Shelves

## 9.3 Shelves

A shelf is an anonymous object which can be used to store information across failures. A typical application is counting of solutions, keeping track of the best solution, aggregating information across multiple solutions etc.
A shelf is an object with multiple slots whose contents survive backtracking. The content of each slot can be set and retrieved individually, or the whole shelf can be retrieved as a term.
Shelves are referred to by handle, not by name, so they make it easy to write robust, reentrant code. A shelf disappears when the system backtracks over its creation, when the shelf handle gets garbage collected, or when it is explicitly destroyed.
A shelf is initialised using shelf_create/2 or shelf_create/3. Data is stored in the slots (or the shelf as a whole) with shelf_set/3 and retrieved with shelf_get/3.
Example: Counting how many solutions a goal has:

        count_solutions(Goal, Total) :-
            shelf_create(count(0), Shelf),
            (
                call(Goal),
                shelf_get(Shelf, 1, Old),
                New is Old + 1,
                shelf_set(Shelf, 1, New),
                fail
            ;
                shelf_get(Shelf, 1, Total)
            ).

In this particular example, we could have used shelf_inc/2 to increment the counter.