Normally, C functions only have indirect access to Prolog terms
via SP_term_refs. C functions may receive arguments as
unconverted Prolog terms, in which case the actual arguments
received will have the type
SP_term_ref. Also, a C function may
return an unconverted Prolog term, in which case it must create an
SP_term_ref. Finally, any temporary Prolog terms created by
C code must be handled as SP_term_refs.
SP_term_refs are motivated by the fact that SICStus Prolog's memory manager must have a means of reaching all live Prolog terms for memory management purposes, including such terms that are being manipulated by the user's C code. Previous releases provided direct access to Prolog terms and the ability to tell the memory manager that a given memory address points to a Prolog term, but this approach was too low level and highly error-prone. The current design is modeled after and largely compatible with Quintus Prolog release 3.
SP_term_refs are created dynamically. At any given time, an
SP_term_ref has a value (a Prolog term, initially
). This value can be examined, accessed, and updated by the
support functions described in this section.
It is important to understand the rules governing the scope of SP_term_refs in conjunction with calls from Prolog to C and vice versa:
A new SP_term_ref is created by calling
An SP_term_ref can be assigned the value of another SP_term_ref