Referring to ECLiPSe terms from C

## C.3 Referring to ECLiPSe terms from C

The data types ec_refs and ec_ref provide a means to have non-volatile references to ECLiPSe data from within C data structures. However, it must be kept in mind that ECLiPSe data structures are nevertheless subject to backtracking, which means they may be reset to an earlier status when the search engine requires it. Creating a reference to a data structure does not change that in any way. In particular, when the search engine fails beyond the state where the reference was set up, the reference disappears and is also reset to its earlier value.

ec_refs ec_refs_create(int n,const pword pw)
  create a data structure capable of holding n non-volatile references to ECLiPSe data items. They are initialised with the value pw, which must be of a simple type.
ec_refs ec_refs_create_newvars(int)
  like ec_refs_create(), but each item is initialised to a freshly created ECLiPSe variable.
void ec_refs_destroy(ec_refs)
  destroy the ECLiPSe references. It is important that this is done, otherwise the ECLiPSe garbage collector will not be able to free the references data structures, which may eventually lead to memory overflow.
void ec_refs_set(ec_refs,int i,const pword pw)
  set the i’th reference to the ECLiPSe term pw. This setting is subject to the ECLiPSe engine’s undo-mechanism on backtracking.
pword ec_refs_get(const ec_refs,int i)
  return the ECLiPSe term referred to by the i’th reference.
int ec_refs_size(const ec_refs)
  return the capacity of the ec_refs data structure.
ec_ref ec_ref_create(pword)
  like ec_refs_create() for a single reference.
ec_ref ec_ref_create_newvar()
  analogous to ec_refs_create_newvars().
void ec_ref_destroy(ec_ref)
  analogous to ec_refs_destroy().
void ec_ref_set(ec_ref,const pword)
  analogous to ec_refs_set().
pword ec_ref_get(const ec_ref)
  analogous to ec_refs_get().