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

# local shelf(++Name, +Init)

Create a named shelf object which can store data across failures

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

## 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) instantiation fault
  Name or Init is uninstantiated
(5) type error
  Init is not a structure
(5) type error
  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