5.5.1 Type term_t: a reference to a Prolog term

The principal data-type is term_t. Type term_t is what Quintus calls QP_term_ref. This name indicates better what the type represents: it is a handle for a term rather than the term itself. Terms can only be represented and manipulated using this type, as this is the only safe way to ensure the Prolog kernel is aware of all terms referenced by foreign code and thus allows the kernel to perform garbage-collection and/or stack-shifts while foreign code is active, for example during a callback from C.

A term reference is a C unsigned long, representing the offset of a variable on the Prolog environment-stack. A foreign function is passed term references for the predicate-arguments, one for each argument. If references for intermediate results are needed, such references may be created using PL_new_term_ref() or PL_new_term_refs(). These references normally live till the foreign function returns control back to Prolog. Their scope can be explicitly limited using PL_open_foreign_frame() and PL_close_foreign_frame()/PL_discard_foreign_frame().

A term_t always refers to a valid Prolog term (variable, atom, integer, float or compound term). A term lives either until backtracking takes us back to a point before the term was created, the garbage collector has collected the term or the term was created after a PL_open_foreign_frame() and PL_discard_foreign_frame() has been called.

The foreign-interface functions can either read, unify or write to term-references. In the this document we use the following notation for arguments of type term_t:

term_t +t	Accessed in read-mode. The `+' indicates the argument is `input'.
term_t -t	Accessed in write-mode.
term_t ?t	Accessed in unify-mode.

Term references are obtained in any of the following ways.

• Passed as argument
  The C-functions implementing foreign predicates are passed their arguments as term-references. These references may be read or unified. Writing to these variables causes undefined behaviour.
• Created by PL_new_term_ref()
  A term created by PL_new_term_ref() is normally used to build temporary terms or be written by one of the interface functions. For example, PL_get_arg() writes a reference to the term-argument in its last argument.
• Created by PL_new_term_refs(int n)
  This function returns a set of term refs with the same characteristics as PL_new_term_ref(). See PL_open_query().
• Created by PL_copy_term_ref(term_t t)
  Creates a new term-reference to the same term as the argument. The term may be written to. See figure 8.

Term-references can safely be copied to other C-variables of type term_t, but all copies will always refer to the same term.

term_t PL_new_term_ref()

Return a fresh reference to a term. The reference is allocated on the local stack. Allocating a term-reference may trigger a stack-shift on machines that cannot use sparse-memory management for allocation the Prolog stacks. The returned reference describes a variable.

term_t PL_new_term_refs(int n)

Return n new term references. The first term-reference is returned. The others are t+1, t+2, etc. There are two reasons for using this function. PL_open_query() expects the arguments as a set of consecutive term references and very time-critical code requiring a number of term-references can be written as:

pl_mypredicate(term_t a0, term_t a1) { term_t t0 = PL_new_term_refs(2); term_t t1 = t0+1; ... }

term_t PL_copy_term_ref(term_t from)

Create a new term reference and make it point initially to the same term as from. This function is commonly used to copy a predicate argument to a term reference that may be written.

• 5.5.1.1 Interaction with the garbage collector and stack-shifter