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)
).