shelf_create(++ShelfSpec, ?SlotInit, -ShelfHandle)

Create a shelf object which can store data across failures

ShelfSpec

A term of the form Name/Arity

SlotInit

The value used to initialize the slots (any term)

ShelfHandle

A free variable

Description

This creates a 'shelf' 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.

When using shelf_create/3, ShelfSpec determines the number of
slots on the shelf, and all slots get initialized identically
with the value SlotInit.

Modes and Determinism

shelf_create(++, ?, -) is det

Exceptions

(4) instantiation fault

ShelfSpec is not fully instantiated

(5) type error

ShelfSpec is fully instantiated but not to a term of the form Atom/Integer