This section describes passing Prolog terms to a foreign function and receiving Prolog terms from a foreign function. For the current release this interface is supported only for C.
There is a difference between passing atomic objects (atoms, floats,
db_reference and integers) and generic Prolog terms through the
foreign interface. Generic Prolog terms passed to a C function (using
+term) are not converted to any representation in C. Instead the
foreign function in C gets a reference to the Prolog term, which is of
QP_term_ref (defined in
Similarly when a generic term is returned (using
from a foreign function there is no conversion of any data structures
in the foreign language into an equivalent Prolog representation. The
foreign function has to return a reference to a Prolog term, which it
originally got from Prolog or from one of the functions/macros
provided to manipulate Prolog terms such as the
QP_cons* families of functions.
When Prolog terms are referred to from C, what the C function holds is an indirect reference to the Prolog term. There is a reason for this indirection. Prolog terms live in the Prolog global stack, and migrate when Prolog does garbage collection or stack shifting. If the C function held onto a direct reference to a Prolog term it would become invalid after one of these memory management operations. Prolog cannot update and relocate these references that C is holding onto since it is impossible to distinguish between Prolog references and other integers and pointers that C holds onto.
The C code should also be aware of the scope (or lifetime) of the references to Prolog terms passed to it. Once you return to Prolog from a call to a foreign function, all the references to Prolog terms passed to the foreign function are invalid. All references to terms created by the foreign function are also invalid.
WARNING: You should not store references to prolog terms into global variables in the foreign language.
The scope of references to terms are more restricted when C calls Prolog.
If Prolog returns a term as a result of a C call to a Prolog predicate,
that term is valid only till the call for the next solution from that
Prolog predicate (using
This also holds true for terms created in C. If you create a term after one
call to a Prolog predicate then the reference to that term is only valid
till the call for next solution from that Prolog predicate.