
local shelf(++Name, +Init)

   Create a named shelf object which can store data across failures

Arguments
   Name                An atom, or an atom/integer structure
   Init                A structure

Type
   Non-logical Variables, Arrays, Bags, Shelves and Stores

Description
    	This creates a 'shelf' object which can be used to store
	information across failures.  A typical application is counters
	for statistics, 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 can be referred to either by handle or by name. Whenever
	possible, handles should be used, because this naturally leads to
	robust, reentrant code, and avoids the danger of memory leaks.
	See shelf_create/2,3 for how to create shelves with a handle.

	Named shelves are identified by a functor. This is usually simply
	an atom, but in general it can be name/arity pair.

	When named shelves are used, the visibility of the shelf name is
	local to the module where it was created. A named shelf never
	disappears, therefore, in order to free the associated memory,
	its contents should be erased when no longer needed.

	Duplicate shelf declarations are silently ignored.
    

Modes and Determinism
   shelf(++, +) is det

Exceptions
     4 --- Name or Init is uninstantiated
     5 --- Init is not a structure
     5 --- Name is neither an atom nor an atom/integer structure

Examples
   

    % A store with the simple, atomic name 'counters'

    :- local shelf(counters, count(0,0,0)).

    main :-
	shelf_get(counters,1,N0), N1 is N0+1, shelf_set(counters,1,N1),
	printf("main has been called %d times%n", [N1]).
    

See Also
   shelf_create / 2, shelf_create / 3, local / 1, shelf_set / 3, shelf_get / 3, store_delete / 2, store_contains / 2, stored_keys / 2, stored_keys_and_values / 2, store_erase / 1, store_count / 2
