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:
return TRUE.
return FALSE.
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:
quotient_below_n(Q, N) :-
natural_number_below_n(N, N1),
natural_number_below_n(N, N2),
Q =:= N1 / N2, !.
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:
PL_FIRST_CALL)PL_REDO)PL_CUTTED)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.
return _PL_retry(n). See also
PL_succeed().return
_PL_retry_address(n). See also PL_succeed().PL_CUTTED case and should be aware that the other
arguments are not valid in this case.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).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 8 shows a skeleton for a non-deterministic foreign predicate definition.
typedef struct /* define a context structure */
{ ...
} context;
foreign_t
my_function(term_t a0, term_t a1, control_t handle)
{ struct context * ctxt;
switch( PL_foreign_control(handle) )
{ case PL_FIRST_CALL:
ctxt = malloc(sizeof(struct context));
...
PL_retry_address(ctxt);
case PL_REDO:
ctxt = PL_foreign_context_address(handle);
...
PL_retry_address(ctxt);
case PL_CUTTED:
ctxt = PL_foreign_context_address(handle);
...
free(ctxt);
PL_succeed;
}
}
| Figure 8 : Skeleton for non-deterministic foreign functions |
The following functions provide for communication using atoms and functors.
term_t normally use PL_get_atom_chars() or
PL_get_atom_nchars().With the introduction of atom-garbage collection in version 3.3.0, atoms no longer live as long as the process. Instead, their lifetime is guaranteed only as long as they are referenced. In the single-threaded version, atom garbage collections are only invoked at the call-port. In the multi-threaded version (see section 8), they appear asynchronously, except for the invoking thread.
For dealing with atom garbage collection, two additional functions are provided:
Please note that the following two calls are different with respect to atom garbage collection:
PL_unify_atom_chars(t, "text");
PL_unify_atom(t, PL_new_atom("text"));
The latter increments the reference count of the atom text,
which effectively ensures the atom will never be collected. It is
advised to use the *_chars() or *_nchars() functions whenever
applicable.
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.
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.
[].
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.
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 16 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 PL_free()
when not needed any longer.
With the introduction of wide-characters (see section
2.17.1), not all atoms can be converted into a char*.
This function fails if t is of the wrong type, but also if
the text cannot be represented. See the REP_* flags below
for details.
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_WRITE | Convert any term that
is not converted by any of the other flags using write/1.
If no BUF_* is provided, BUF_RING is implied. |
CVT_ALL | Convert if term is any
of the above, except for
CVT_VARIABLE and CVT_WRITE |
CVT_EXCEPTION | If conversion fails due to a type error, raise a Prolog type error exception in addition to failure |
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 PL_malloc(3). When no longer needed the user must call PL_free() on the data. |
REP_ISO_LATIN_1 | (0, default). Text is in ISO Latin-1 encoding and the call fails if text cannot be represented. |
REP_UTF8 | Convert the text to a UTF-8 string. This works for all text. |
REP_MB | Convert to default locale-defined 8-bit string. Success depends on the locale. Conversion is done using the wcrtomb() C-library function. |
PL_get_chars(l, s, CVT_LIST|flags),
provided flags contains no of the CVT_* flags.
FALSE.
If t is a floating point number that can be represented as a
long, this function succeeds as well. See also PL_get_int64()int64_t, assign its value over i. Currently all
Prolog integers can be represented using this type, but this might
change if SWI-Prolog introduces unbounded integers.true or false,
set val to the C constant TRUE or FALSE
and return success. otherwise return failure.
All internal text-representation of SWI-Prolog is represented using
char * plus length and allow for 0-bytes in them.
The foreign library supports this by implementing a *_nchars() function
for each applicable *_chars() function. Below we briefly present the
signatures of these functions. For full documentation consult the
*_chars() function.
In addition, the following functions are available for creating and inspecting atoms:
Support for exchange of wide character strings is still under
consideration. The functions dealing with 8-bit character strings return
failure when operating on a wide character atom or Prolog string object.
The functions below can extract and unify both 8-bit and wide atoms and
string objects. Wide character strings are represented as C arrays of
objects of the type pl_wchar_t, which is guaranteed to be
the same as wchar_t on platforms supporting this type. For
example, on MS-Windows, this represents 16-bit UCS2 characters, while
using the GNU C library (glibc) this represents 32-bit UCS4 characters.
NULL) if atom is not a wide-character atom. This
is the wide-character version of PL_atom_nchars(). Note that only one of
these functions succeeds on a particular atom. Especially, after
creating an atom with PL_new_atom_wchars(), extracting the text using
PL_atom_wchars() will fail if the atom only contains ISO-Latin-1
characters.PL_ATOM, PL_STRING,
PL_CODE_LIST or PL_CHAR_LIST.
PL_CODE_LIST
and PL_CHAR_LIST. It serves two purposes. It allows for
returning very long lists from data read from a stream without the need
for a resizing buffer in C. Also, the use of difference lists is often
practical for further processing in Prolog. Examples can be found in packages/clib/readutil.c
from the source distribution.
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:
foreign_t
pl_write_atoms(term_t l)
{ term_t head = PL_new_term_ref(); /* variable for the elements */
term_t list = PL_copy_term_ref(l); /* copy as we need to write */
while( PL_get_list(list, head, list) )
{ char *s;
if ( PL_get_atom_chars(head, &s) )
Sprintf("%s\n", s);
else
PL_fail;
}
return PL_get_nil(list); /* test end for [] */
}
[] assign a
term-reference to the head to h and to the tail to t.
[] assign a
term-reference to the head to h.
[] assign a
term-reference to the tail to t.
[].
Figure 9 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.
foreign_t
pl_display(term_t t)
{ functor_t functor;
int arity, len, n;
char *s;
switch( PL_term_type(t) )
{ case PL_VARIABLE:
case PL_ATOM:
case PL_INTEGER:
case PL_FLOAT:
PL_get_chars(t, &s, CVT_ALL);
Sprintf("%s", s);
break;
case PL_STRING:
PL_get_string_chars(t, &s, &len);
Sprintf("\"%s\"", s);
break;
case PL_TERM:
{ term_t a = PL_new_term_ref();
PL_get_name_arity(t, &name, &arity);
Sprintf("%s(", PL_atom_chars(name));
for(n=1; n<=arity; n++)
{ PL_get_arg(n, t, a);
if ( n > 1 )
Sprintf(", ");
pl_display(a);
}
Sprintf(")");
break;
default:
PL_fail; /* should not happen */
}
PL_succeed;
}
| Figure 9 : A Foreign definition of display/1 |
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.
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 9.6.19.
PL_put_functor(l, PL_new_functor(PL_new_atom("."), 2)).
PL_put_atom_chars("[]").
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();
functor_t animal2;
/* animal2 is a constant that may be bound to a global
variable and re-used
*/
animal2 = PL_new_functor(PL_new_atom("animal"), 2);
PL_put_atom_chars(a1, "gnu");
PL_put_integer(a2, 50);
PL_cons_functor(t, animal2, a1, a2);
}
After this sequence, the term-references a1 and a2 may be used for other purposes.
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.
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:
foreign_t
pl_hostname(term_t name)
{ char buf[100];
if ( gethostname(buf, sizeof(buf)) )
{ term_t tmp = PL_new_term_ref();
PL_put_atom_chars(tmp, buf);
return PL_unify(name, tmp);
}
PL_fail;
}
Using PL_unify_atom_chars(), this becomes:
foreign_t
pl_hostname(term_t name)
{ char buf[100];
if ( gethostname(buf, sizeof(buf)) )
return PL_unify_atom_chars(name, buf);
PL_fail;
}
char* with various
encodings to a Prolog representation. The flags argument is a
bitwise or specifying the Prolog target type and the encoding
of
chars. Prolog types is one of PL_ATOM, PL_STRING,
PL_CODE_LIST or PL_CHAR_LIST. Representations
is one of
REP_ISO_LATIN_1, REP_UTF8 or REP_MB.
See PL_get_chars() for a definition of the representation types. If
len is -1 chars must be 0-terminated
and the length is computed from chars using strlen().
If flags includes PL_DIFF_LIST and type is
one of
PL_CODE_LIST or PL_CHAR_LIST, the text is
converted to a difference list. The tail of the difference list
is
t+1.
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);
}
[].
Special attention is required when passing numbers. C `promotes' any
integral smaller than int to int. I.e. the
types
char, short and int are all
passed as int. In addition, on most 32-bit platforms int
and long are the same. Up-to version 4.0.5, only PL_INTEGER
could be specified which was taken from the stack as long.
Such code fails when passing small integral types on machines where int
is smaller than long. It is advised to use PL_SHORT, PL_INT
or PL_LONG as appropriate. Similar, C compilers promote
float to double and therefore PL_FLOAT
and
PL_DOUBLE are synonyms.
The type identifiers are:
PL_VARIABLE nonePL_FUNCTOR.
PL_BOOL inttrue or false.
PL_ATOM atom_tPL_CHARS const char *char *,
as in PL_unify_atom_chars().
PL_NCHARS size_t, const char *char* as in PL_unify_atom_nchars().
PL_UTF8_CHARS const char *PL_UTF8_STRING const char *PL_MBCHARS const char *PL_MBCODES const char *PL_MBSTRING const char *PL_NWCHARS size_t, const wchar_t *PL_NWCODES size_t, const wchar_t *PL_NWSTRING size_t, const wchar_t *PL_SHORT shortshort is promoted to int, PL_SHORT
is a synonym for PL_INT.
PL_INTEGER longPL_INT intPL_LONG longPL_INT64 int64_tPL_INTPTR intptr_tPL_LONG. but on 64-bit
MS-Windows pointers are 64-bit while longs are only 32-bits.
PL_DOUBLE doublePL_FLOAT doublePL_POINTER void *PL_STRING const char *PL_TERM term_tPL_FUNCTOR functor_t, ...PL_FUNCTOR_CHARS const char *name, int arity,
...PL_FUNCTOR.
PL_LIST int length, ...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();
}
FALSE
if a syntax error was encountered and TRUE after successful
completion. In addition to returning FALSE, the
exception-term is returned in t on a syntax error. See also term_to_atom/2.
The following example build a goal-term from a string and calls it.
int
call_chars(const char *goal)
{ fid_t fid = PL_open_foreign_frame();
term_t g = PL_new_term_ref();
BOOL rval;
if ( PL_chars_to_term(goal, g) )
rval = PL_call(goal, NULL);
else
rval = FALSE;
PL_discard_foreign_frame(fid);
return rval;
}
...
call_chars("consult(load)");
...
'\'', the result is a quoted atom. If chr is
'"', the result is a string. The result string is stored in
the same ring of buffers as described with the BUF_RING
argument of PL_get_chars();
In the current implementation, the string is surrounded by chr and any occurrence of chr is doubled. In the future the behaviour will depend on the character_escapes Prolog flag.
SWI-Prolog atoms as well as strings can represent arbitrary binary data of arbitrary length. This facility is attractive for storing foreign data such as images in an atom. An atom is a unique handle to this data and the atom garbage collector is able to destroy atoms that are no longer referenced by the Prolog engine. This property of atoms makes them attractive as a handle to foreign resources, such as Java atoms, Microsoft's COM objects, etc., providing safe combined garbage collection.
To exploit these features safely and in an organised manner the SWI-Prolog foreign interface allows for creating `atoms' with additional type information. The type is represented by a structure holding C function pointers that tell Prolog how to handle releasing the atom, writing it, sorting it, etc. Two atoms created with different types can represent the same sequence of bytes. Atoms are first ordered on the rank number of the type and then on the result of the compare() function. Rank numbers are assigned when the type is registered.
The type PL_blob_t represents a structure with the
layout displayed above. The structure contains additional fields at the
... for internal bookkeeping as well as future extension.
typedef struct PL_blob_t
{ unsigned long magic; /* PL_BLOB_MAGIC */
unsigned long flags; /* Bitwise or of PL_BLOB_* */
char * name; /* name of the type */
int (*release)(atom_t a);
int (*compare)(atom_t a, atom_t b);
int (*write)(IOSTREAM *s, atom_t a, int flags);
int (*acquire)(atom_t a);
...
} PL_blob_t;
For each type exactly one such structure should be allocated. Its
first field must be initialised to PL_BLOB_MAGIC. The
flags is a bitwise or of the following constants:
PL_BLOB_UNIQUE
is also specified uniqueness is determined by comparing the pointer
rather than the data pointed at.
The name field represents the type name as available to
Prolog. See also current_blob/2.
The other field are function pointers that must be initialised to proper
functions or NULL to get the default behaviour of built-in
atoms. Below are the defined member functions:
FALSE
the atom garbage collector will not reclaim the atom.PL_WRT_* flags defined in
SWI-Prolog.h. This prototype is available if the
undocumented SWI-Stream.h is included before
SWI-Prolog.h.
If this function is not provided, write/1
emits the content of the blob for blobs of type PL_BLOB_TEXT
or a string of the format <#hex data>
for binary blobs.
If a blob type is registered from a loadable object (shared object or DLL) the blob-type must be deregistered before the object may be released.
unregistered, avoiding further
reference to the type structure, functions referred by it as well as the
data. This function returns TRUE if no blobs of this type
existed and FALSE otherwise. PL_unregister_blob_type() is
intended for the uninstall() hook of foreign modules, avoiding further
references to the module.
The blob access functions are similar to the atom accessing functions. Blobs being atoms, the atom functions operate on blobs and visa versa. For clarity and possible future compatibility issues however it is not advised to rely on this.
FALSE) or the blob is a
reference to an existing blob (TRUE). Reporting
new/existing can be used to deal with external objects having their own
reference counts. If the return is TRUE this reference
count must be incremented and it must be decremented on blob destruction
callback. See also PL_put_atom_nchars().TRUE. Otherwise return FALSE. Each result
pointer may be NULL, in which case the requested
information is ignored.If SWI-Prolog is linked with the GNU Multiple Precision Arithmetic
Library (GMP, used by default), the foreign interface provides functions
for exchanging numeric values to GMP types. To access these functions
the header <gmp.h> must be included before
<SWI-Prolog.h>. Foreign code using GMP linked to
SWI-Prolog asks for some considerations.
PL_action(PL_GMP_SET_ALLOC_FUNCTIONS, TRUE) to force
Prolog's GMP initialization without doing the rest of the Prolog
initialization. If you do not want Prolog rebinding the GMP allocation,
call PL_action(PL_GMP_SET_ALLOC_FUNCTIONS, FALSE)
before initializing Prolog.
Here is an example exploiting the function mpz_nextprime():
#include <gmp.h>
#include <SWI-Prolog.h>
static foreign_t
next_prime(term_t n, term_t prime)
{ mpz_t mpz;
int rc;
mpz_init(mpz);
if ( PL_get_mpz(n, mpz) )
{ mpz_nextprime(mpz, mpz);
rc = PL_unify_mpz(prime, mpz);
} else
rc = FALSE;
mpz_clear(mpz);
return rc;
}
install_t
install()
{ PL_register_foreign("next_prime", 2, next_prime, 0);
}
TRUE. Otherwise mpz
is untouched and the function returns FALSE. Note that mpz
must have been initialised before calling this function and must be
cleared using mpz_clear() to reclaim any storage associated with it.TRUE. Otherwise mpq is
untouched and the function returns FALSE. Note that mpq
must have been initialised before calling this function and must be
cleared using mpq_clear() to reclaim any storage associated with it.The Prolog engine can be called from C. There are two 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.
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.
NULL, the current context module is used.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.
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_NORMALPL_Q_NODEBUG
for backward compatibility reasons.
PL_Q_NODEBUGPL_Q_CATCH_EXCEPTIONPL_Q_PASS_EXCEPTIONPL_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);
...
}
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.
TRUE if the call succeeds, FALSE
otherwise.
Figure 10
shows an example to obtain the number of defined atoms. All checks are
omitted to improve readability.
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 10 for an example.
It is obligatory to call either of the two closing functions to discard a foreign frame. Foreign frames may be nested.
int
count_atoms()
{ fid_t fid = PL_open_foreign_frame();
term_t goal = PL_new_term_ref();
term_t a1 = PL_new_term_ref();
term_t a2 = PL_new_term_ref();
functor_t s2 = PL_new_functor(PL_new_atom("statistics"), 2);
int atoms;
PL_put_atom_chars(a1, "atoms");
PL_cons_functor(goal, s2, a1, a2);
PL_call(goal, NULL); /* call it in current module */
PL_get_integer(a2, &atoms);
PL_discard_foreign_frame(fid);
return atoms;
}
| Figure 10 : Calling Prolog |
Modules are identified via a unique handle. The following functions are available to query and manipulate modules.
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);
...
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 arithmetic_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.
static int
prologFunction(ArithFunction f, term_t av, Number r)
{ int arity = f->proc->definition->functor->arity;
fid_t fid = PL_open_foreign_frame();
qid_t qid;
int rval;
qid = PL_open_query(NULL, PL_Q_NORMAL, f->proc, av);
if ( PL_next_solution(qid) )
{ rval = valueExpression(av+arity-1, r);
PL_close_query(qid);
PL_discard_foreign_frame(fid);
} else
{ term_t except;
if ( (except = PL_exception(qid)) )
{ rval = PL_throw(except); /* pass exception */
} else
{ char *name = stringAtom(f->proc->definition->functor->name);
/* generate exception */
rval = PL_error(name, arity-1, NULL, ERR_FAILED, f->proc);
}
PL_cut_query(qid); /* donot destroy data */
PL_close_foreign_frame(fid); /* same */
}
return rval;
}
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_CHARS, "type_error", 2,
PL_CHARS, "atom",
PL_TERM, to);
return PL_raise_exception(except);
}
}
SWI-Prolog offers both a C and Prolog interface to deal with software interrupts (signals). The Prolog mapping is defined in section 4.10. 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 wishes to handle this signal too, it should use
PL_signal() to install its handler after initialising 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.
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.
By default, signals are handled asynchronously (i.e. at the time they
arrive). It is inherently dangerous to call extensive code fragments,
and especially exception related code from asynchronous handlers. The
interface allows for synchronous handling of signals. In this
case the native OS handler just schedules the signal using PL_raise(),
which is checked by PL_handle_signals() at the call- and redo-port. This
behaviour is realised by or-ing sig with the constant
PL_SIGSYNC.81A better
default would be to use synchronous handling, but this interface
preserves backward compatibility.
Signal handling routines may raise exceptions using PL_raise_exception(). The use of PL_throw() is not safe. If a synchronous handler raises an exception, the exception is delayed to the next call to PL_handle_signals();
The user may call this function inside long-running foreign functions
to handle scheduled interrupts. This routine returns the number of
signals handled. If a handler raises an exception, the return value is
-1 and the calling routine should return with FALSE as soon
as possible.
SIG or the full signal name.
These refer to the same: 9, kill and SIGKILL.
Leaves a typed, domain or instantiation error if the conversion fails.
TRUE if t1 and t2 refer to
physically the same compound term and FALSE otherwise.
In some applications it is useful to store and retrieve Prolog terms from C-code. For example, the XPCE graphical environment does this for storing arbitrary Prolog data as slot-data of XPCE objects.
Please note that the returned handles have no meaning at the Prolog level and the recorded terms are not visible from Prolog. The functions PL_recorded() and PL_erase() are the only functions that can operate on the stored term.
Two groups of functions are provided. The first group (PL_record() and friends) store Prolog terms on the Prolog heap for retrieval during the same session. These functions are also used by recorda/3 and friends. The recorded database may be used to communicate Prolog terms between threads.
The second group (headed by PL_record_external()) provides the same functionality, but the returned data has properties that enable storing the data on an external device. It has been designed to make it possible to store Prolog terms fast an compact in an external database. Here are the main features:
It is allowed to copy the data and use PL_recorded_external() on the copy. The user is responsible for the memory management of the copy. After copying, the original may be discarded using PL_erase_external().
PL_recorded_external() is used to copy such recorded terms back to the Prolog stack.
The function PL_get_file_name() provides access to Prolog filenames and its file-search mechanism described with absolute_file_name/3. Its existence is motivated to realise a uniform interface to deal with file-properties, search, naming conventions etc. from foreign code.
BUF_RING. Conversion from the internal UNICODE encoding is
done using standard C library functions. flags is a bit-mask
controlling the conversion process. Options are:
PL_FILE_ABSOLUTEPL_FILE_OSPATH\/PL_FILE_SEARCHPL_FILE_EXISTPL_FILE_READPL_FILE_WRITEPL_FILE_EXECUTEPL_FILE_NOERRORSPL_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 4.9.
]' and a
newline. Then start the tracer. format and the arguments are
the same as for printf(2). Always returns FALSE.
PL_ACTION_TRACEStart Prolog tracer (trace/0). Requires no arguments. PL_ACTION_DEBUGSwitch on Prolog debug mode (debug/0). Requires no arguments. PL_ACTION_BACKTRACEPrint backtrace on current output stream. The argument (an int) is the number of frames printed. PL_ACTION_HALTHalt Prolog execution. This action should be called rather than Unix exit() to give Prolog the opportunity to clean up. This call does not return. The argument (an int) is the exit code. See halt/1. PL_ACTION_ABORTGenerate a Prolog abort (abort/0). This call does not return. Requires no arguments. PL_ACTION_BREAKCreate a standard Prolog break environment (break/0). Returns after the user types the end-of-file character. Requires no arguments. PL_ACTION_GUIAPPWin32: Used to indicate the kernel that the application is a GUI application if the argument is not 0 and a console application if the argument is 0. If a fatal error occurs, the system uses a windows messagebox to report this on a GUI application and simply prints the error and exits otherwise. PL_ACTION_WRITEWrite the argument, a char *to the current output stream.PL_ACTION_FLUSHFlush the current output stream. Requires no arguments. PL_ACTION_ATTACH_CONSOLEAttach a console to a thread if it does not have one. See attach_console/0. PL_GMP_SET_ALLOC_FUNCTIONSTakes and integer argument. If TRUE, the GMP allocation are immediately bound to the Prolog functions. IfFALSE, SWI-Prolog will never rebind the GMP allocation functions. See mp_set_memory_functions() in the GMP documentation. The action returnsFALSEif there is no GMP support or GMP is already initialised.
| Table 6 : PL_action() options |
PL_QUERY_ARGCReturn an integer holding the number of arguments given to Prolog from Unix. PL_QUERY_ARGVReturn a char ** holding the argument vector given to Prolog from Unix. PL_QUERY_SYMBOLFILEReturn a char * holding the current symbol file of the running process. PL_MAX_INTEGERReturn a long, representing the maximal integer value represented by a Prolog integer. PL_MIN_INTEGERReturn a long, representing the minimal integer value. PL_QUERY_VERSIONReturn 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, 20717means2.7.17.PL_QUERY_MAX_THREADSReturn the maximum number of threads that can be created in this version. Return values of PL_thread_self() are between 0 and this number. PL_QUERY_ENCODINGReturn the default stream encoding of Prolog (of type IOENC).PL_QUERY_USER_CPUGet amount of user CPU time of the process in milliseconds.
| Table 7 : PL_query() options |
NULL, the predicate is created in the
module of the calling context or if no context is present in the module
user.
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(). |
PL_FA_VARARGS | Use alternative calling convention. |
Predicates may be registered either before or after PL_initialise(). When registered before initialisation the registration is recorded and executed after installing the system predicates and before loading the saved state.
Default calling (i.e. without PL_FA_VARARGS) function
is passed the same number of term_t arguments as the arity of the
predicate and, if the predicate is non-deterministic, an extra argument
of type
control_t (see section
9.6.1.1). If PL_FA_VARARGS is provided, function
is called with three arguments. The first argument is a term_t
handle to the first argument. Further arguments can be reached by adding
the offset (see also PL_new_term_refs()). The second argument is the
arity, which defines the number of valid term-references in the argument
vector. The last argument is used for non-deterministic calls. It is
currently undocumented and should be defined of type void*.
Here is an example:
static foreign_t
atom_checksum(term_t a0, int arity, void* context)
{ char *s;
if ( PL_get_atom_chars(a0, &s) )
{ int sum;
for(sum=0; *s; s++)
sum += *s&0xff;
return PL_unify_integer(a0+1, sum&0xff);
}
return FALSE;
}
install_t
install()
{ PL_register_foreign("atom_checksum", 2, atom_checksum, PL_FA_VARARGS);
}
NULL for
the
module.PL_extension in the given module. If module
is
NULL, the predicate is created in the module of the calling
context or if no context is present in the module user. The PL_extension
type 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;
For details, see PL_register_foreign_in_module(). 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_in_module("user", predicates);
if ( !PL_initialise(argc, argv) )
PL_halt(1);
...
}
NULL for
the module argument.
For various specific applications some hooks re provided.
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);
PL_abort_hook_t is defined as:
typedef void (*PL_abort_hook_t)(void);
FALSE
if no such hook is found, TRUE otherwise.
NULL is returned. The
argument of the called hook is the atom that is to be garbage collected.
The return value is an int. If the return value is zero,
the atom is not reclaimed. The hook may invoke any Prolog
predicate.
The example below defines a foreign library for printing the garbage collected atoms for debugging purposes.
#include <SWI-Stream.h>
#include <SWI-Prolog.h>
static int
atom_hook(atom_t a)
{ Sdprintf("AGC: deleting %s\n", PL_atom_chars(a));
return TRUE;
}
static PL_agc_hook_t old;
install_t
install()
{ old = PL_agc_hook(atom_hook);
}
install_t
uninstall()
{ PL_agc_hook(old);
}
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
The choice may be guided using the following distinctions
true and false.
In this section, we will 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. Finally, we discuss the outline of the DDE interface.
Integer sets with not-too-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 bit-vectors. This can be done using Prolog's unbounded integers.
For really demanding applications, foreign representation will perform better, especially time-wise. Bit-vectors are naturally expressed using string objects. If the string is wrapped in bitvector/1 , lower-bound of the vector is 0, and the upper-bound is not defined, an implementation for getting and putting the sets as well as the union predicate for it is below.
#include <SWI-Prolog.h>
#define max(a, b) ((a) > (b) ? (a) : (b))
#define min(a, b) ((a) < (b) ? (a) : (b))
static functor_t FUNCTOR_bitvector1;
static int
get_bitvector(term_t in, int *len, unsigned char **data)
{ if ( PL_is_functor(in, FUNCTOR_bitvector1) )
{ term_t a = PL_new_term_ref();
PL_get_arg(1, in, a);
return PL_get_string(a, (char **)data, len);
}
PL_fail;
}
static int
unify_bitvector(term_t out, int len, const unsigned char *data)
{ if ( PL_unify_functor(out, FUNCTOR_bitvector1) )
{ term_t a = PL_new_term_ref();
PL_get_arg(1, out, a);
return PL_unify_string_nchars(a, len, (const char *)data);
}
PL_fail;
}
static foreign_t
pl_bitvector_union(term_t t1, term_t t2, term_t u)
{ unsigned char *s1, *s2;
int l1, l2;
if ( get_bitvector(t1, &l1, &s1) &&
get_bitvector(t2, &l2, &s2) )
{ int l = max(l1, l2);
unsigned char *s3 = alloca(l);
if ( s3 )
{ int n;
int ml = min(l1, l2);
for(n=0; n<ml; n++)
s3[n] = s1[n] | s2[n];
for( ; n < l1; n++)
s3[n] = s1[n];
for( ; n < l2; n++)
s3[n] = s2[n];
return unify_bitvector(u, l, s3);
}
return PL_warning("Not enough memory");
}
PL_fail;
}
install_t
install()
{ PL_register_foreign("bitvector_union", 3, pl_bitvector_union, 0);
FUNCTOR_bitvector1 = PL_new_functor(PL_new_atom("bitvector"), 1);
}
The DDE interface (see section 4.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 approach 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.
With embedded Prolog we refer to the situation where the `main' program is not the Prolog application. Prolog is sometimes embedded in C, C++, Java or other languages to provide logic based services in a larger application. Embedding loads the Prolog engine as a library to the external language. Prolog itself only provides for embedding in the C-language (compatible to C++). Embedding in Java is achieved using JPL using a C-glue between the Java and Prolog C-interfaces.
The most simple embedded program is below. The interface function PL_initialise() must be called before any of the other SWI-Prolog foreign language functions described in this chapter, except for PL_initialise_hook(), PL_new_atom(), PL_new_functor() and PL_register_foreign(). PL_initialise() interprets all the command-line arguments, except for the -t toplevel flag that is interpreted by PL_toplevel().
int
main(int argc, char **argv)
{
#ifdef READLINE /* Remove if you don't want readline */
PL_initialise_hook(install_readline);
#endif
if ( !PL_initialise(argc, argv) )
PL_halt(1);
PL_halt(PL_toplevel() ? 0 : 1);
}
Special consideration is required for argv[0]. On Unix,
this argument passes the part of the command-line that is used to locate
the executable. Prolog uses this to find the file holding the running
executable. The Windows version uses this to find a module
of the running executable. If the specified module cannot be found, it
tries the module libpl.dll, containing the Prolog runtime
kernel. In all these cases, the resulting file is used for two purposes
boot.prc
file from the SWI-Prolog home directory. See also qsave_program/[1,2]
and section 9.7.
PL_initialise() returns 1 if all initialisation succeeded and 0 otherwise.bugVarious fatal errors may cause PL_initialise to call PL_halt(1), preventing it from returning at all.
In most cases, argc and argv will be passed
from the main program. It is allowed to create your own argument vector,
provided
argv[0] is constructed according to the rules above. For
example:
int
main(int argc, char **argv)
{ char *av[10];
int ac = 0;
av[ac++] = argv[0];
av[ac++] = "-x";
av[ac++] = "mystate";
av[ac] = NULL;
if ( !PL_initialise(ac, av) )
PL_halt(1);
...
}
Please note that the passed argument vector may be referred from Prolog at any time and should therefore be valid as long as the Prolog engine is used.
A good setup in Windows is to add SWI-Prolog's bin
directory to your PATH and either pass a module holding a
saved-state, or
"libpl.dll" as argv[0]. If the Prolog state is
attached to a DLL (see the -dll option of plld,
pass the name of this DLL.
FALSE if Prolog is not initialised and TRUE
otherwise. If the engine is initialised and argc is not NULL,
the argument count used with PL_initialise() is stored in argc.
Same for the argument vector argv.This function allows deleting and restarting the Prolog system in the same process. Use it with care, as PL_initialise() is a costly function. Unix users should consider using exec() (available as part of the clib package,).
if ( (pid=fork()) == 0 )
{ PL_cleanup_fork();
<some exec variation>
}
The call behaves the same on Windows, though there is probably no meaningful application.
FALSE when called from
another thread as the main one.bugEventually
it may become possible to call PL_halt() from any thread.
This section applies to Unix-based environments that have signals or multi-threading. The Windows version is compiled for multi-threading and Windows lacks proper signals.
We can distinguish two classes of embedded executables. There are small C/C++-programs that act as an interfacing layer around Prolog. Most of these programs can be replaced using the normal Prolog executable extended with a dynamically loaded foreign extension and in most cases this is the preferred route. In other cases, Prolog is embedded in a complex application that---like Prolog---wants to control the process environment. A good example is Java. Embedding Prolog is generally the only way to get these environments together in one process image. Java applications however are by nature multi-threaded and appear to do signal-handling (software interrupts).
To make Prolog operate smoothly in such environments it must be told not to alter the process environment. This is partly done at build-time and partly execution time. At build-time we must specify the use of software stack-overflow rather then the default hardware checks. This is done using
sh configure --disable-segv-handling
The resulting Prolog executable is about 10% slower than the normal executable, but behaves much more reliable in complicated embedded situations. In addition, as the process no longer handles segmentation violations, debugging foreign code linked to it is much easier.
At runtime, it is advised to pass the flag -nosignals, which inhibits all default signal handling. This has a few consequences though:
SIGPIPE is normally set to be ignored. Prolog uses
return-codes to diagnose broken pipes. Depending on the situation one
should take appropriate action if Prolog streams are connected to pipes.