
getref(+Name, -Value)

   Gets the value of the named reference.

Arguments
   Name                Atom (name of a reference).
   Value               Output variable.

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

Description
   If Name is the name of a (previously declared) reference, the value
   it refers to will be unified with Value.

   A named reference can be used to hold a reference to a term, in the
   same way as a logical variable.  Unlike a logical variable, the
   reference has a name under which it can be looked up.  Its value is
   not a copy, but a reference to the value it was set to.  This implies
   that the value behaves logically, i.e. it disappears on backtracking,
   bindings to the variables inside it are undone on backtracking etc.

   A reference that has never been set (or whose settings were
   all undone by backtracking) has its declared initialization value.

   Reference names are visible in the module where they are declared.
   Furthermore every ECLiPSe engine has its own reference store,
   meaning that the values are engine/thread-local and cannot be shared.


Modes and Determinism
   getref(+, -) is det

Modules
   This predicate is sensitive to its module context (tool predicate, see @/2).

Exceptions
     4 --- Name is uninstantiated
     5 --- Name is not an atom.
    45 --- Name has not been declared as a reference.

Examples
   
    ?- local reference(r, hello).
    Yes (0.00s cpu)

    ?- getref(r,X), setref(r,world), getref(r,Y).
    X = hello
    Y = world
    Yes (0.00s cpu)

    ?- getref(r,X), ( setref(r,world), fail ; getref(r,Y) ).      
    X = hello
    Y = hello
    Yes (0.00s cpu)


% Example: maintain a complex global state

    :- local reference(state, _).

    get_state(S) :-
        getref(state, S),
        ( var(S) ->
            % Initialise the state to some term
            writeln(initializing),
            S = complex_state(123, [4,5], _)
        ;
            writeln(accessing)
        ).

    ?- get_state(S1), get_state(S2), S1==S2.
    initializing
    accessing
    S1 = complex_state(123, [4, 5], _316)
    S2 = complex_state(123, [4, 5], _316)
    Yes (0.00s cpu)



See Also
   reference / 2, setref / 2, swapref / 3
