[ Non-logical Variables, Arrays, Bags, Shelves and Stores | Reference Manual | Alphabetic Index ]

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

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
(5) type error
ShelfHandle is not a variable

Examples

% finding the sum and maximum of data/1 facts:

    data(2).
    data(9).
    data(3).
    data(5).
    data(7).

    sum_and_max(Sum, Max) :-
    	shelf_create(agg/2, 0, Shelf),
	(
	    data(X),
	    shelf_get(Shelf, 1, OldMax),
	    ( X > OldMax -> shelf_set(Shelf, 1, X) ; true ),
	    shelf_get(Shelf, 2, OldSum),
	    NewSum is OldSum + X,
	    shelf_set(Shelf, 2, NewSum),
	    fail
	;
	    shelf_get(Shelf, 0, agg(Max, Sum))
	),
	shelf_abolish(Shelf).
    

See Also

shelf_create / 2, shelf_set / 3, shelf_get / 3, shelf_abolish / 1