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.
?- 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)