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.
A new SP_term_ref is created by calling
An SP_term_ref can be assigned the value of another SP_term_ref
It is important to understand the rules governing the scope of SP_term_refs, and the terms they hold, in conjunction with calls from Prolog to C and vice versa. This is explained in Finding Multiple Solutions of a Call.