Referring to ECLiPSe terms

## 3.3 Referring to ECLiPSe terms

The terms constructed so far (as EC-words) have been volatile, that is they do not survive an ECLiPSe execution (due to eg. garbage collection), It is possible to create safe terms that have been registered with the ECLiPSe engine and which do survive execution. The `EC_ref` and `EC_refs` classes are provided for this purpose. `EC_refs` are vectors of safe terms.

When you declare an `EC_ref` it will contain free variables.

    EC_ref X; /* declare one free variable */
    EC_refs Tasks(10); /* declare 10 free variables */

`EC_ref`s work like logical variables. When ECLiPSe fails during search they are reset to old values. They are always guaranteed to refer to something i.e. they never contain dangling references. If ECLiPSe backtracks to a point in the execution older than the point at which the references were created, they return to being free variables, or take on their initial values.

It is possible to declare references, giving them an initialiser but this must be an atomic type that fits into a single word. That restricts you to atoms, integers and nil.

You can freely assign between an `EC_ref` and a `EC_word`.

One point to take care of is that assigning such a variable is not like unification since assignment cannot fail. It just overwrites the old value. Assignment is very similar to the setarg/3 built-in in the ECLiPSe language.