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.

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 display/1 in C

Figure 7 shows a definition of display/1 to illustrate the described functions.

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 string in the term-reference. The data will be copied.

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_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_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_put_list(l, a, l); } }

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.

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

Unify t with a Prolog string object created from chars.

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; while(*environ) { if ( !PL_unify_list(l, a, l) || !PL_unify_atom_chars(a, *environ) ) 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. (25)

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 debug, 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() and PL_throw(), the interface functions to detect and generate Prolog exceptions from C-code. PL_throw() is similar to throw/1, and may be used to return an exception from a foreign predicate. After calling PL_throw(), the function implementing a foreign predicate should return failure. If success is returned, the exception is simply discarded. Calling PL_throw() 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_throw()). 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_throw(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_ATOM, "atom", PL_TERM, to); return PL_throw(except); } }

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. (26).

5.6.10 Miscellaneous

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.11 Catching Signals (Software Interrupts)

SWI-Prolog catches the Unix signals SIGINT, SIGFPE and SIGSEGV. To avoid problems with foreign code attempting to catch these signals foreign code should call PL_signal() to install signal handlers rather than the Unix library function signal(). SWI-Prolog will always handle SIGINT itself. SIGFPE and SIGSEGV are passed to the foreign code handlers if Prolog did not expect that signal.

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

This function should be used to install signal handlers rather than the Unix library function signal(). It ensures consistent signal handling between SWI-Prolog and the foreign code and reinstalls signal handlers if a state created with save_program/1 is restarted.

5.6.12 Errors and warnings

Two standard functions are available to print standard Prolog errors to the standard error stream.

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.

void PL_reinit_hook(PL_reinit_hook_t)

Install a hook that is called when a saved program (using save_program/[1,2]) is restored. The hooks are called in reverse order. The type PL_reinit_hook_t is defined as: typedef void (*PL_reinit_hook_t)(int argc, char **argv);

int PL_reinit_unhook(PL_reinit_hook_t)

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

5.6.17 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.