10.19.6.1 Lifetime of SPTerms and Prolog Memory

There are three separate memory areas involved when manipulating Prolog terms from Java using SPTerm objects. These areas have largely independent life times.

1. The SPTerm object itself.
2. Creating SPTerm object also tells Prolog to allocate an SP_term_ref. SP_term_refs have a life-time that is independent of the lifetime of the corresponding SPTerm object.
3. Any Prolog terms allocated on the global stack. An SPTerm refer to a Prolog term indirectly via a SP_term_ref.

A SP_term_ref ref (created as a side effect of creating a SPTerm object) will be reclaimed if either:

• Java returns to Prolog. This may never happen, especially if Java is the top-level application.
• Assume there exists a still open query q that was opened before the SP_term_ref ref was created. The SP_term_ref ref will be reclaimed if the query q is closed (using q.close() or q.cut()) or if q.nextSolution() is called.

An SPTerm object will be invalidated (and eventually reclaimed by the garbage collector) if the corresponding SP_term_ref is reclaimed as above. If passed an invalidated SP_term_ref, then most methods will throw an IllegalTermException exception.

A Prolog term (allocated on the global stack) will be deallocated when:

• Assume there exists a still open query q that was opened before the term was created. The memory of the term will be reclaimed if the query q is closed using q.close() or if q.nextSolution() is called. The memory is not reclaimed if the query is closed with q.cut().

Please note: it is possible to get a SPTerm object and its SP_term_ref to refer to deallocated Prolog terms, in effect creating “dangling” pointers in cases where the SPTerm would ordinarily still be valid. This will be detected and invalidate the SPTerm:

{
  SPTerm old = new SPTerm(sp);
  SPQuery q;

  q = sp.openQuery(….);
  …
  old.consFunctor(…);  // allocate a Prolog term newer than q
  …
  q.nextSolution(); // or q.close()
  // error: 
  // The SP_term_ref in q refers to an invalid part of the global stack
  // the SPTerm old will be invalidated by q.nextSolution()
}