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

getref(+Name, -Value)

Gets the value of the named reference.
Name
Atom (name of a reference).
Value
Output variable.

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. Unlike a named non-logical variable, the value of a reference is not a copy, but identical to the original term 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.

Changing the value of a reference is similar to changing an argument of a compound term using setarg/3. The change is undone on backtracking, i.e. the value of the reference reverts to what it was before being changed. 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

Modules

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

Exceptions

(4) instantiation fault
Name is uninstantiated
(5) type error
Name is not an atom.
(45) named object does not exist
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)

See Also

reference / 2, setref / 2