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_PRUNED)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_PRUNED 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
or PL_PRUNED).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_PRUNED will follow.
The code of figure 6 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_PRUNED:
ctxt = PL_foreign_context_address(handle);
...
free(ctxt);
PL_succeed;
}
}
The following functions provide for communication using atoms and functors.
ATOM_nil
is the same as PL_new_atom("[]")
and ATOM_dot is the same as
PL_new_atom(".").
This is no long the case in SWI-Prolog version 7.
PL_new_functor(ATOM_dot,2).
It is adviced to use
PL_get_list(), PL_put_list()
or PL_unify_list()
where applicable.
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 multithreaded version (see chapter 9), 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.
PL_get_*() 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) )
{ ...;
}
Version 7 added PL_NIL, PL_BLOB,
PL_LIST_PAIR and PL_DICT. Older versions
classify PL_NIL and PL_BLOB as PL_ATOM,
PL_LIST_PAIR as PL_TERM and do not have dicts.
PL_VARIABLE | A variable or attributed variable |
PL_ATOM | A Prolog atom |
PL_NIL | The constant [] |
PL_BLOB | A blob (see section 10.4.7.2) |
PL_STRING | A string (see section 5.2) |
PL_INTEGER | A integer |
PL_FLOAT | A floating point number |
PL_TERM | A compound term |
PL_LIST_PAIR | A list cell ([H|T]) |
PL_DICT | A dict (see section 5.4)) |
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), that 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 no longer needed.
With the introduction of wide characters (see section
2.18.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.
BUF_* is provided, BUF_RING is implied.CVT_WRITE, but using write_canonical/2.CVT_WRITE, but using writeq/2.CVT_VARIABLE
and
CVT_WRITE*.PL_get_chars(l, s,
CVT_LIST|flags), provided flags
contains none 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 in 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:
(size_t)-1,
it is computed from s using strlen().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.
(size_t)-1,
it is computed from s using wcslen().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(); /* the elements */
term_t list = PL_copy_term_ref(l); /* copy (we modify list) */
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 [] */
}
Note that as of version 7, lists have a new representation unless the option --traditional is used. see section 5.1.
It is allowed to pass 0 for tail and NULL for len.
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.
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;
}
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().
true or false in the term
reference See also PL_put_atom(), PL_unify_bool()
and PL_get_bool().
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 10.4.20.
PL_unify_*() functions or use PL_cons_functor().TRUE. Note that in classical Prolog systems or in
SWI-Prolog using the option --traditional, this is the
same as
PL_put_atom_chars("[]").
See section 5.1.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();
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 section unify terms with other terms
or translated C data structures. Except for PL_unify(),
these functions are specific to SWI-Prolog. They have been introduced
because they shorten the code for returning data to Prolog and at the
same time make this more efficient by avoiding the need to allocate
temporary term references and reduce the number of calls to the Prolog
API. 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;
}
Note that unification functions that perform multiple bindings may leave part of the bindings in case of failure. See PL_unify() for details.
TRUE on success.
Care is needed if PL_unify()
returns FAIL and the foreign function does not immediately
return to Prolog with FAIL. Unification may perform
multiple changes to either t1 or t2. A failing
unification may have created bindings before failure is detected. Already
created bindings are not undone. For example, calling PL_unify()
on a(X, a) and a(c,b) binds
X to c and fails when trying to unify a
to
b. If control remains in C or even if we want to return
success to Prolog, we must undo such bindings. This is achieved
using
PL_open_foreign_frame()
and PL_rewind_foreign_frame(),
as shown in the snippet below.
{ fid_t fid = PL_open_foreign_frame();
...
if ( !PL_unify(t1, t2) )
PL_rewind_foreign_frame(fid);
...
PL_close_foreign_frame(fid);
}
In addition, PL_unify()
may have failed on an exception, typically a resource (stack)
overflow. This can be tested using
PL_exception(),
passing 0 (zero) for the query-id argument. Foreign functions that
encounter an exception must return FAIL to Prolog as soon
as possible or call PL_clear_exception()
if they wish to ignore the exception.
true or false.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. A Prolog type is one of PL_ATOM, PL_STRING,
PL_CODE_LIST or PL_CHAR_LIST. A representation
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
zero-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.
./2). If successful,
write a reference to the head of the list into h and a
reference to the tail of the list into 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);
}
[].
Special attention is required when passing numbers. C `promotes' any
integral smaller than int to int. That is, 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. Similarly, 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 bits 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 builds 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.
The typical implementation of a foreign predicate first uses the PL_get_*() functions to extract C data types from the Prolog terms. Failure of any of these functions is normally because the Prolog term is of the wrong type. The *_ex() family of functions are wrappers around (mostly) the PL_get_*() functions, such that we can write code in the style below and get proper exceptions if an argument is uninstantiated or of the wrong type.
/** set_size(+Name:atom, +Width:int, +Height:int) is det.
static foreign_t
set_size(term_t name, term_t width, term_t height)
{ char *n;
int w, h;
if ( !PL_get_chars(name, &n, CVT_ATOM|CVT_EXCEPTION) ||
!PL_get_integer_ex(with, &w) ||
!PL_get_integer_ex(height, &h) )
return FALSE;
...
}
int.long.int64_t.intptr_t.size_t.TRUE
and t is -1, p is filled with -1. Raises an
appropriate error if the conversion is not possible.The second family of functions in this section simplifies the
generation of ISO compatible error terms. Any foreign function that
calls this function must return to Prolog with the return code of the
error function or the constant FALSE. If available, these
error functions add the name of the calling predicate to the error
context. See also PL_raise_exception().
instantiation_error. Culprit is ignored,
but should be bound to the term that is insufficiently instantiated. See
instantiation_error/1.uninstantiation_error(culprit). This should be called
if an argument that must be unbound at entry is bound to culprit.
This error is typically raised for a pure output arguments such as a
newly created stream handle (e.g., the third argument of open/3).representation_error(resource). See representation_error/1.type_error(expected, culprit). See type_error/2.domain_error(expected, culprit). See domain_error/2.existence_error(type, culprit). See type_error/2.permission_error(operation, type, culprit). See
permission_error/3.
resource_error(resource). See resource_error/1.
syntax_error(message). If arg is not NULL,
add information about the current position of the input stream.
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 below. The structure contains additional fields at the
... for internal bookkeeping as well as future extensions.
typedef struct PL_blob_t
{ uintptr_t magic; /* PL_BLOB_MAGIC */
uintptr_t 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);
void (*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 fields 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 vice 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.
\cfuncref{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 \cfuncref{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.rdiv/2),
mpq is filled with the normalised rational number
and the function returns 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.TRUE on success. The mpz argument is not
changed.TRUE on success. Note that t is unified with an
integer if the denominator is 1. The mpq argument is not
changed.
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 then 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 be defined or not, redefined,
etc., a Prolog predicate has a handle that is neither destroyed nor
moved. This handle is known by the type predicate_t.
NULL, the current context module is used.NULL.
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 that 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. 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 meta-predicates. See meta_predicate/1,
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.
PL_open_query() can return the query identifier `0' if there is not enough space on the environment stack. This function succeeds, even if the referenced predicate is not defined. In this case, running the query using PL_next_solution() will return an existence_error. See PL_exception().
The example below opens a query to the predicate is_a/2
to find the ancestor of `me'. The reference to the predicate is valid
for the duration of the process and may be cached by the client.
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 8 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 set up the call and/or analyse the result can in most cases be discarded right after the call. PL_close_query() allows for destroying 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.
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;
}
Modules are identified via a unique handle. The following functions are available to query and manipulate modules.
:<rest>,
this function will make
plain a reference to <rest> and fill module
* with <module>. For further nested module
constructs the innermost module is returned via module *. If raw
is not a module construct, raw will simply be put in plain.
The value pointed to by m must be initialized before calling PL_strip_module(),
either to the default module or to NULL. A NULL
value is replaced by the current context module if raw
carries no module. 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 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 an 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 a 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);
}
}
Additionally, \cfuncref{PL_exception}{0} returns the
pending exception in the current query or 0 if no exception is pending.
This can be used to check the error status after a failing call to,
e.g., one of the unification functions.
SWI-Prolog offers both a C and Prolog interface to deal with software interrupts (signals). The Prolog mapping is defined in section 4.11. 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.
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.152A
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.
TRUE
on success, and FALSE if there is not enough space on the
stack to accommodate the term. See also PL_record()
and PL_erase().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 and 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_FILE_OSPATH must be provided to fetch a
filename in OS native (e.g., C:\x\y) notation.
Foreign code can set or create Prolog flags using PL_set_prolog_flag(). See set_prolog_flag/2 and create_prolog_flag/3.153The current C API does not provide for a dedicated mechanism for fetching the value of Prolog flags. Relatively slow access is provided by calling PL_call_predicate() using current_prolog_flag/2.
TRUE on success and FALSE on failure. This
function can be called before PL_initialise(),
making the flag available to the Prolog startup code.
PL_BOOLtrue or false) flag. The
argument must be an int.
PL_ATOMconst char *.
PL_INTEGERintptr_t *.
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
4.10.
[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.
int)
is the number of frames printed.int) is the exit code. See halt/1.char * to the current output stream.TRUE, the GMP allocations are
immediately bound to the Prolog functions. If FALSE,
SWI-Prolog will never rebind the GMP allocation functions. See
mp_set_memory_functions() in the GMP documentation. The action returns
FALSE if there is no GMP support or GMP is already
initialised.
PL_BT_SAFE
(0x1) and PL_BT_USER (0x2). PL_BT_SAFE causes
frames not to be printed as normal Prolog goals, but using the
predicate, program counter and clause-number. For example, the dump
below indicates the frame is executing the 2nd clause of
$autoload:load_library_index_p/0 at program pointer 25.
This can be interpreted by dumping the virtual machine code using vm_list/1.
[34] $autoload:load_library_index_p/0 [PC=19 in clause 2]
If the constant PL_BT_USER is specified, `no-debug'
frames are ignored. This predicate may be used from the C-debugger
(e.g., gdb) to get the Prolog stack at a crash location. Here is an
example dumping the top 20 frames of the Prolog stack.
(gdb) call PL_backtrace(20,0)
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_ENCODINGReturn the default stream encoding of Prolog (of type IOENC).PL_QUERY_USER_CPUGet amount of user CPU time of the process in milliseconds.
char *) and arity arity (a C int)
is created in module mod. If mod is 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 form a bitwise or'ed list of options for the installation. These are:
PL_FA_META | Provide meta-predicate info (see below) |
PL_FA_TRANSPARENT | Predicate is module transparent (deprecated) |
PL_FA_NONDETERMINISTIC | Predicate is non-deterministic. See also PL_retry(). |
PL_FA_NOTRACE | Predicate cannot be seen in the tracer |
PL_FA_VARARGS | Use alternative calling convention. |
If PL_FA_META is provided, PL_register_foreign_in_module()
takes one extra argument. This argument is of type const char*.
This string must be exactly as long as the number of arguments of the
predicate and filled with characters from the set 0-9:^-+?.
See
meta_predicate/1
for details. PL_FA_TRANSPARENT is implied if at least one
meta-argument is provided (0-9:^). Note that meta-arguments
are not always passed as <module>:<term>.
Always use PL_strip_module()
to extract the module and plain term from a meta-argument.155It
is encouraged to pass an additional NULL pointer for
non-meta-predicates.
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
10.4.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 are 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);
}
When combining foreign code with Prolog, it can be necessary to make data represented in the foreign language available to Prolog. For example, to pass it to another foreign function. At the end of this section, there is a partial implementation of using foreign functions to manage bit-vectors. Another example is the SGML/XML library that manages a `parser' object, an object that represents the current state of the parser and that can be directed to perform actions such as parsing a document or make queries about the document content.
This section provides some hints for handling foreign data in Prolog. There are four options for storing such data:
The choice may be guided using the following distinctions
In this section, we 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. Then, 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,
the 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.41) 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 use 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, nor to verify that 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 with 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 10.5.
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 swipl-ld),
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.The function returns TRUE if successful and FALSE
otherwise. Currently, FALSE is returned when an attempt is
made to call PL_cleanup()
recursively or if one of the exit handlers cancels the termination using cancel_halt/1.
Exit handlers may only cancel termination if status is 0.
In theory, this function allows deleting and restarting the Prolog system in the same process. In practice, SWI-Prolog's cleanup process is far from complete, and trying to revive the system using PL_initialise() will leak memory in the best case. It can also crash the appliction.
In this state, there is little practical use for this function. If you want to use Prolog temporarily, consider running it in a separate process. If you want to be able to reset Prolog, your options are (again) a separate process, modules or threads.
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
if exit was cancelled by PL_cleanup().
This section applies to Unix-based environments that have signals or multithreading. The Windows version is compiled for multithreading, 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 multithreaded and appear to do signal handling (software interrupts).
On Unix systems, SWI-Prolog uses three signals:
EINTR, which
gives them the opportunity to react to thread-signals.The --nosignals option can be used to inhibit
processing of SIGINT. The other signals are vital for the
functioning of SWI-Prolog. If they conflict with other applications,
signal handling of either component must be modified. The SWI-Prolog
signals are defined in
pl-thread.h of the source distribution.