5.6 The Foreign Include File

5.6.1 Argument Passing and Control

If Prolog encounters a foreign predicate at run time it will call a function specified in the predicate definition of the foreign predicate. The arguments 1, ... , <arity> pass the Prolog arguments to the goal as Prolog terms. Foreign functions should be declared of type foreign_t. Deterministic foreign functions have two alternatives to return control back to Prolog:

void PL_succeed()

Succeed deterministically. PL_succeed is defined as return TRUE.

void PL_fail()

Fail and start Prolog backtracking. PL_fail is defined as return FALSE.

5.6.1.1 Non-deterministic Foreign Predicates

By default foreign predicates are deterministic. Using the PL_FA_NONDETERMINISTIC attribute (see PL_register_foreign()) it is possible to register a predicate as a non-deterministic predicate. Writing non-deterministic foreign predicates is slightly more complicated as the foreign function needs context information for generating the next solution. Note that the same foreign function should be prepared to be simultaneously active in more than one goal. Suppose the natural_number_below_n/2 is a non-deterministic foreign predicate, backtracking over all natural numbers lower than the first argument. Now consider the following predicate:

In this predicate the function natural_number_below_n/2 simultaneously generates solutions for both its invocations.

Non-deterministic foreign functions should be prepared to handle three different calls from Prolog:

• Initial call (PL_FIRST_CALL)
  Prolog has just created a frame for the foreign function and asks it to produce the first answer.
• Redo call (PL_REDO)
  The previous invocation of the foreign function associated with the current goal indicated it was possible to backtrack. The foreign function should produce the next solution.
• Terminate call (PL_CUTTED)
  The choice point left by the foreign function has been destroyed by a cut. The foreign function is given the opportunity to clean the environment.

Both the context information and the type of call is provided by an argument of type control_t appended to the argument list for deterministic foreign functions. The macro PL_foreign_control() extracts the type of call from the control argument. The foreign function can pass a context handle using the PL_retry*() macros and extract the handle from the extra argument using the PL_foreign_context*() macro.

void PL_retry(long)

The foreign function succeeds while leaving a choice point. On backtracking over this goal the foreign function will be called again, but the control argument now indicates it is a `Redo' call and the macro PL_foreign_context() will return the handle passed via PL_retry(). This handle is a 30 bits signed value (two bits are used for status indication).

void PL_retry_address(void *)

As PL_retry(), but ensures an address as returned by malloc() is correctly recovered by PL_foreign_context_address().

int PL_foreign_control(control_t)

Extracts the type of call from the control argument. The return values are described above. Note that the function should be prepared to handle the PL_CUTTED case and should be aware that the other arguments are not valid in this case.

long PL_foreign_context(control_t)

Extracts the context from the context argument. In the call type is PL_FIRST_CALL the context value is 0L. Otherwise it is the value returned by the last PL_retry() associated with this goal (both if the call type is PL_REDO as PL_CUTTED).

void * PL_foreign_context_address(control_t)

Extracts an address as passed in by PL_retry_address().

Note: If a non-deterministic foreign function returns using PL_succeed or PL_fail, Prolog assumes the foreign function has cleaned its environment. No call with control argument PL_CUTTED will follow.

The code of figure 6 shows a skeleton for a non-deterministic foreign predicate definition.

5.6.2 Atoms and functors

The following functions provide for communication using atoms and functors.

atom_t PL_new_atom(const char *)

Return an atom handle for the given C-string. This function always succeeds. The returned handle is valid for the entire session.

const char * PL_atom_chars(atom_t atom)

Return a C-string for the text represented by the given atom. The returned text will not be changed by Prolog. It is not allowed to modify the contents, not even `temporary' as the string may reside in read-only memory.

functor_t PL_new_functor(atom_t name, int arity)

Returns a functor identifier, a handle for the name/arity pair. The returned handle is valid for the entire Prolog session.

atom_t PL_functor_name(functor_t f)

Return an atom representing the name of the given functor.

int PL_functor_arity(functor_t f)

Return the arity of the given functor.

5.6.3 Analysing Terms via the Foreign Interface

Each argument of a foreign function (except for the control argument) is of type term_t, an opaque handle to a Prolog term. Three groups of functions are available for the analysis of terms. The first just validates the type, like the Prolog predicates var/1, atom/1, etc and are called PL_is_*(). The second group attempts to translate the argument into a C primitive type. These predicates take a term_t and a pointer to the appropriate C-type and return TRUE or FALSE depending on successful or unsuccessful translation. If the translation fails, the pointed-to data is never modified.

5.6.3.1 Testing the type of a term

int PL_term_type(term_t)

Obtain the type of a term, which should be a term returned by one of the other interface predicates or passed as an argument. The function returns the type of the Prolog term. The type identifiers are listed below. Note that the extraction functions PL_ge_t*() also validate the type and thus the two sections below are equivalent.

if ( PL_is_atom(t) ) { char *s; PL_get_atom_chars(t, &s); ...; } or char *s; if ( PL_get_atom_chars(t, &s) ) { ...; }

PL_VARIABLE	An unbound variable. The value of term as such is a unique identifier for the variable.
PL_ATOM	A Prolog atom.
PL_STRING	A Prolog string.
PL_INTEGER	A Prolog integer.
PL_FLOAT	A Prolog floating point number.
PL_TERM	A compound term. Note that a list is a compound term ./2 .

The functions PL_is_<type> are an alternative to PL_term_type(). The test PL_is_variable(term) is equivalent to PL_term_type(term) == PL_VARIABLE, but the first is considerably faster. On the other hand, using a switch over PL_term_type() is faster and more readable then using an if-then-else using the functions below. All these functions return either TRUE or FALSE.

int PL_is_variable(term_t)

Returns non-zero if term is a variable.

int PL_is_atom(term_t)

Returns non-zero if term is an atom.

int PL_is_string(term_t)

Returns non-zero if term is a string.

int PL_is_integer(term_t)

Returns non-zero if term is an integer.

int PL_is_float(term_t)

Returns non-zero if term is a float.

int PL_is_compound(term_t)

Returns non-zero if term is a compound term.

int PL_is_functor(term_t, functor_t)

Returns non-zero if term is compound and its functor is functor. This test is equivalent to PL_get_functor(), followed by testing the functor, but easier to write and faster.

int PL_is_list(term_t)

Returns non-zero if term is a compound term with functor ./2 or the atom .

int PL_is_atomic(term_t)

Returns non-zero if term is atomic (not variable or compound).

int PL_is_number(term_t)

Returns non-zero if term is an integer or float.

5.6.3.2 Reading data from a term

The functions PL_get_*() read information from a Prolog term. Most of them take two arguments. The first is the input term and the second is a pointer to the output value or a term-reference.

int PL_get_atom(term_t +t, atom_t *a)

If t is an atom, store the unique atom identifier over a. See also PL_atom_chars() and PL_new_atom(). If there is no need to access the data (characters) of an atom, it is advised to manipulate atoms using their handle.

int PL_get_atom_chars(term_t +t, char **s)

If t is an atom, store a pointer to a 0-terminated C-string in s. It is explicitly not allowed to modify the contents of this string. Some built-in atoms may have the string allocated in read-only memory, so `temporary manipulation' can cause an error.

int PL_get_string(term_t +t, char **s, int *len)

If t is a string object, store a pointer to a 0-terminated C-string in s and the length of the string in len. Note that this pointer is invalidated by backtracking, garbage-collection and stack-shifts, so generally the only save operations are to pass it immediately to a C-function that doesn't involve Prolog.

int PL_get_chars(term_t +t, char **s, unsigned flags)

Convert the argument term t to a 0-terminated C-string. flags is a bitwise disjunction from two groups of constants. The first specifies which term-types should converted and the second how the argument is stored. Below is a specification of these constants. BUF_RING implies, if the data is not static (as from an atom), the data is copied to the next buffer from a ring of four (4) buffers. This is a convenient way of converting multiple arguments passed to a foreign predicate to C-strings. If BUF_MALLOC is used, the data must be freed using free() when not needed any longer.

CVT_ATOM	Convert if term is an atom
CVT_STRING	Convert if term is a string
CVT_LIST	Convert if term is a list of integers between 1 and 255
CVT_INTEGER	Convert if term is an integer (using %d)
CVT_FLOAT	Convert if term is a float (using %f)
CVT_NUMBER	Convert if term is a integer or float
CVT_ATOMIC	Convert if term is atomic
CVT_VARIABLE	Convert variable to print-name
CVT_ALL	Convert if term is any of the above, except for variables
BUF_DISCARDABLE	Data must copied immediately
BUF_RING	Data is stored in a ring of buffers
BUF_MALLOC	Data is copied to a new buffer returned by malloc(3)

int PL_get_list_chars(+term_t l, char **s, unsigned flags)

Same as PL_get_chars(l, s, CVT_LIST|flags), provided flags contains no of the CVT_* flags.

int PL_get_integer(+term_t t, int *i)

If t is a Prolog integer, assign its value over i. On 32-bit machines, this is the same as PL_get_long(), but avoids a warning from the compiler. See also PL_get_long().

int PL_get_long(term_t +t, long *i)

If t is a Prolog integer, assign its value over i. Note that Prolog integers have limited value-range. If t is a floating point number that can be represented as a long, this function succeeds as well.

int PL_get_pointer(term_t +t, void **ptr)

In the current system, pointers are represented by Prolog integers, but need some manipulation to make sure they do not get truncated due to the limited Prolog integer range. PL_put_pointer()/PL_get_pointer() guarantees pointers in the range of malloc() are handled without truncating.

int PL_get_float(term_t +t, double *f)

If t is a float or integer, its value is assigned over f.

int PL_get_functor(term_t +t, functor_t *f)

If t is compound or an atom, the Prolog representation of the name-arity pair will be assigned over f. See also PL_get_name_arity() and PL_is_functor().

int PL_get_name_arity(term_t +t, atom_t *name, int *arity)

If t is compound or an atom, the functor-name will be assigned over name and the arity over arity. See also PL_get_functor() and PL_is_functor().

int PL_get_module(term_t +t, module_t *module)

If t is an atom, the system will lookup or create the corresponding module and assign an opaque pointer to it over module,.

int PL_get_arg(int index, term_t +t, term_t -a)

If t is compound and index is between 1 and arity (including), assign a with a term-reference to the argument.

int _PL_get_arg(int index, term_t +t, term_t -a)

Same as PL_get_arg(), but no checking is performed, nor whether t is actually a term, nor whether index is a valid argument-index.

5.6.3.3 Reading a list

The functions from this section are intended to read a Prolog list from C. Suppose we expect a list of atoms, the following code will print the atoms, each on a line:

int PL_get_list(term_t +l, term_t -h, term_t -t)

If l is a list and not assign a term-reference to the head to h and to the tail to t.

int PL_get_head(term_t +l, term_t -h)

If l is a list and not assign a term-reference to the head to h.

int PL_get_tail(term_t +l, term_t -t)

If l is a list and not assign a term-reference to the tail to t.

int PL_get_nil(term_t +l)

Succeeds if represents the atom .

5.6.3.4 An example: defining write/1 in C

Figure 7 shows a simplified definition of write/1 to illustrate the described functions. This simplified version does not deal with operators. It is called display/1, because it mimics closely the behaviour of this Edinburgh predicate.

5.6.4 Constructing Terms

Terms can be constructed using functions from the PL_put_*() and PL_cons_*() families. This approach builds the term `inside-out', starting at the leaves and subsequently creating compound terms. Alternatively, terms may be created `top-down', first creating a compound holding only variables and subsequently unifying the arguments. This section discusses functions for the first approach. This approach is generally used for creating arguments for PL_call() and PL_open_query.

void PL_put_variable(term_t -t)

Put a fresh variable in the term. The new variable lives on the global stack. Note that the initial variable lives on the local stack and is lost after a write to the term-references. After using this function, the variable will continue to live.

void PL_put_atom(term_t -t, atom_t a)

Put an atom in the term reference from a handle. See also PL_new_atom() and PL_atom_chars().

void PL_put_atom_chars(term_t -t, const char *chars)

Put an atom in the term-reference constructed from the 0-terminated string. The string itself will never be references by Prolog after this function.

void PL_put_string_chars(term_t -t, const char *chars)

Put a zero-terminated string in the term-reference. The data will be copied. See also PL_put_string_nchars().

void PL_put_string_nchars(term_t -t, unsigned int len, const char *chars)

Put a string, represented by a length/start pointer pair in the term-reference. The data will be copied. This interface can deal with 0-bytes in the string. See also section 5.6.17.

void PL_put_list_chars(term_t -t, const char *chars)

Put a list of ASCII values in the term-reference.

void PL_put_integer(term_t -t, long i)

Put a Prolog integer in the term reference.

void PL_put_pointer(term_t -t, void *ptr)

Put a Prolog integer in the term-reference. Provided ptr is in the `malloc()-area', PL_get_pointer() will get the pointer back.

void PL_put_float(term_t -t, double f)

Put a floating-point value in the term-reference.

void PL_put_functor(term_t -t, functor_t functor)

Create a new compound term from functor and bind t to this term. All arguments of the term will be variables. To create a term with instantiated arguments, either instantiate the arguments using the PL_unify_*() functions or use PL_cons_functor().

void PL_put_list(term_t -l)

Same as PL_put_functor(l, PL_new_functor(PL_new_atom("."), 2)).

void PL_put_nil(term_t -l)

Same as PL_put_atom_chars("[]").

void PL_put_term(term_t -t1, term_t +t2)

Make t1 point to the same term as t2.

void PL_cons_functor(term_t -h, functor_t f, ...)

Create a term, whose arguments are filled from variable argument list holding the same number of term_t objects as the arity of the functor. To create the term animal(gnu, 50), use:

term_t a1 = PL_new_term_ref(); term_t a2 = PL_new_term_ref(); term_t t = PL_new_term_ref(); PL_put_atom_chars(a1, "gnu"); PL_put_integer(a2, 50); PL_cons_functor(t, PL_new_functor(PL_new_atom("animal"), 2), a1, a2);

After this sequence, the term-references a1 and a2 may be used for other purposes.

void PL_cons_functor_v(term_t -h, functor_t f, term_t a0)

Creates a compound term like PL_cons_functor(), but a0 is an array of term references as returned by PL_new_term_refs(). The length of this array should match the number of arguments required by the functor.

void PL_cons_list(term_t -l, term_t +h, term_t +t)

Create a list (cons-) cell in l from the head and tail. The code below creates a list of atoms from a char **. The list is built tail-to-head. The PL_unify_*() functions can be used to build a list head-to-tail.

void put_list(term_t l, int n, char **words) { term_t a = PL_new_term_ref(); PL_put_nil(l); while( --n >= 0 ) { PL_put_atom_chars(a, words[n]); PL_cons_list(l, a, l); } }

Note that l can be redefined within a PL_cons_list call as shown here because operationally its old value is consumed before its new value is set.

5.6.5 Unifying data

The functions of this sections unify terms with other terms or translated C-data structures. Except for PL_unify(), the functions of this section are specific to SWI-Prolog. They have been introduced to make translation of old code easier, but also because they provide for a faster mechanism for returning data to Prolog that requires less term-references. Consider the case where we want a foreign function to return the host name of the machine Prolog is running on. Using the PL_get_*() and PL_put_*() functions, the code becomes:

Using PL_unify_atom_chars(), this becomes:

int PL_unify(term_t ?t1, term_t ?t2)

Unify two Prolog terms and return non-zero on success.

int PL_unify_atom(term_t ?t, atom_t a)

Unify t with the atom a and return non-zero on success.

int PL_unify_atom_chars(term_t ?t, const char *chars)

Unify t with an atom created from chars and return non-zero on success.

int PL_unify_list_chars(term_t ?t, const char *chars)

Unify t with a list of ASCII characters constructed from chars.

void PL_unisy_string_chars(term_t ?t, const char *chars)

Unify t with a Prolog string object created from the zero-terminated string chars. The data will be copied. See also PL_put_string_nchars().

void PL_put_string_nchars(term_t ?t, unsigned int len, const char *chars)

Unify t with a Prolog string object created from the string created from the len/chars pair. The data will be copied. This interface can deal with 0-bytes in the string. See also section 5.6.17.

int PL_unify_integer(term_t ?t, long n)

Unify t with a Prolog integer from n.

int PL_unify_float(term_t ?t, double f)

Unify t with a Prolog float from f.

int PL_unify_pointer(term_t ?t, void *ptr)

Unify t with a Prolog integer describing the pointer. See also PL_put_pointer() and PL_get_pointer().

int PL_unify_functor(term_t ?t, functor_t f)

If t is a compound term with the given functor, just succeed. If it is unbound, create a term and bind the variable, else fails. Not that this function does not create a term if the argument is already instantiated.

int PL_unify_list(term_t ?l, term_t -h, term_t -t)

Unify l with a list-cell (./2). If successful, write a reference to the head of the list to h and a reference to the tail of the list in t. This reference may be used for subsequent calls to this function. Suppose we want to return a list of atoms from a char **. We could use the example described by PL_put_list(), followed by a call to PL_unify(), or we can use the code below. If the predicate argument is unbound, the difference is minimal (the code based on PL_put_list() is probably slightly faster). If the argument is bound, the code below may fail before reaching the end of the word-list, but even if the unification succeeds, this code avoids a duplicate (garbage) list and a deep unification.

foreign_t pl_get_environ(term_t env) { term_t l = PL_copy_term_ref(env); term_t a = PL_new_term_ref(); extern char **environ; char **e; for(e = environ; *e; e++) { if ( !PL_unify_list(l, a, l) || !PL_unify_atom_chars(a, *e) ) PL_fail; } return PL_unify_nil(l); }

int PL_unify_nil(term_t ?l)

Unify l with the atom .

int PL_unify_arg(int index, term_t ?t, term_t ?a)

Unifies the index-th argument (1-based) of t with a.

int PL_unify_term(term_t ?t, ...)

Unify t with a (normally) compound term. The remaining arguments is a sequence of a type identifier, followed by the required arguments. This predicate is an extension to the Quintus and SICStus foreign interface from which the SWI-Prolog foreign interface has been derived, but has proved to be a powerful and comfortable way to create compound terms from C. Due to the vararg packing/unpacking and the required type-switching this interface is slightly slower than using the primitives. Please note that some bad C-compilers have fairly low limits on the number of arguments that may be passed to a function.

The type identifiers are:

PL_VARIABLE none

No op. Used in arguments of PL_FUNCTOR.

PL_ATOM atom_t

Unify the argument with an atom, as in PL_unify_atom().

PL_INTEGER long

Unify the argument with an integer, as in PL_unify_integer().

PL_FLOAT double

Unify the argument with a float, as in PL_unify_float(). Note that, as the argument is passed using the C vararg conventions, a float must be casted to a double explicitly.

PL_STRING const char *

Unify the argument with a string object, as in PL_unify_string_chars().

PL_TERM term_t

Unify a subterm. Note this may the return value of a PL_new_term_ref() call to get access to a variable.

PL_CHARS const char *

Unify the argument with an atom, constructed from the C char *, as in PL_unify_atom_chars().

PL_FUNCTOR functor_t, ...

Unify the argument with a compound term. This specification should be followed by exactly as many specifications as the number of arguments of the compound term.

PL_LIST int length, ...

Create a list of the indicated length. The following arguments contain the elements of the list.

For example, to unify an argument with the term language(dutch), the following skeleton may be used:

static functor_t FUNCTOR_language1; static void init_constants() { FUNCTOR_language1 = PL_new_functor(PL_new_atom("language"), 1); } foreign_t pl_get_lang(term_t r) { return PL_unify_term(r, PL_FUNCTOR, FUNCTOR_language1, PL_CHARS, "dutch"); } install_t install() { PL_register_foreign("get_lang", 1, pl_get_lang, 0); init_constants(); }

5.6.6 Calling Prolog from C

The Prolog engine can be called from C. There are to interfaces for this. For the first, a term is created that could be used as an argument to call/1 and next PL_call() is used to call Prolog. This system is simple, but does not allow to inspect the different answers to a non-deterministic goal and is relatively slow as the runtime system needs to find the predicate. The other interface is based on PL_open_query(), PL_next_solution() and PL_cut_query() or PL_close_query(). This mechanism is more powerful, but also more complicated to use.

5.6.6.1 Predicate references

This section discusses the functions used to communicate about predicates. Though a Prolog predicate may defined or not, redefined, etc., a Prolog predicate has a handle that is not destroyed, nor moved. This handle is known by the type predicate_t.

predicate_t PL_pred(functor_t f, module_t m)

Return a handle to a predicate for the specified name/arity in the given module. This function always succeeds, creating a handle for an undefined predicate if no handle was available.

predicate_t PL_predicate(const char *name, int arity, const char* module)

Same a PL_pred(), but provides a more convenient interface to the C-programmer.

void PL_predicate_info(predicate_t p, atom_t *n, int *a, module_t *m)

Return information on the predicate p. The name is stored over n, the arity over a, while m receives the definition module. Note that the latter need not be the same as specified with PL_predicate(). If the predicate was imported into the module given to PL_predicate(), this function will return the module where the predicate was defined.

5.6.6.2 Initiating a query from C

This section discusses the functions for creating and manipulating queries from C. Note that a foreign context can have at most one active query. This implies it is allowed to make strictly nested calls between C and Prolog (Prolog calls C, calls Prolog, calls C, etc., but it is not allowed to open multiple queries and start generating solutions for each of them by calling PL_next_solution(). Be sure to call PL_cut_query() or PL_close_query() on any query you opened before opening the next or returning control back to Prolog.

qid_t PL_open_query(module_t ctx, int flags, predicate_t p, term_t +t0)

Opens a query and returns an identifier for it. This function always succeeds, regardless whether the predicate is defined or not. ctx is the context module of the goal. When NULL, the context module of the calling context will be used, or user if there is no calling context (as may happen in embedded systems). Note that the context module only matters for module_transparent predicates. See context_module/1 and module_transparent/1. The p argument specifies the predicate, and should be the result of a call to PL_pred() or PL_predicate(). Note that it is allowed to store this handle as global data and reuse it for future queries. The term-reference t0 is the first of a vector of term-references as returned by PL_new_term_refs(n).

The flags arguments provides some additional options concerning debugging and exception handling. It is a bitwise or of the following values:

PL_Q_NORMAL

Normal operation. The debugger inherits its settings from the environment. If an exception occurs that is not handled in Prolog, a message is printed and the tracer is started to debug the error. (26)

PL_Q_NODEBUG

Switch off the debugger while executing the goal. This option is used by many calls to hook-predicates to avoid tracing the hooks. An example is print/1 calling portray/1 from foreign code.

PL_Q_CATCH_EXCEPTION

If an exception is raised while executing the goal, do not report it, but make it available for PL_exception().

PL_Q_PASS_EXCEPTION

As PL_Q_CATCH_EXCEPTION, but do not invalidate the exception-term while calling PL_close_query(). This option is experimental.

The example below opens a query to the predicate is_a/2 to find the ancestor of for some name.

char * ancestor(const char *me) { term_t a0 = PL_new_term_refs(2); static predicate_t p; if ( !p ) p = PL_predicate("is_a", 2, "database"); PL_put_atom_chars(a0, me); PL_open_query(NULL, PL_Q_NORMAL, p, a0); ... }

int PL_next_solution(qid_t qid)

Generate the first (next) solution for the given query. The return value is TRUE if a solution was found, or FALSE to indicate the query could not be proven. This function may be called repeatedly until it fails to generate all solutions to the query.

void PL_cut_query(qid)

Discards the query, but does not delete any of the data created by the query. It just invalidate qid, allowing for a new call to PL_open_query() in this context.

void PL_close_query(qid)

As PL_cut_query(), but all data and bindings created by the query are destroyed.

int PL_call_predicate(module_t m, int flags, predicate_t pred, term_t +t0)

Shorthand for PL_open_query(), PL_next_solution(), PL_cut_query(), generating a single solution. The arguments are the same as for PL_open_query(), the return value is the same as PL_next_solution().

int PL_call(term_t, module_t)

Call term just like the Prolog predicate once/1. Term is called in the specified module, or in the context module if module_t = NULL. Returns TRUE if the call succeeds, FALSE otherwise. Figure 8 shows an example to obtain the number of defined atoms. All checks are omitted to improve readability.

5.6.7 Discarding Data

The Prolog data created and term-references needed to setup the call and/or analyse the result can in most cases be discarded right after the call. PL_close_query() allows for destructing the data, while leaving the term-references. The calls below may be used to destroy term-references and data. See figure 8 for an example.

fid_t PL_open_foreign_frame()

Created a foreign frame, holding a mark that allows the system to undo bindings and destroy data created after it as well as providing the environment for creating term-references. This function is called by the kernel before calling a foreign predicate.

void PL_close_foreign_frame(fid_t id)

Discard all term-references created after the frame was opened. All other Prolog data is retained. This function is called by the kernel whenever a foreign function returns control back to Prolog.

void PL_discard_foreign_frame(fid_t id)

Same as PL_close_foreign_frame(), but also undo all bindings made since the open and destroy all Prolog data.

It is obligatory to call either of the two closing functions to discard a foreign frame. Foreign frames may be nested.

5.6.8 Foreign Code and Modules

Modules are identified via a unique handle. The following functions are available to query and manipulate modules.

module_t PL_context()

Return the module identifier of the context module of the currently active foreign predicate.

int PL_strip_module(term_t +raw, module_t *m, term_t -plain)

Utility function. If raw is a term, possibly holding the module construct <module>:<rest> this function will make plain a reference to <rest> and fill module * with <module>. For further nested module constructs the inner most module is returned via module *. If raw is not a module construct arg will simply be put in plain. If module * is NULL it will be set to the context module. Otherwise it will be left untouched. The following example shows how to obtain the plain term and module if the default module is the user module:

{ module m = PL_new_module(PL_new_atom("user")); term_t plain = PL_new_term_ref(); PL_strip_module(term, &m, plain); ...

atom_t PL_module_name(module_t)

Return the name of module as an atom.

module_t PL_new_module(atom_t name)

Find an existing or create a new module with name specified by the atom name.

5.6.9 Prolog exceptions in foreign code

This section discusses PL_exception(), PL_throw() and PL_raise_exception(), the interface functions to detect and generate Prolog exceptions from C-code. PL_throw() and PL_raise_exception() from the C-interface to raise an exception from foreign code. PL_throw() exploits the C-function longjmp() to return immediately to the innermost PL_next_solution(). PL_raise_exception() registers the exception term and returns FALSE. If a foreign predicate returns FALSE, while and exception-term is registered a Prolog exception will be raised by the virtual machine.

Calling these functions outside the context of a function implementing a foreign predicate results in undefined behaviour.

PL_exception() may be used after a call to PL_next_solution() fails, and returns a term reference to an exception term if an exception was raised, and 0 otherwise.

If a C-function, implementing a predicate calls Prolog and detects an exception using PL_exception(), it can handle this exception, or return with the exception. Some caution is required though. It is not allowed to call PL_close_query() or PL_discard_foreign_frame() afterwards, as this will invalidate the exception term. Below is the code that calls a Prolog defined arithmetic function (see arithmethic_function/1).

If PL_next_solution() succeeds, the result is analysed and translated to a number, after which the query is closed and all Prolog data created after PL_open_foreign_frame() is destroyed. On the other hand, if PL_next_solution() fails and if an exception was raised, just pass it. Otherwise generate an exception (PL_error() is an internal call for building the standard error terms and calling PL_raise_exception()). After this, the Prolog environment should be discarded using PL_cut_query() and PL_close_foreign_frame() to avoid invalidating the exception term.

int PL_raise_exception(term_t exception)

Generate an exception (as throw/1) and return FALSE. Below is an example returning an exception from foreign predicate:

foreign_t pl_hello(term_t to) { char *s; if ( PL_get_atom_chars(to, &s) ) { Sprintf("Hello \"%s\"\n", s); PL_succeed; } else { term_t except = PL_new_term_ref(); PL_unify_term(except, PL_FUNCTOR, PL_new_functor(PL_new_atom("type_error"), 2), PL_CHARS, "atom", PL_TERM, to); return PL_raise_exception(except); } }

int PL_throw(term_t exception)

Similar to PL_raise_exception(), but returns using the C longjmp() function to the innermost PL_next_solution().

term_t PL_exception(qid_t qid)

If PL_next_solution() fails, this can be due to normal failure of the Prolog call, or because an exception was raised using throw/1. This function returns a handle to the exception term if an exception was raised, or 0 if the Prolog goal simply failed. (27).

5.6.10 Miscellaneous

5.6.10.1 Term Comparison

int PL_compare(term_t t1, term_t t2)

Compares two terms using the standard order of terms and returns -1, 0 or 1. See also compare/3.

5.6.10.2 Recorded database

The interface functions below provide for efficient management of Prolog terms in the Prolog database. They provide an alternative to calling asserta/1 or recorda/3 or friends.

record_t PL_record(term_t +t)

Record the term t into the Prolog database as recorda/3 and return an opaque handle to the term. The returned handle remains valid until PL_erase() is called on it. PL_recorded() is used to copy recorded terms back to the Prolog stack.

void PL_recorded(record_t record, term_t -t)

Copy a recorded term back to the Prolog stack. The same record may be used to copy multiple instances at any time to the Prolog stack. See also PL_record() and PL_erase().

void PL_erase(record_t record)

Remove the recorded term from the Prolog database, reclaiming all associated memory resources.

5.6.11 Catching Signals (Software Interrupts)

SWI-Prolog offers both a C and Prolog interface to deal with software interrupts (signals). The Prolog mapping is defined in section ??. This subsection deals with handling signals from C.

If a signal is not used by Prolog and the handler does not call Prolog in any way, the native signal interface routines may be used.

Some versions of SWI-Prolog, notably running on popular Unix platforms, handle SIG_SEGV for guarding the Prolog stacks. If the application whishes to handle this signal too, it should use PL_signal() to install its handler after initialisating Prolog. SWI-Prolog will pass SIG_SEGV to the user code if it detected the signal is not related to a Prolog stack overflow.

Any handler that wishes to call one of the Prolog interface functions should call PL_signal() for its installation.

void (*)() PL_signal(sig, func)

This function is equivalent to the BSD-Unix signal() function, regardless of the platform used. The signal handler is blocked while the signal routine is active, and automatically reactivated after the handler returns.

After a signal handler is registered using this function, the native signal interface redirects the signal to a generic signal handler inside SWI-Prolog. This generic handler validates the environment, creates a suitable environment for calling the interface functions described in this chapter and finally calls the registered user-handler.

5.6.12 Errors and warnings

PL_warning() prints a standard Prolog warning message to the standard error (user_error) stream. Please note that new code should consider using PL_raise_exception() to raise a Prolog exception. See also section 3.8.

int PL_warning(format, a1, ...)

Print an error message starting with `[WARNING: ', followed by the output from format, followed by a `]' and a newline. Then start the tracer. format and the arguments are the same as for printf(2). Always returns FALSE.

5.6.13 Environment Control from Foreign Code

int PL_action(int, C_type)

Perform some action on the Prolog system. int describes the action, C_type provides the argument if necessary. The actions are listed in table 5.

PL_ACTION_TRACE	Start Prolog tracer
PL_ACTION_DEBUG	Switch on Prolog debug mode
PL_ACTION_BACKTRACE	Print backtrace on current output stream. The argument (an int) is the number of frames printed.
PL_ACTION_HALT	Halt Prolog execution. This action should be called rather than Unix exit() to give Prolog the opportunity to clean up. This call does not return.
PL_ACTION_ABORT	Generate a Prolog abort. This call does not return.
PL_ACTION_BREAK	Create a standard Prolog break environment. Returns after the user types control-D.
PL_ACTION_SYMBOLFILE	The argument (a char *) is considered to be hold the symbolfile for further incremental loading. Should be called by user applications that perform incremental loading as well and want to inform Prolog of the new symbol table.

Table 5 : PL_action() options

5.6.14 Querying Prolog

C_type PL_query(int)

Obtain status information on the Prolog system. The actual argument type depends on the information required. int describes what information is wanted. The options are given in table 6.

PL_QUERY_ARGC	Return an integer holding the number of arguments given to Prolog from Unix.
PL_QUERY_ARGV	Return a char ** holding the argument vector given to Prolog from Unix.
PL_QUERY_SYMBOLFILE	Return a char * holding the current symbol file of the running process.
PL_QUERY_ORGSYMBOLFILE	Return the initial symbol file (before loading) of Prolog. By setting the symbol file to this value no name clashes can occur with previously loaded foreign files (but no symbols can be shared with earlier loaded modules as well).
PL_MAX_INTEGER	Return a long, representing the maximal integer value represented by Prolog's tagged integers.
PL_MIN_INTEGER	Return a long, represented the minimal integer value.
PL_QUERY_VERSION	Return a long, representing the version as 10,000 × M + 100 × m + p, where M is the major, m the minor version number and p the patch-level. For example, 20717 means 2.7.17.

Table 6 : PL_query() options

5.6.15 Registering Foreign Predicates

int PL_register_foreign(name, arity, function, flags)

Register a C-function to implement a Prolog predicate. After this call returns successfully a predicate with name name (a char *) and arity arity (a C int) is created. When called in Prolog, Prolog will call function. flags forms bitwise or'ed list of options for the installation. These are:

PL_FA_NOTRACE	Predicate cannot be seen in the tracer
PL_FA_TRANSPARENT	Predicate is module transparent
PL_FA_NONDETERMINISTIC	Predicate is non-deterministic. See also PL_retry().

void PL_register_extensions(PL_extension *e)

Register foreign predicates from a table of structures. The type PL_extension is defined as:

typedef struct _PL_extension { char *predicate_name; /* Name of the predicate */ short arity; /* Arity of the predicate */ pl_function_t function; /* Implementing functions */ short flags; /* Or of PL_FA_... */ } PL_extension;

Here is an example of its usage:

static PL_extension predicates[] = { { "foo", 1, pl_foo, 0 }, { "bar", 2, pl_bar, PL_FA_NONDETERMINISTIC }, { NULL, 0, NULL, 0 } }; main(int argc, char **argv) { PL_register_extensions(predicates); if ( !PL_initialise(argc, argv) ) PL_halt(1); ... }

The function PL_register_extensions() is the only PL_* function that may be called before PL_initialise(). The functions are registered after registration of the SWI-Prolog builtin foreign predicates and before loading the initial saved state. This implies that initialization/1 directives can refer to them.

5.6.16 Foreign Code Hooks

For various specific applications some hooks re provided.

PL_dispatch_hook_t PL_dispatch_hook(PL_dispatch_hook_t)

If this hook is not NULL, this function is called when reading from the terminal. It is supposed to dispatch events when SWI-Prolog is connected to a window environment. It can return two values: PL_DISPATCH_INPUT indicates Prolog input is available on file descriptor 0 or PL_DISPATCH_TIMEOUT to indicate a timeout. The old hook is returned. The type PL_dispatch_hook_t is defined as:

typedef int (*PL_dispatch_hook_t)(void);

void PL_abort_hook(PL_abort_hook_t)

Install a hook when abort/0 is executed. SWI-Prolog abort/0 is implemented using C setjmp()/longjmp() construct. The hooks are executed in the reverse order of their registration after the longjmp() took place and before the Prolog toplevel is reinvoked. The type PL_abort_hook_t is defined as: typedef void (*PL_abort_hook_t)(void);

int PL_abort_unhook(PL_abort_hook_t)

Remove a hook installed with PL_abort_hook(). Returns FALSE if no such hook is found, TRUE otherwise.

5.6.17 Storing foreign data

This section provides some hints for handling foreign data in Prolog. With foreign data, we refer to data that is used by foreign language predicates and needs to be passed around in Prolog. Excluding combinations, there are three principal options for storing such data

• Natural Prolog data
  E.i. using the representation one would choose if there was no foreign interface required.
• Opaque packed Prolog data
  Data can also be represetented in a foreign structure and stored on the Prolog stacks using PL_put_string_nchars() and retrieved using PL_get_string_chars(). It is generally good practice to wrap the string in a compound term with arity 1, so Prolog can identify the type. portray/1 rules may be used to streamline printing such terms during development.
• Natural foreign data, passing a pointer
  An alternative is to pass a pointer to the foreign data. Again, this functor may be wrapped in a compound term.

The choice may be guided using the following distinctions

• Is the data opaque to Prolog
  With `opaque' data, we refer to data handled in foreign functions, passed around in Prolog, but of which Prolog never examines the contents of the data itself. If the data is opaque to Prolog, the choosen representation does not depend on simple analysis by Prolog, and the selection will be driven solely by simplicity of the interface and performance (both in time and space).
• How big is the data
  Is effient encoding required? For examine, a boolean aray may be expressed as a compound term, holding integers each of which contains a number of bits, or as a list of true and false.
• What is the nature of the data
  For examples in C, constants are often expressed using `enum' or #define'd integer values. If prolog needs to handle this data, atoms are a more logical choice. Whether or not this mapping is used depends on whether Prolog needs to interpret the data, how important debugging is and how important performance is.
• What is the lifetime of the data
  We can distinguish three cases.
  1. The lifetime is dictated by the accesibility of the data on the Prolog stacks. Their is no way by which the foreign code when the data becomes `garbage', and the data thus needs to be represented on the Prolog stacks using Prolog data-types. (2),
  2. The data lives on the `heap' and is explicitly allocated and deallocated. In this case, representing the data using native foreign representation and passing a pointer to it is a sensible choice.
  3. The data lives as during the lifetime of a foreign predicate. If the predicate is deterministic, foreign automatic variables are suitable. if the predicate is non-deterministic, the data may be allocated using malloc() and a pointer may be passed. See section 5.6.1.1.

5.6.17.1 Examples for storing foreign data

In this section, we wull outline some examples, covering typical cases. In the first example, we will deal with extending Prolog's data representation with integer-sets, represented as bit-vectors. In the second example, we look at handling a `netmask'. Finally, we discuss the outline of the DDE interface.

Integer sets with not-to-far-apart upper- and lower-bounds can be represented using bit-vectors. Common set operations, such as union, intersection, etc. are reduced to simple and'ing and or'ing the bitvectors. This can be done in Prolog, using a compound term holding integer arguments. Especially if the integers are kept below the maximum tagged integer value (see feature/2), this representation is fairly space-efficient (wasting 1 word for the functor and and 7 bits per integer for the tags). Arithmetic can all be performed in Prolog too.

For really demanding applications, foreign representation will perform better, especially time-wise. Bit-vectors are natrually expressed using string objects. If the string is wrapped in bitvector/1 , lower-bound of the vector is 0, and the upperbound is not defined, an implementation for getting and putting the setes as well as the union predicate for it is below.

Netmask's are used with TCP/IP configuration. Suppose we have an application dealing with reasoning about a network configuration. Such an application requires communicating netmask structures from the operating system, reasoning about them and possibly communicate them to the user. A netmask consists of 4 bitmasks between 0 and 255. C-application normally see them as an 4-byte wide unsigned integer. SWI-Prolog cannot do that, as integers are always signed.

We could use the string approach outlined above, but this makes it hard to handle these terms in Prolog. A better choice is a compound term netmask/4, holding the 4 submasks as integer arguments.

As the implementation is trivial, we will omit this here.

The DDE interface (see section 3.42) represents another common usage of the foreign interface: providing communication to new operating system features. The DDE interface requires knowledge about active DDE server and client channels. These channels contains various foreign data-types. Such an interface is normally achieved using an open/close protocol that creates and destroys a handle. The handle is a reference to a foreign data-structure containing the relevant information.

There are a couple of possibilities for representing the handle. The choice depends on responsibilities and debugging facilities. The simplest aproach is to using PL_unify_pointer() and PL_get_pointer(). This approach is fast and easy, but has the drawbacks of (untyped) pointers: there is no reliable way to detect the validity of the pointer, not to verify it is pointing to a structure of the desired type. The pointer may be wrapped into a compound term with arity 1 (i.e. dde_channel(<Pointer>)), making the type-problem less serious.

Alternatively (used in the DDE interface), the interface code can maintain a (preferably variable length) array of pointers and return the index in this array. This provides better protection. Especially for debugging purposes, wrapping the handle in a compound is a good suggestion.

5.6.18 Embedding SWI-Prolog in a C-program

As of version 2.1.0, SWI-Prolog may be embedded in a C-program. To reach at a compiled C-program with SWI-Prolog as an embedded application is very similar to creating a statically linked SWI-Prolog executable as described in section 5.4.1.

The file ... /pl/include/stub.c defines SWI-Prologs default main program:

This may be replaced with your own main C-program. The interface function PL_initialise() must be called before any of the other SWI-Prolog foreign language functions described in this chapter. PL_initialise() interprets all the command-line arguments, except for the -t toplevel flag that is interpreted by PL_toplevel().

int PL_initialise(int argc, char **argv, char **environ)

Initialises the SWI-Prolog heap and stacks, restores the boot QLF file, loads the system and personal initialisation files, runs the at_initialization/1 hooks and finally runs the -g goal hook.

PL_initialise() returns 1 if all initialisation succeeded and 0 otherwise. Various fatal errors may cause PL_initialise to call PL_halt(1), preventing it from returning at all.

void PL_install_readline()

Installs the GNU-readline line-editor. Embedded applications that do not use the Prolog toplevel should normally delete this line, shrinking the Prolog kernel significantly.

int PL_toplevel()

Runs the goal of the -t toplevel switch (default prolog/0) and returns 1 if successful, 0 otherwise.

void PL_halt(int status)

Cleanup the Prolog environment and calls exit() with the status argument.