At this moment there are two versions of the C++ interface.
SWI-cpp.h and described in chapter
1. This version is old, suffers from several ambiguities, covers
only the core part of the C interface and does not support character
encoding issues, which implies
char* can only be used to exchange text in ISO-Latin-1
encoding. We hope to deprecate this interface soon.SWI-cpp2.h and SWI-cpp2.cpp
and described in chapter 2. This is a
much more mature C++ interface has been designed and implemented by
Peter Ludemann. We plan to make this the preferred interface soon. There
are still several issues that need to be fully resolved and implemented
before this can happen, mostly related to handling text encoding.
C++ provides a number of features that make it possible to define a much more natural and concise interface to dynamically typed languages than plain C does. Using programmable type-conversion (casting), native data-types can be translated automatically into appropriate Prolog types, automatic destructors can be used to deal with most of the cleanup required and C++ exception handling can be used to map Prolog exceptions and interface conversion errors to C++ exceptions, which are automatically mapped to Prolog exceptions as control is turned back to Prolog.
Volker Wysk has defined an alternative C++ mapping based on templates and compatible to the STL framework. See http://www.volker-wysk.de/swiprolog-c++/index.html.
I would like to thank Anjo Anjewierden for comments on the definition, implementation and documentation of this package.
The most useful area for exploiting C++ features is type-conversion.
Prolog variables are dynamically typed and all information is passed
around using the C-interface type term_t. In C++, term_t
is embedded in the lightweight class PlTerm.
Constructors and operator definitions provide flexible operations and
integration with important C-types (char *, wchar_t*,
long and double).
The list below summarises the classes defined in the C++ interface.
[]type_error exception.domain_error exception.existence_error exception.permission_error exception.The required C(++) function header and registration of a predicate is arranged through a macro called PREDICATE().
Before going into a detailed description of the C++ classes we present a few examples illustrating the‘feel' of the interface.
This simple example shows the basic definition of the predicate hello/1 and how a Prolog argument is converted to C-data:
PREDICATE(hello, 1)
{ cout << "Hello " << (char *)A1 << endl;
return TRUE;
}
The arguments to PREDICATE() are the name and arity of the predicate.
The macros A<n> provide access to the predicate
arguments by position and are of the type PlTerm.
Casting a PlTerm to a
char * or wchar_t * provides the natural
type-conversion for most Prolog data-types, using the output of write/1
otherwise:
?- hello(world). Hello world Yes ?- hello(X) Hello _G170 X = _G170
This example shows arithmetic using the C++ interface, including unification, type-checking and conversion. The predicate add/3 adds the two first arguments and unifies the last with the result.
PREDICATE(add, 3)
{ return A3 = (long)A1 + (long)A2;
}
Casting a PlTerm to a long
performs a PL_get_long() and throws a C++ exception if the Prolog
argument is not a Prolog integer or float that can be converted without
loss to a long. The
=TRUE or FALSE
depending on the result.
?- add(1, 2, X). X = 3. ?- add(a, 2, X). [ERROR: Type error: `integer' expected, found `a'] Exception: ( 7) add(a, 2, _G197) ?
This example is a bit harder. The predicate average/3 is defined to take the template average(+Var, :Goal, -Average) , where Goal binds Var and will unify Average with average of the (integer) results.
PlQuery takes the name of a
predicate and the goal-argument vector as arguments. From this
information it deduces the arity and locates the predicate. the
member-function next_solution() yields
TRUE if there was a solution and FALSE
otherwise. If the goal yielded a Prolog exception it is mapped into a
C++ exception.
PREDICATE(average, 3)
{ long sum = 0;
long n = 0;
PlQuery q("call", PlTermv(A2));
while( q.next_solution() )
{ sum += (long)A1;
n++;
}
return A3 = (double)sum/(double)n;
}
As we have seen from the examples, the PlTerm class plays a central role in conversion and operating on Prolog data. This section provides complete documentation of this class.
void *.
PREDICATE(make_my_object, 1)
{ myclass *myobj = new myclass();
return A1 = (void *)myobj;
}
PREDICATE(free_my_object, 1)
{ myclass *myobj = (void *)A1;
delete(myobj);
return TRUE;
}
PlTerm can be cast to the following types:
long if the PlTerm
is a Prolog integer or float that can be converted without loss to a
long. throws a
type_error exception otherwise.long, but might represent fewer bits.CVT_ALL|CVT_WRITE|BUF_RING, which implies Prolog atoms and
strings are converted to the represented text. All other data is handed
to write/1. If
the text is static in Prolog, a direct pointer to the string is
returned. Otherwise the text is saved in a ring of 16 buffers and must
be copied to avoid overwriting.
=long, double, char *, wchar_t*
and
PlAtom. It performs Prolog
unification and returns TRUE if successful and FALSE
otherwise.
The boolean return-value leads to somewhat unconventional-looking code as normally, assignment returns the value assigned in C. Unification however is fundamentally different to assignment as it can succeed or fail. Here is a common example.
PREDICATE(hostname, 1)
{ char buf[32];
if ( gethostname(buf, sizeof(buf)) == 0 )
return A1 = buf;
return FALSE;
}
long
and perform standard C-comparison between the two long integers. If PlTerm
cannot be converted a type_error is raised.TRUE if the PlTerm
is an atom or string representing the same text as the argument, FALSE
if the conversion was successful, but the strings are not equal and an
type_error exception if the conversion failed.Below are some typical examples. See section 1.6 for direct manipulation of atoms in their internal representation.
A1 < 0 | Test A1 to hold a Prolog integer or float that can be transformed lossless to an integer less than zero. |
A1 < PlTerm(0) | A1
is before the term‘0' in the‘standard order of terms'. This
means that if A1 represents an atom, this test yields TRUE. |
A1 == PlCompound("a(1)") | Test A1
to represent the term
a(1). |
A1 == "now" | Test A1 to be an atom or string holding the text “now''. |
Compound terms can be viewed as an array of terms with a name and
arity (length). This view is expressed by overloading the []
A type_error is raised if the argument is not compound
and a
domain_error if the index is out of range.
In addition, the following functions are defined:
type_error is raised. Id arg is out of range, a
domain_error is raised. Please note the counting from 1
which is consistent to Prolog's arg/3
predicate, but inconsistent to C's normal view on an array. See also
class PlCompound. The following
example tests x to represent a term with first-argument an
atom or string equal to gnat.
...,
if ( x[1] == "gnat" )
...
const char * holding the name of the functor of
the compound term. Raises a type_error if the argument is
not compound.type_error
if the argument is not compound.
PL_VARIABLE, PL_FLOAT, PL_INTEGER,
PL_ATOM, PL_STRING or PL_TERMTo avoid very confusing combinations of constructors and therefore possible undesirable effects a number of subclasses of PlTerm have been defined that provide constructors for creating special Prolog terms. These subclasses are defined below.
A SWI-Prolog string represents a byte-string on the global stack. It's lifetime is the same as for compound terms and other data living on the global stack. Strings are not only a compound representation of text that is garbage-collected, but as they can contain 0-bytes, they can be used to contain arbitrary C-data structures.
Character lists are compliant to Prolog's atom_chars/2 predicate.
syntax_error exception is raised. Otherwise a new
term-reference holding the parsed text is created.hello(world).
PlCompound("hello", PlTermv("world"))
The class PlTail is both for analysing and constructing lists. It is called PlTail as enumeration-steps make the term-reference follow the‘tail' of the list.
"gnat",
a list of the form [gnat|B] is created and the PlTail
object now points to the new variable B.
This function returns TRUE if the unification succeeded
and
FALSE otherwise. No exceptions are generated.
The example below translates the main() argument vector to Prolog and calls the prolog predicate entry/1 with it.
int
main(int argc, char **argv)
{ PlEngine e(argv[0]);
PlTermv av(1);
PlTail l(av[0]);
for(int i=0; i<argc; i++)
l.append(argv[i]);
l.close();
PlQuery q("entry", av);
return q.next_solution() ? 0 : 1;
}
[]TRUE
on success and FALSE if
PlTail represents the empty list.
If PlTail is neither a list nor the
empty list, a type_error is thrown. The example below
prints the elements of a list.
PREDICATE(write_list, 1)
{ PlTail tail(A1);
PlTerm e;
while(tail.next(e))
cout << (char *)e << endl;
return TRUE;
}
The class PlTermv represents an array of term-references. This type is used to pass the arguments to a foreignly defined predicate, construct compound terms (see PlTerm::PlTerm(const char *name, PlTermv arguments)) and to create queries (see PlQuery).
The only useful member function is the overloading of []domain_error exception.
The constructors for this class are below.
load_file(const char *file)
{ return PlCall("compile", PlTermv(file));
}
If the vector has to contain more than 5 elements, the following construction should be used:
{ PlTermv av(10);
av[0] = "hello";
...
Both for quick comparison as for quick building of lists of atoms, it is desirable to provide access to Prolog's atom-table, mapping handles to unique string-constants. If the handles of two atoms are different it is guaranteed they represent different text strings.
Suppose we want to test whether a term represents a certain atom, this interface presents a large number of alternatives:
Example:
PREDICATE(test, 1)
{ if ( A1 == "read" )
...;
This writes easily and is the preferred method is performance is not critical and only a few comparisons have to be made. It validates A1 to be a term-reference representing text (atom, string, integer or float) extracts the represented text and uses strcmp() to match the strings.
Example:
static PlAtom ATOM_read("read");
PREDICATE(test, 1)
{ if ( A1 == ATOM_read )
...;
This case raises a type_error if A1 is not an
atom. Otherwise it extacts the atom-handle and compares it to the
atom-handle of the global PlAtom
object. This approach is faster and provides more strict type-checking.
Example:
static PlAtom ATOM_read("read");
PREDICATE(test, 1)
{ PlAtom a1(A1);
if ( a1 == ATOM_read )
...;
This approach is basically the same as section 1.6, but in nested if-then-else the extraction of the atom from the term is done only once.
Example:
PREDICATE(test, 1)
{ PlAtom a1(A1);
if ( a1 == "read" )
...;
This approach extracts the atom once and for each test extracts the represented string from the atom and compares it. It avoids the need for global atom constructors.
type_error is thrown.TRUE if the atom represents text, FALSE
otherwise. Performs a strcmp() for this.TRUE or
FALSE.
This class encapsulates PL_register_foreign(). It is defined as a class rather then a function to exploit the C++ global constructor feature. This class provides a constructor to deal with the PREDICATE() way of defining foreign predicates as well as constructors to deal with more conventional foreign predicate definitions.
PL_FA_VARARGS calling convention, where the argument
list of the predicate is passed using an array of term_t
objects as returned by PL_new_term_refs(). This interface poses
no limits on the arity of the predicate and is faster, especially for a
large number of arguments.
static foreign_t
pl_hello(PlTerm a1)
{ ...
}
PlRegister x_hello_1(NULL, "hello", 1, pl_hello);
This construct is currently supported upto 3 arguments.
This class encapsulates the call-backs onto Prolog.
user.TRUE if
successful and FALSE if there are no (more) solutions.
Prolog exceptions are mapped to C++ exceptions.Below is an example listing the currently defined Prolog modules to the terminal.
PREDICATE(list_modules, 0)
{ PlTermv av(1);
PlQuery q("current_module", av);
while( q.next_solution() )
cout << (char *)av[0] << endl;
return TRUE;
}
In addition to the above, the following functions have been defined.
The class PlFrame provides an interface to discard unused term-references as well as rewinding unifications (data-backtracking). Reclaiming unused term-references is automatically performed after a call to a C++-defined predicate has finished and returns control to Prolog. In this scenario PlFrame is rarely of any use. This class comes into play if the toplevel program is defined in C++ and calls Prolog multiple times. Setting up arguments to a query requires term-references and using PlFrame is the only way to reclaim them.
A typical use for PlFrame is the definition of C++ functions that call Prolog and may be called repeatedly from C++. Consider the definition of assertWord(), adding a fact to word/1:
void
assertWord(const char *word)
{ PlFrame fr;
PlTermv av(1);
av[0] = PlCompound("word", PlTermv(word));
PlQuery q("assert", av);
q.next_solution();
}
This example shows the most sensible use of PlFrame if it is used in the context of a foreign predicate. The predicate's thruth-value is the same as for the Prolog unification (=/2), but has no side effects. In Prolog one would use double negation to achieve this.
PREDICATE(can_unify, 2)
{ PlFrame fr;
int rval = (A1=A2);
fr.rewind();
return rval;
}
The PREDICATE macro is there to make your code look nice, taking care of the interface to the C-defined SWI-Prolog kernel as well as mapping exceptions. Using the macro
PREDICATE(hello, 1)
is the same as writing:
static foreign_t pl_hello__1(PlTermv PL_av);
static foreign_t
_pl_hello__1(term_t t0, int arity, control_t ctx)
{ (void)arity; (void)ctx;
try
{ return pl_hello__1(PlTermv(1, t0));
} catch ( PlTerm &ex )
{ return ex.raise();
}
}
static PlRegister _x_hello__1("hello", 1, _pl_hello__1);
static foreign_t
pl_hello__1(PlTermv PL_av)
The first function converts the parameters passed from the Prolog kernel to a PlTermv instance and maps exceptions raised in the body to Prolog exceptions. The PlRegister global constructor registers the predicate. Finally, the function header for the implementation is created.
The PREDICATE() macros has a number of variations that deal with special cases.
PL_av is not used.
NAMED_PREDICATE("#", hash, 2)
{ A2 = (wchar_t*)A1;
}
SWI-cpp.h. FIXME: Needs cleanup and an example.
With no special precautions, the predicates are defined into the
module from which load_foreign_library/1
was called, or in the module
user if there is no Prolog context from which to deduce the
module such as while linking the extension statically with the Prolog
kernel.
Alternatively, before loading the SWI-Prolog include file, the macro PROLOG_MODULE may be defined to a string containing the name of the destination module. A module name may only contain alpha-numerical characters (letters, digits, _). See the example below:
#define PROLOG_MODULE "math"
#include <SWI-Prolog.h>
#include <math.h>
PREDICATE(pi, 1)
{ A1 = M_PI;
}
?- math:pi(X). X = 3.14159
Prolog exceptions are mapped to C++ exceptions using the subclass PlException of PlTerm to represent the Prolog exception term. All type-conversion functions of the interface raise Prolog-compliant exceptions, providing decent error-handling support at no extra work for the programmer.
For some commonly used exceptions, subclasses of PlException have been created to exploit both their constructors for easy creation of these exceptions as well as selective trapping in C++. Currently, these are PlTypeEror and PlDomainError.
To throw an exception, create an instance of PlException and use throw().
char *data = "users";
throw PlException(PlCompound("no_database", PlTerm(data)));
The C++ model of exceptions and the Prolog model of exceptions are
different. Wherever the underlying function returns a "fail" return
code, the C++ API does a further check for whether there's an exception
and, if so, does a C++ throw of a PlException
object. You can use C++ try-catch to intercept this and examine the
This subclass of PlTerm is used to represent exceptions. Currently defined methods are:
...;
try
{ PlCall("consult(load)");
} catch ( PlException &ex )
{ cerr << (char *) ex << endl;
}
error(type_error(Expected, Actual), Context)
PlException::cppThrow() throws a PlTypeEror exception. This ensures consistency in the exception-class whether the exception is generated by the C++-interface or returned by Prolog.
The following example illustrates this behaviour:
PREDICATE(call_atom, 1)
{ try
{ return PlCall((char *)A1);
} catch ( PlTypeError &ex )
{ cerr << "Type Error caugth in C++" << endl;
cerr << "Message: \"" << (char *)ex << "\"" << endl;
return FALSE;
}
}
A type error expresses that a term does not satisfy the expected basic Prolog type.
A domain error expresses that a term satisfies the basic
Prolog type expected, but is unacceptable to the restricted domain
expected by some operation. For example, the standard Prolog open/3
call expect an io_mode (read, write, append, ...). If an
integer is provided, this is a type error, if an atom other
than one of the defined io-modes is provided it is a domain error.
Most of the above assumes Prolog is‘in charge' of the application and C++ is used to add functionality to Prolog, either for accessing external resources or for performance reasons. In some applications, there is a main-program and we want to use Prolog as a logic server. For these applications, the class PlEngine has been defined.
Only a single instance of this class can exist in a process. When used in a multi-threading application, only one thread at a time may have a running query on this engine. Applications should ensure this using proper locking techniques.1For Unix, there is a multi-threaded version of SWI-Prolog. In this version each thread can create and destroy a thread-engine. There is currently no C++ interface defined to access this functionality, though ---of course--- you can use the C-functions.
argv[0]
from its main function, which is needed in the Unix version to find the
running executable. See PL_initialise() for details.argv[0].Section 1.4.11 has a simple example using this class.
Not all functionality of the C-interface is provided, but as
PlTerm and term_t are
essentially the same thing with automatic type-conversion between the
two, this interface can be freely mixed with the functions defined for
plain C.
Using this interface rather than the plain C-interface requires a
little more resources. More term-references are wasted (but reclaimed on
return to Prolog or using PlFrame).
Use of some intermediate types (functor_t etc.) is not
supported in the current interface, causing more hash-table lookups.
This could be fixed, at the price of slighly complicating the interface.
The mechanisms outlined in this document can be used for static linking with the SWI-Prolog kernel using swipl-ld(1). In general the C++ linker should be used to deal with the C++ runtime libraries and global constructors.
The current interface is entirely defined in the .h file
using inlined code. This approach has a few advantages: as no C++ code
is in the Prolog kernel, different C++ compilers with different
name-mangling schemas can cooperate smoothly.
Also, changes to the header file have no consequences to binary compatibility with the SWI-Prolog kernel. This makes it possible to have different versions of the header file with few compatibility consequences.
In this document, we presented a high-level interface to Prolog exploiting automatic type-conversion and exception-handling defined in C++.
Programming using this interface is much more natural and requires only little extra resources in terms of time and memory.
Especially the smooth integration between C++ and Prolog exceptions reduce the coding effort for type checking and reporting in foreign predicates.
Version 1 is in SWI-cpp.h; version 2 is in SWI-cpp2.h,
SWI-cpp2.cpp, and SWI-cpp2-plx.h.
The overall structure of the API has been retained - that is, it is a
thin layer on top of the interface provided by
SWI-Prolog.h. Based on experience with the API, most of the
conversion operators and some of the comparison operators have been
removed or deprecated, and replaced by "getter" methods. The overloaded
constructors have been replaced by subclasses for the various types.
Some changes were also made to ensure that the
[]PlTerm and PlTermv
doesn't cause unexpected implicit conversions.
2If there is an implicit
conversion operator from PlTerm to term_t and
also to char*, then the []f is overloaded to accept a term_t
or char* in the code PlTerm t=...; f(t[0])
Prolog exceptions are now converted to C++ exceptions (which contain
the exception term rather being a subclass of PlTerm as in
version 1), where they can be caught and thrown using the usual C++
mechanisms; and the subclasses that create exceptions have been changed
to functions. In addition, a PlFail has been added, to
allow "short circuit" return to Prolog on failure.
More specifically:
SWI-cpp2.cpp has been added, containing the
implementation of some functions that are too long to inline. The user
must either #include <SWI-cpp2.cpp> or compile it
separately and link it with the other foreign function code.SWI-Prolog.h, and have the same names with the “PL''
replaced by “Plx''.3 “Pl''
is used throughout the SWI-cpp2.h interface, and the “x''
is for “eXtended with eXception handling.'' Where
appropriate, these check return codes and throw a C++ exception (created
from the Prolog error). See section
2.4.4 Many of these wrapper functions have been added to the PlAtom
and PlTerm classes, with the arguments changed from
atom_t and term_t to PlAtom and PlTerm.
These wrappers are available if you include SWI-cpp2.h
(they are in a separate SWI-cpp2-plx.h file for ease of
maintenance).false from a foreign predicate to
indicate failure, you can use throw PlFail(). The
convenience function PlCheckFail(rc) can be used to throw
PlFail() if false is returned from a function in
SWI-Prolog.h. If the wrapper functions or class methods are
used, Prolog errors result in a C++ PlException exception.4If
a “Plx_'' wrapper is used to call a SWI-Prolog.h
function, a Prolog error will have already resulted in throwing PlException;‘cfuncrefPlCheckFailrc
is used to additionally throw PlFail, similar to returning false
from the top-level of a foreign predicate.PlException class is a subclass of std::excxeption
and encapsulates a Prolog error. Prolog errors are converted into throw
PlException(...). If the user code does not catch the PlException,
the PREDICATE() macro converts the error to a Prolog error upon return
to the Prolog caller.(char*)t, (int64_t)t)
have been deprecated, replaced by "getters" (e.g.,
t.as_string(), t.as_int64_t()).5The
form (char*)t is a C-style cast; C++'s preferred form is
more verbose: static_cast<char*>(t).std::string, comparison operators. The as_string() method
allows specifying the encoding to use whereas the ==char* have been replaced by methods
that return std::string to ensure that lifetime issues
don't cause subtle bugs.6If you
want to return a char* from a function, you should not do return
t.as_string().c_str() because that will return a pointer to local
or stack memory. Instead, you should change your interface to return a std::string
and apply the c_str() method to it. These lifetime errors
can sometimes be caught by specifying the Gnu C++ or Clang
options -Wreturn-stack-address or -Wreturn-local-addr
- as of 2023-04, Clang seems to do a better analysis.char*
arguments also accept std::string or std::wstring
arguments. Where possible, encoding information can also be specified.PlString has been renamed to PlTerm_string
to make it clear that it's a term that contains a Prolog string.PL_...(term_t, ...) methods have been added to PlTerm,
and PL_...(atom_t, ...) methods have been added to PlAtom.
Where appopriate, the arguments use PlTerm, PlAtom,
etc. instead of term_t, atom_t, etc.std::string and std::wstring are now
supported in most places where char* or wchar_t*
are allowed.int for
true/false now return a C++ bool.term_t, atom_t,
etc.) have been renamed from handle, ref, etc.
to
C_.7This is done by
subclassing from Wrapped<term_t>, Wrapped<atom_t>,
etc., which define the field C_, standard constructors, the
methods is_null(), not_null(), reset(),
and reset(v), plus the constant null.PlForeignContextPtr<ContextType>
has been added, to simplify dynamic memory allocation in
non-deterministic predicates.PlStringBuffers provides a simpler interface for
allocating strings on the stack than PL_STRINGS_MARK() and PL_STRINGS_RELEASE().record_t have been added. The
PlRecordExternalCopy class contains the opaque handle, as a
convenience.control_t has been added and the
PREDICATE_NONDET() has been modified to use it.More details are given in section 2.6 and section 2.7.
C++ provides a number of features that make it possible to define a more natural and concise interface to dynamically typed languages than plain C does. Using programmable type-conversion (casting) and overloading, native data-types can be easily translated into appropriate Prolog types, automatic destructors can be used to deal with most of the cleanup required and C++ exception handling can be used to map Prolog exceptions and interface conversion errors to C++ exceptions, which are automatically mapped to Prolog exceptions as control is turned back to Prolog.
However, there are subtle differences between Prolog and C++ that can lead to confusion; in particular, the lifetime of terms do not fit well with the C++ notion of constructor/destructor. It might be possible to handle this with "smart pointers", but that would lead to other complications, so the decision was made to provide a thin layer between the underlying C functions and the C++ classes/methods/functions.
More information on the SWI-Prolog native types is given in Interface Data Types.
It would be tempting to use C++ implicit conversion operators and
method overloading to automatically convert between C++ types such as
std::string and int64_t and Prolog foreign
language interface types such as term_t and atom_t.
However, types such as term_t are unsigned integers, so
many of the automatic type conversions can easily do something other
than what the programmer intended, resulting in subtle bugs that are
difficult to find. Therefore Version 2 of this interface reduces the
amount of automatic conversion and introduces some redundancy, to avoid
these subtle bugs, by using "getter" methods rather than conversion
operators, and using naming conventions for explicitly specifying
constructors.
I would like to thank Anjo Anjewierden for comments on the definition, implementation and documentation of this package. Peter Ludemann modified the interface to remove some pitfalls, and also added some convenience functions (see section 2.1).
A foreign predicate is defined using the PREDICATE() macro,
pPlus a few variations on this, such as
PREDICATE_NONDET(), NAMED_PREDICATE(),
and
NAMED_PREDICATE_NONDET().
This defines an internal name for the function, registers it with the
SWI-Prolog runtime (where it will be picked up by the use_foreign_library/1
directive), and defines the names A1, A2, etc.
for the arguments.8You can define
your own names for the arguments, for example: auto x=A1, y=A2,
result=A3;. If a non-deterministic predicate is
being defined, an additional parameter handle is defined
(of type
PlControl).
The foreign predicate returns a value of true or false
to indicate whether it succeeded or failed.9Non-deterministic
predicates can also return a "retry" value. If a predicate
fails, it could be simple failure (the equivalent of calling the builtin fail/0
predicate) or an error (the equivalent of calling the throw/1
predicate). When a Prolog exception is raised, it is important that a
return be made to the calling environment as soon as possible. In C
code, this requires checking every call for failure, which can become
cumbersome. C++ has exceptions, so instead the code can wrap calls to
PL_*() functions with PlCheck_PL() or
PlCheckEx(), which will throw a PlException() to exit from the
top level of the foreign predicate, and handle the failure or exception
appropriately.
The following three snippets do the same thing (for implementing the equivalent of =/2):
PREDICATE(eq, 2)
{ PlCheckFail(A1.unify_term(A2));
return true;
}
PREDICATE(eq, 2)
{ return A1.unify_term(A2);
}
PREDICATE(eq, 2)
{ return PlWrap<int>(PL_unify(A1.C_, A2.C_));
}
The most useful area for exploiting C++ features is type-conversion.
Prolog variables are dynamically typed and all information is passed
around using the C-interface type term_t. In C++, term_t
is embedded in the lightweight class PlTerm.
Constructors and operator definitions provide flexible operations and
integration with important C-types (char *, wchar_t*,
long and double), plus the C++-types (std::string,
std::wstring).
See also section 2.4.5.
The general philosophy for C++ classes is that a "half-created" object should not be possible - that is, the constructor should either succeed with a completely usable object or it should throw an exception. This API tries to follow that philosophy, but there are some important exceptions and caveats. (For more on how the C++ and Prolog exceptions interrelate, see section 2.17.)
The various classes (PlAtom, PlTerm, etc.)
are thin wrappers around the C interface's types (atom_t,
term_t, etc.). As such, they inherit the concept of "null"
from these types (which is abstracted as PlAtom::null,
PlTerm::null, etc., which typically is equivalent to
0). Normally, you shouldn't need to check whether the
object is "fully created", but if you do, you can use the methods
is_null() or not_null().
Most of the classes have constructors that create a "complete" object. For example,
PlAtom foo("foo");
will ensure that the object foo is useable and will
throw an exception if the atom can't be created. However, if you choose
to create an PlAtom object from a atom_t
value, no checking is done (similarly, no checking is done if you create
a PlTerm object using the PlTerm_term_t
constructor).
To help avoid programming errors, most of the classes do not have a
default "empty" constructor. For example, if you with to create a
PlAtom that is uninitialized, you must explicitly use
PlAtom(PlAtom::null). This make some code a bit more
cumbersome because you can't omit the default constructors in struct
initalizers.
Many of the classes wrap long-lived items, such as atoms, functors,
predicates, or modules. For these, it's often a good idea to define them
as static variables that get created at load time, so that
a lookup for each use isn't needed (atoms are unique, so
PlAtom("foo") requires a lookup for an atom foo
and creates one if it isn't found).
C code sometimes creates objects "lazily" on first use:
void my_function(...)
{ static atom_t ATOM_foo = 0;
...
if ( ! foo )
foo = PL_new_atom("foo");
...
}
For C++, this can be done in a simpler way, because C++ will call a
local “static” constructor on first use.
void my_function(...)
{ static PlAtom ATOM_foo("foo");
}
The class PlTerm (which wraps term_t) is
the most used. Although a PlTerm object can be created from
a term_t value, it is intended to be used with a
constructor that gives it an initial value. The default constructor
calls PL_new_term_ref() and throws an exception if this fails.
The various constructors are described in
section 2.9.1. Note that the
default constructor is not public; to create a "variable" term, you
should use the subclass constructor PlTerm_var().
The following files are provided:
SWI-cpp2.h Include this file to get the C++ API. It
automatically includes
SWI-cpp2-plx.h but does not include SWI-cpp2.cpp.
SWI-cpp2.cpp Contains the implementations of some
methods and functions. It must be compiled as-is or included in the
foreign predicate's source file. Alternatively, it can be included with
each include of
SWI-cpp2.h with this macro definition:
#define _SWI_CPP2_CPP_inline inline
SWI-cpp2-plx.h Contains the wrapper functions for the
most of the functions in
SWI-Prolog.h. This file is not intended to be used by
itself, but is #included by SWI-cpp2.h.
test_cpp.cpp, test_cpp.pl Contains various
tests, including some longer sequences of code that can help in
understanding how the C++ API is intended to be used. In addition, there
are test_ffi.cpp, test_ffi.pl, which often
have the same tests written in C, without the C++ API.
The list below summarises the classes defined in the C++ interface.
term_t (for more details on
term_t, see
Interface
Data Types). This is a "base class" whose constructor is protected;
subclasses specify the actual contents. Additional methods allow
checking the Prolog type, unification, comparison, conversion to native
C++-data types, etc. See section 2.9.3.
The subclass constructors are as follows. If a constructor fails
(e.g., out of memory), a PlException is thrown.
PlTerm with constructors for building a term
that contains an atom.PlTerm with constructors for building a term
that contains an uninstantiated variable. Typically this term is then
unified with another object.PlTerm with constructors for building a term
from a C term_t.PlTerm with constructors for building a term
that contains a Prolog integer from a
long.10PL_put_integer()
takes a long argument.PlTerm with constructors for building a term
that contains a Prolog integer from a int64_t.PlTerm with constructors for building a term
that contains a Prolog integer from a uint64_t.PlTerm with constructors for building a term
that contains a Prolog integer from a size_t.PlTerm with constructors for building a term
that contains a Prolog float.PlTerm with constructors for building a term
that contains a raw pointer. This is mainly for backwards compatibility;
new code should use blobs.PlTerm with constructors for building a term
that contains a Prolog string object.PlTerm with constructors for building Prolog
lists of character integer values.PlTerm with constructors for building Prolog
lists of one-character atoms (as atom_chars/2).PlTerm for building and analysing Prolog lists.
Additional subclasses of PlTerm are:
PlTerm with constructors for building compound
terms. If there is a single string argument, then PL_chars_to_term()
or PL_wchars_to_term() is used to parse the string and create the
term. If the constructor has two arguments, the first is name of a
functor and the second is a PlTermv with the arguments.[]PlTermv
is used to build complex terms and provide argument-lists to Prolog
goals.std::exception, representing a Prolog
exception. Provides methods for the Prolog communication and mapping to
human-readable text representation.
PlException object for representing a Prolog
type_error exception.PlException object for representing a Prolog
domain_error exception.PlException object for representing a Prolog
existence_error exception.PlExceptionobject for representing a Prolog
permission_error exception.atom_t) in their internal
Prolog representation for fast comparison. (For more details on
atom_t, see
Interface
Data Types).functor_t, which maps to the internal
representation of a name/arity pair.predicate_t, which maps to the internal
representation of a Prolog predicate.module_t, which maps to the internal
representation of a Prolog module.return false instead
if failure is expected. An error can be signaled by calling
Plx_raise_exception() or one of the PL_*_error() functions and then
throwing PlFail; but it's better style to create the error
throwing one of the subclasses of PlException e.g.,
throw PlTypeError("int", t).PlException object and throws it. If the
enclosing code doesn't intercept the exception, the PlException
object is turned back into a Prolog error.PlException object, so a PlExceptionFail
object is thrown. This is turned into failure by the PREDICATE()
macro, resulting in normal Prolog error handling.The required C++ function header and registration of a predicate is arranged through a macro called PREDICATE().
The various PL_*() functions in SWI-Prolog.h have
corresponding Plx_*() functions. There are three kinds of wrappers:
false,
indicating an error. The Plx*() function checks for this and throws a PlException
object containing the error. The wrapper uses template<typename
C_t> C_t PlExce(C_t rc), where C_t is the return
type of the PL_*() function. (These are defined using the PLX_WRAP()
macro.)
true if it succeeds and false if it fails or
has a runtime error. If it fails, the wrapper checks for a Prolog error
and throws a PlException object containing the error. The
wrapper uses template<typename C_t> C_t PlWrap(C_t rc),
where C_t is the return type of the PL_*() function. (These
are defined using the PLX_EXCE() macro.)
A few PL_*() functions do not have a corresponding Plx*() function
because they do not fit into one of these categories. For example,
PL_next_solution() has multiple return values (PL_S_EXCEPTION,
PL_S_LAST, etc.) if the query was opened with the
PL_Q_EXT_STATUS flag.
Most of the PL_*() functions whose first argument is of type
term_t, atom_t, etc. have corresponding
methods in classes PlTerm, PlAtom, etc.
See also section 2.4.1.
The classes all have names starting with "Pl", using CamelCase; this contrasts with the C functions that start with "PL_" and use underscores.
The wrapper classes (PlFunctor, PlAtom,
PlTerm), etc. all contain a field C_ that
contains the wrapped value (functor_t, atom_t, term_t
respectively).
The wrapper classes (which subclass WrappedC< ...)
all define the following methods and constants:
null)PlAtom,
the constructor takes an atom_t value).C_ - the wrapped value. This can be used directly when
calling C functions, for example, if t and a
are of type PlTerm and PlAtom: Plcheck_PL(PL_put_atom(t.C_,a.C_)).null - the null value (typically 0, but
code should not rely on this)is_null(), not_null() - test for the
wrapped value being null.reset() - set the wrapped value to nullreset(new_value) - set the wrapped valuebool operator is turned off - you should use
not_null() instead.11The reason: a bool
conversion causes ambiguity with PlAtom(PlTterm) and PlAtom(atom_t).
The C_ field can be used wherever a atom_t
or
term_t is used. For example, the PL_scan_options()
example code can be written as follows. Note the use of &callback.C_
to pass a pointer to the wrapped term_t value.
PREDICATE(mypred, 2)
{ auto options = A2;
int quoted = false;
size_t length = 10;
PlTerm_var callback;
PlCheck_L(PL_scan_options(options, 0, "mypred_options", mypred_options,
"ed, &length, &callback.C_));
callback.record(); // Needed if callback is put in a blob that Prolog doesn't know about.
// If it were an atom (OPT_ATOM): register_ref().
<implement mypred>
}
For functions in SWI-Prolog.h that don't have a C++
equivalent in SWI-cpp2.h, PlCheck_PL() is a
convenience function that checks the return code and throws a PlFail
exception on failure or PlException if there was an
exception. The PREDICATE() code catches PlFail
exceptions and converts them to the foreign_t return code
for failure. If the failure from the C function was due to an exception
(e.g., unification failed because of an out-of-memory condition), the
foreign function caller will detect that situation and convert the
failure to an exception.
The "getter" methods for PlTerm all throw an exception
if the term isn't of the expected Prolog type. Where possible, the
"getters" have the same name as the underlying type; but this isn't
possible for types such as int or float, so
for these the name is prepended with "as_".
"Getters" for integers have an additionnal problem, in that C++
doesn't define the sizes of int and long, nor
for
size_t. It seems to be impossible to make an overloaded
method that works for all the various combinations of integer types on
all compilers, so there are specific methods for int64_t,
uint64_t, size_t.
In some cases,it is possible to overload methods; for example, this
allows the following code without knowing the exact definition of
size_t:
PREDICATE(p, 1)
{ size_t sz;
A1.integer(&sz);
...
}
It is strongly recommended that you enable conversion checking.
For example, with GNU C++, these options (possibly with -Werror:
-Wconversion -Warith-conversion -Wsign-conversion
-Wfloat-conversion.
There is an additional problem with characters - C promotes them to int
but C++ doesn't. In general, this shouldn't cause any problems, but care
must be used with the various getters for integers.
The C++ API remains a work in progress.
SWI-Prolog string handling has evolved over time. The functions that
create atoms or strings using char* or wchar_t*
are "old school"; similarly with functions that get the string as
char* or wchar_t*. The PL_get_unify_put_[nw]chars()
family is more friendly when it comes to different input, output,
encoding and exception handling.
Roughly, the modern API is PL_get_nchars(), PL_unify_chars() and PL_put_chars() on terms. There is only half of the API for atoms as PL_new_atom_mbchars() and PL-atom_mbchars(), which take an encoding, length and char*.
However, there is no native "string" type in C++; the char*
strings can be automatically cast to string. If a C++ interface provides
only std::string arguments or return values, that can
introduce some inefficiency; therefore, many of the functions and
constructors allow either a char* or std::string
as a value (also wchar_t* or std::wstring.
For return values, char* is dangerous because it can
point to local or stack memory. For this reason, wherever possible, the
C++ API returns a std::string, which contains a copy of the
the string. This can be slightly less efficient that returning a
char*, but it avoids some subtle and pervasive bugs that
even address sanitizers can't detect.12If
we wish to minimize the overhead of passing strings, this can be done by
passing in a pointer to a string rather than returning a string value;
but this is more cumbersome and modern compilers can often optimize the
code to avoid copying the return value.
Many of the classes have a as_string() method - this might be changed
in future to to_string(), to be consistent with
std::to_string(). However, the method names such as
as_int32_t() were chosen istntead of to_int32_t() because they imply
that the representation is already an int32_t, and not that
the value is converted to a int32_t. That is, if the value
is a float, int32_t will fail with an error rather than
(for example) truncating the floating point value to fit into a 32-bit
integer.
Many of the "opaque object handles", such as atom_t,
term_t, and functor_t are integers.13Typically uintptr_t
values, which the C standard defines as “an unsigned integer type
with the property that any valid pointer to void can be converted to
this type, then converted back to pointer to void, and the result will
compare equal to the original pointer.'' As such, there is
no compile-time detection of passing the wrong handle to a function.
This leads to a problem with classes such as PlTerm -
C++ overloading cannot be used to distinguish, for example, creating a
term from an atom versus creating a term from an integer. There are
number of possible solutions, including:
struct instead of an
integer.It is impractical to change the C code, both because of the amount of edits that would be required and also because of the possibility that the changes would inhibit some optimizations.
There isn't much difference between subclasses versus tags; but as a matter of design, it's better to specify things as constants than as (theoretically) variables, so the decision was to use subclasses.
The utility program swipl-ld (Win32: swipl-ld.exe) works with both C and C++ programs. See Linking embedded applications using swipl-ld for more details.
Your C++ compiler should support at least C++-17.
To avoid incompatibilities amongst the various C++ compilers' ABIs,
the object file from compiling SWI-cpp2.cpp is not included
in the shared object libswipl; instead, it must be compiled
along with any foreign predicate files. You can do this in three ways:
SWI-cpp2.cpp separately.#include SWI-cpp2.cpp to one of the foreign
predicate files.#include SWI-cpp2.h%, add
#define _SWI_CPP2_CPP_inline inline
#include <SWI-cpp2.cpp>
This will cause the compiler to attempt to inline all the functions and methods, even those that are rarely used, resulting in some code bloat.
Before going into a detailed description of the C++ classes we present a few examples illustrating the‘feel' of the interface.
This simple example shows the basic definition of the predicate hello/1 and how a Prolog argument is converted to C-data:
PREDICATE(hello, 1)
{ cout << "Hello " << A1.as_string() << endl;
return true;
}
The arguments to PREDICATE() are the name and arity of the
predicate. The macros A<n> provide access to the
predicate arguments by position and are of the type PlTerm.
The C or C++ string for a PlTerm can be extracted using as_string(),
or as_wstring() methods;14The
C-string values can be extracted from std::string by using c_str(),
but you must be careful to not return a pointer to a local/stack value.
and similar access methods provide an easy type-conversion for most
Prolog data-types, using the output of write/1
otherwise:
?- hello(world). Hello world Yes ?- hello(X) Hello _G170 X = _G170
This example shows arithmetic using the C++ interface, including unification, type-checking, and conversion. The predicate add/3 adds the two first arguments and unifies the last with the result.
PREDICATE(add, 3)
{ return A3.unify_integer(A1.as_long() + A2.as_long());
}
You can use your own variable names instead of A1,
A2, etc.:
PREDICATE(add, 3) // add(+X, +Y, +Result)
{ PlTerm x(A1);
PlTerm y(A2);
PlTerm result(A3);
return result.unify_integer(x.as_long() + y.as_long());
}
The as_long() method for a PlTerm performs a PL_get_long_ex()
and throws a C++ exception if the Prolog argument is not a Prolog
integer or float that can be converted without loss to a
long. The unify_integer() method of PlTerm
is defined to perform unification and returns true or false
depending on the result.
?- add(1, 2, X). X = 3. ?- add(a, 2, X). [ERROR: Type error: `integer' expected, found `a'] Exception: ( 7) add(a, 2, _G197) ?
This example is a bit harder. The predicate average/3 is defined to take the template average(+Var, :Goal, -Average) , where Goal binds Var and will unify Average with average of the (integer) results.
PlQuery takes the name of a predicate and the
goal-argument vector as arguments. From this information it deduces the
arity and locates the predicate. The method next_solution()
yields
true if there was a solution and false
otherwise. If the goal yields a Prolog exception, it is mapped into a
C++ exception. A return to Prolog does an implicit "cut" (PL_cut_query());
this can also be done explicitly by the PlQuery::cut() method.
PREDICATE(average, 3) /* average(+Templ, :Goal, -Average) */
{ long sum = 0;
long n = 0;
PlQuery q("call", PlTermv(A2));
while( q.next_solution() )
{ sum += A1.as_long();
n++;
}
return A3.unify_float(double(sum) / double(n));
}
?- [user]. |: p(1). |: p(10). |: p(20). |: % user://1 compiled 0.00 sec, 3 clauses true. ?- average(X, p(X), Average). Average = 10.333333333333334.
The original version of the C++ interface heavily used implicit constructors and conversion operators. This allowed, for example:
PREDICATE(hello, 1)
{ cout << "Hello " << A1.as_string() << endl;
return true;
}
PREDICATE(add, 3)
{ return A3 = (long)A1 + (long)A2;
}
Version 2 is a bit more verbose:
PREDICATE(hello, 1)
{ cout << "Hello " << A1.as_string() << endl;
return true;
}
PREDICATE(add, 3)
{ return A3.unify_int(A1.as_long() + A2.as_long());
}
There are a few reasons for this:
(char *)A1 becomes the more verbose
static_cast<std::string>(A1), which is longer than
A1.as_string(). Also, the string casts don't allow for
specifying encoding.PlTerm t; Pl_put_atom_chars(t, "someName");
whereas this is now required:
PlTerm t; Pl_put_atom_chars(t.as_term_t(), "someName");
However, this is mostly avoided by methods and constructors that wrap the foreign language functions:
PlTerm_atom t("someName");
or
auto t = PlTerm_atom("someName");
bool and they can be wrapped inside a PlCheckFail()
to raise an exception on unification failure.Over time, it is expected that some of these restrictions will be eased, to allow a more compact coding style that was the intent of the original API. However, too much use of overloaded methods/constructors, implicit conversions and constructors can result in code that's difficult to understand, so a balance needs to be struck between compactness of code and understandability.
For backwards compatibility, some of the version 1 interface is still available (except for the implicit constructors and operators), but marked as "deprecated"; code that depends on the parts that have been removed can be easily changed to use the new interface.
The version API often used char* for both setting and
setting string values. This is not a problem for setting (although
encodings can be an issue), but can introduce subtle bugs in the
lifetimes of pointers if the buffer stack isn't used properly. The
buffer stack is abstracted into PlStringBuffers, but it
would be preferable to avoid its use altogether. C++, unlike C, has a
standard string that allows easily keeping a copy rather than dealing
with a pointer that might become invalid. (Also, C++ strings can contain
null characters.)
C++ has default conversion operators from char* to
std::string, so some of the API support only
std::string, even though this can cause a small
inefficiency. If this proves to be a problem, additional overloaded
functions and methods can be provided in future (note that some
compilers have optimizations that reduce the overheads of using
std::string); but for performance-critical code, the C
functions can still be used.
There still remains the problems of Unicode and encodings.
std::wstring is one way of dealing with this. And for
interfaces that use std::string, an encoding can be
specified.15As of 2023-04, this
had only been partially implemented. Some of the details
for this - such as the default encoding - may change slightly in the
future.
SWI-cpp2.h is not complete; it needs‘fileSWI-cpp2.cpp
to implement some functions. The easiest way of taking care of this is
to add
#include <SWI-cpp2.cpp> in your "main" file;
alternatively, you can create another source file that contains the
"include" statement.
The easiest way of porting from SWI-cpp.h to SWI-cpp2.h
is to change the #include "SWI-cpp.h" to #include
"SWI-cpp2.h" and look at the warning and error messages. Where
possible, version 2 keeps old interfaces with a "deprecated" flag if
there is a better way of doing things with version 2.
For convenience when calling PL_*() functions, the Plx_*() wrapper
functions add error checking. Also, most of the PL_*() functions that
work with term_t, atom_t, etc. have
corresponding methods in PlTerm, PlAtom, etc.
Here is a list of typical changes:
term_t, PlTerm_integer(i),
PlTerm_float(v), or PlTerm_pointer(p).
char* or wchar_t and
replace them by
std::string or std::wstring if appropriate.
For example, cout << "Hello " <<
A1.as_string().c_str()() << endl can be replaced by cout
<< "Hello " << A1.as_string() << endl. In
general, std::string is safer than char*
because the latter can potentially point to freed memory.
false from a predicate for
failure, you can do throw PlFail(). This mechanism
is also used by
PlCheckFail(rc). Note that throwing an exception is significantly
slower than returning false, so performance-critical code
should avoid PlCheckFail(rc).
SWI-Prolog and throw a PlFail
exception to short-circuit execution and return failure (false)
to Prolog (or throw a PlException if there was a Prolog
error.
PlAtom::handle has been replaced by PlAtom::C_.
PlTerm::ref has been replaced by PlAtom::C_.
PlFunctor::functor has been replaced by PlAtom::C_.
=unify_XXX‘methods (PlTerm::unify_term(t2),
PlTerm::unify_atom(a),
etc.).
static_cast<char*>(t) is replaced by t.as_string().c_str();
static_cast<int32_t>(t) is replaced by t.as_int32_t().
int or
long because of problems porting between Unix and Windows
platforms; instead, use int32_t, int64_t,
uint32_t, uint64_t, etc.
The PlFail class is used for short-circuiting a function
when failure or an exception occurs and any errors will be handled in
the code generated by the PREDICATE() macro. See also
section 2.19.2).
For example, this code:
PREDICATE(unify_zero, 1)
{ if ( !PL_unify_integer(A1.C_, 0) )
return false;
return true;
}
can instead be written this way:
void
PREDICATE(unify_zero, 1)
{ if ( !PL_unify_integer(A1.C_, 0) )
throw PlFail();
return true;
}
or:
PREDICATE(unify_zero, 1)
{ PlCheck_PL(PL_unify_integer(t.C_, 0));
return true;
}
or:
PREDICATE(unify_zero, 1)
{ PlCheckFail(A1.unify_integer(0));
return true;
}
or:
PREDICATE(unify_zero, 1)
{ return A1.unify_integer(0);
}
Using throw PlFail() in performance-critical code can
cause a signficant slowdown. A simple benchmark showed a 15x to 20x
slowdown using throw PlFail() compared to return
false (comparing the first code sample above with the second and
third samples; the speed difference seems to have been because in the
second sample, the compiler did a better job of inlining). However, for
most code, this difference will be barely noticeable.
There was no significant performance difference between the C++ version and this C version:
static foreign_t
unify_zero(term_t a1)
{ return PL_unify_integer(a1, 0);
}
If one of the C "PL_" functions in SWI-Prolog.h returns
failure, this can be either a Prolog-style failure (e.g. from
PL_unify() or PL_next_solution()) or an error. If the
failure is due to an error, it's usually best to immediately return to
Prolog - and this can be done with the PlCheckEx() function,
which turns a Prolog error into a C++ PlException. PlCheck()
calls PlCheckEx() and additionally throws PlFail() if the failure is for
Prolog failure.
The code for PlCheck() is just
void PlCheck(int rc)
{ if ( !PlCheckEx(rc) ) throw PlFail(); }
PlCheckEx() calls PL_exception() to see if there is a
Prolog exception; if so, the Prolog exception is converted to a
PlException object, which is then thrown. For more details
on the C++ exceptions, see section 2.17.
As we have seen from the examples, the PlTerm class
plays a central role in conversion and operating on Prolog data. This
section provides complete documentation of this class.
The constructors are defined as subclasses of PlTerm,
with a name that reflects the Prolog type of what is being created
(e.g., PlTerm_atom creates an atom; PlTerm_string
creates a Prolog string). All of the constructors are "explicit" because
implicit creation of PlTerm objects can lead to subtle and
difficult to debug errors.
PlTerm. Note that, being
a lightweight class, this is a no-op at the machine-level!void *. Also note that in general blobs
are a better way of doing this (see the section on blobs in the
Foreign Language Interface part of the SWI-Prolog manual).
PREDICATE(make_my_object, 1)
{ auto myobj = new MyClass();
return A1.unify_pointer(myobj);
}
PREDICATE(my_object_contents, 2)
{ auto myobj = static_cast<MyClass*>(A1.pointer());
return A2.unify_string(myobj->contents);
}
PREDICATE(free_my_object, 1)
{ auto myobj = static_cast<MyClass*>(A1.pointer());
delete myobj;
return true;
}
The SWI-Prolog.h header provides various functions for
accessing, setting, and unifying terms, atoms and other types.
Typically, these functions return a 0 (false)
or
1 (true) value for whether they succeeded or
not. For failure, there might also be an exception created - this can be
tested by calling PL_excpetion(0).
There are three major groups of methods:
The "put" operations are typically done on an uninstantiated term (see the PlTerm_var() constructor). These are expected to succeed, and typically raise an exception failure (e.g., resource exception) - for details, see the corresponding PL_put_*() functions in Constructing Terms.
For the "get" and "unify" operations, there are three possible failures:
false return code
Each of these is communicated to Prolog by returning false
from the top level; exceptions also set a "global" exception term (using PL_raise_exception()).
The C++ programmer usually doesn't have to worry about this; instead
they can throw PlFail() for failure or throw
PlException() (or one of PlException’s
subclasses) and the C++ API will take care of everything.
These are deprecated and replaced by the various as_*()
methods.
PlTerm can be converted to the following types:
long if the PlTerm is a Prolog
integer or float that can be converted without loss to a long. throws a
type_error exception otherwise.long, but might represent fewer bits.PlTerm represents a
Prolog integer or float.CVT_ALL|CVT_WRITE|BUF_RING, which implies Prolog atoms and
strings are converted to the represented text. All other data is handed
to write/1. If
the text is static in Prolog, a direct pointer to the string is
returned. Otherwise the text is saved in a ring of 16 buffers and must
be copied to avoid overwriting.In addition, the Prolog type (`PL_VARIABLE`,‘PL_ATOM`, ...‘PL_DICT`) can be determined using the type() method. There are also boolean methods that check the type:
See also section 2.13.
A family of unification methods are defined for the various Prolog
types and C++ types. Wherever string is shown, you can use:
char*whar_t*std::stringstd::wstring
Here is an example:
PREDICATE(hostname, 1)
{ char buf[256];
if ( gethostname(buf, sizeof buf) == 0 )
return A1.unify_atom(buf);
return false;
}
An alternative way of writing this would use the PlCheckFail() to raise an exception if the unification fails.
PREDICATE(hostname2, 1)
{ char buf[256];
PlCheckFail(gethostname(buf, sizeof buf) == 0);
PlCheckFail(A1.unify_atom(buf));
return true;
}
Of course, in a real program, the failure of
gethostname(buf)sizeof buf should create an error term than
contains information from errno.
PlTerm to a long and perform standard
C-comparison between the two long integers. If PlTerm
cannot be converted a type_error is raised.true if the PlTerm is an atom or string
representing the same text as the argument, false if the
conversion was successful, but the strings are not equal and an
type_error exception if the conversion failed.Below are some typical examples. See section 2.11.2 for direct manipulation of atoms in their internal representation.
A1 < 0 | Test A1 to hold a Prolog integer or float that can be transformed lossless to an integer less than zero. |
A1 < PlTerm(0) | A1
is before the term‘0' in the‘standard order of terms'. This
means that if A1 represents an atom, this test yields true. |
A1 == PlCompound("a(1)") | Test A1
to represent the term
a(1). |
A1 == "now" | Test A1 to be an atom or string holding the text “now''. |
Compound terms can be viewed as an array of terms with a name and
arity (length). This view is expressed by overloading the []
A type_error is raised if the argument is not compound
and a
domain_error if the index is out of range.
In addition, the following functions are defined:
PlTerm is a compound term and arg is
between 1 and the arity of the term, return a new PlTerm
representing the arg-th argument of the term. If PlTerm is
not compound, a
type_error is raised. Id arg is out of range, a
domain_error is raised. Please note the counting from 1
which is consistent to Prolog's arg/3
predicate, but inconsistent to C's normal view on an array. See also
class PlCompound. The following example tests x
to represent a term with first-argument an atom or string equal to gnat.
...,
if ( x[1] == "gnat" )
...
const char * holding the name of the functor of
the compound term. Raises a type_error if the argument is
not compound.type_error
if the argument is not compound.
t.is_null() is the same as t.C_ == PlTerm::nullt.not_null() is the same as t.C_ != PlTerm::nullt.reset() is the same as t.C_ = PlTerm::nullt.reset(x) is the same as t.C_ = xPL_VARIABLE, PL_FLOAT, PL_INTEGER,
PL_ATOM, PL_STRING or PL_TERM
To avoid very confusing combinations of constructors and therefore
possible undesirable effects a number of subclasses of PlTerm
have been defined that provide constructors for creating special Prolog
terms. These subclasses are defined below.
A SWI-Prolog string represents a byte-string on the global stack. Its
lifetime is the same as for compound terms and other data living on the
global stack. Strings are not only a compound representation of text
that is garbage-collected, but as they can contain 0-bytes, they can be
used to contain arbitrary C-data structures. However, it is generally
preferred to use blobs for storing arbitrary C-data structures (see also PlTerm_pointer(void
*ptr)).
Character lists are compliant to Prolog's atom_chars/2 predicate.
syntax_error exception is raised. Otherwise a new
term-reference holding the parsed text is created.PlTermv for details. The example below
creates the Prolog term hello(world).
PlCompound("hello", PlTermv("world"))
The class PlTail is both for analysing and constructing
lists. It is called PlTail as enumeration-steps make the
term-reference follow the‘tail' of the list.
PlTail is created by making a new term-reference pointing
to the same object. As PlTail is used to enumerate or build
a Prolog list, the initial list term-reference keeps pointing
to the head of the list.PlTail
reference point to the new variable tail. If A is a variable,
and this function is called on it using the argument "gnat",
a list of the form [gnat|B] is created and the PlTail
object now points to the new variable B.
This function returns true if the unification succeeded
and
false otherwise. No exceptions are generated.
The example below translates the main() argument vector to Prolog and calls the prolog predicate entry/1 with it.
int
main(int argc, char **argv)
{ PlEngine e(argv[0]);
PlTermv av(1);
PlTail l(av[0]);
for(int i=0; i<argc; i++)
PlCheckFail(l.append(argv[i]));
PlCheckFail(l.close());
PlQuery q("entry", av);
return q.next_solution() ? 0 : 1;
}
[]PlTail
and advance
PlTail. Returns true on success and false
if
PlTail represents the empty list. If PlTail is
neither a list nor the empty list, a type_error is thrown.
The example below prints the elements of a list.
PREDICATE(write_list, 1)
{ PlTail tail(A1);
PlTerm e;
while(tail.next(e))
cout << e.as_string() << endl;
return true;
}
The class PlTermv represents an array of
term-references. This type is used to pass the arguments to a foreignly
defined predicate, construct compound terms (see PlTerm::PlTerm(const
char *name, PlTermv arguments)) and to create queries (see PlQuery).
The only useful member function is the overloading of []domain_error exception.
The constructors for this class are below.
load_file(const char *file)
{ return PlCall("compile", PlTermv(file));
}
If the vector has to contain more than 5 elements, the following construction should be used:
{ PlTermv av(10);
av[0] = "hello";
...
}
Both for quick comparison as for quick building of lists of atoms, it is desirable to provide access to Prolog's atom-table, mapping handles to unique string-constants. If the handles of two atoms are different it is guaranteed they represent different text strings.
Suppose we want to test whether a term represents a certain atom, this interface presents a large number of alternatives:
Example:
PREDICATE(test, 1)
{ if ( A1 == "read" )
...;
}
This writes easily and is the preferred method is performance is not critical and only a few comparisons have to be made. It validates A1 to be a term-reference representing text (atom, string, integer or float) extracts the represented text and uses strcmp() to match the strings.
Example:
static PlAtom ATOM_read("read");
PREDICATE(test, 1)
{ if ( A1 == ATOM_read )
...;
}
This case raises a type_error if A1 is not an
atom. Otherwise it extacts the atom-handle and compares it to the
atom-handle of the global PlAtom object. This approach is
faster and provides more strict type-checking.
Example:
static PlAtom ATOM_read("read");
PREDICATE(test, 1)
{ PlAtom a1(A1);
if ( a1 == ATOM_read )
...;
}
This approach is basically the same as section 2.11.2, but in nested if-then-else the extraction of the atom from the term is done only once.
Example:
PREDICATE(test, 1)
{ PlAtom a1(A1);
if ( a1 == "read" )
...;
}
This approach extracts the atom once and for each test extracts the represented string from the atom and compares it. It avoids the need for global atom constructors.
atom_t). Used
internally and for integration with the C-interface.type_error is thrown.true if the atom represents text, false
otherwise. Performs a strcmp() or similar for this.true or
false. Because atoms are unique, there is no need to use
strcmp() for this.==true.char* from a function, you should not
do return t.as_string().c_str() because that will return a
pointer into the stack (Gnu C++ or Clang options -Wreturn-stack-address
or -Wreturn-local-addr) can sometimes catch this,
as can the runtime address sanitizer when run with detect_stack_use_after_return=1.
This does not quote or escape any characters that would need to be
escaped if the atom were to be input to the Prolog parser. The possible
values for enc are:
EncLatin1 - throws an exception if cannot be
represented in ASCII.EncUTF8EncLocale - uses the locale to determine the
representation.
The recorded database is has two wrappers, for supporting the internal records and external records.
Currently, the interface to internal records requires that
the programmer explicitly call the dupicate() and erase() methods - in
future, it is intended that this will be done automatically by a new
PlRecord class, so that the internal records behave like
"smart pointers"; in the meantime, the PlRecord provides a
trivial wrapper around the various recorded database functions.
The class PlRecord supports the following methods:
PlRecord object.
The class PlRecord provides direct access to the
reference counting aspects of the recorded term (through the duplicate()
and erase() methods), but does not connect these with C++'s
copy constructor, assignment operator, or destructor. If the recorded
term is encapsulated within an object, then the containing object can
use the duplicate() and erase() methods in its copy and move
constructors and assignment operators (and the erase() method in the
destructor).17The copy constructor
and assignment use the duplicate() method; the move constructor and
assignment use the duplicate() method to assign to the destination and
the erase() method on the source; and the destructor uses erase().
Alternatively, the std::shared_ptr or std::unique_ptr
can be used with the supplied PlrecordDeleter, which calls
the erase() method when the shared_ptr reference count goes
to zero or when the unique_ptr goes out of scope.
For example:
std::shared_ptr<PlRecord> r(new PlRecord(t.record()), PlRecordDeleter()); assert(t.unify_term(r->term()));
The class PlRecordExternalCopy keeps the external
record as an uninterpreted string. It supports the following
methods.
As documented with PL_unify(), if a unification call fails and
control isn't made immediately to Prolog, any changes made by
unification must be undone. The functions PL_open_foreign_frame(), PL_rewind_foreign_frame(),
and
PL_close_foreign_frame() are encapsulated in the class PlFrame,
whose destructor calls PL_close_foreign_frame(). Using this, the
example code with PL_unify() can be written:
{ PlFrame frame;
...
if ( !t1.unify_term(t2) )
frame.rewind();
...
}
Note that PlTerm::unify_term()
checks for an exception and throws an exception to Prolog; if you with
to handle exceptions, you must call PL_unify_term(t1.C_,t2.C_).
This class encapsulates PL_register_foreign(). It is defined as a class rather then a function to exploit the C++ global constructor feature. This class provides a constructor to deal with the PREDICATE() way of defining foreign predicates as well as constructors to deal with more conventional foreign predicate definitions.
PL_FA_VARARGS calling convention, where the argument
list of the predicate is passed using an array of term_t
objects as returned by PL_new_term_refs(). This interface poses
no limits on the arity of the predicate and is faster, especially for a
large number of arguments.
static foreign_t
pl_hello(PlTerm a1)
{ ...
}
PlRegister x_hello_1(NULL, "hello", 1, pl_hello);
This construct is currently supported upto 3 arguments.
This class encapsulates the call-backs onto Prolog.
user.true if
successful and false if there are no (more) solutions.
Prolog exceptions are mapped to C++ exceptions.PlQuery’s destructor.
Below is an example listing the currently defined Prolog modules to the terminal.
PREDICATE(list_modules, 0)
{ PlTermv av(1);
PlQuery q("current_module", av);
while( q.next_solution() )
cout << av[0].as_string() << endl;
return true;
}
In addition to the above, the following functions have been defined.
PlQuery from the arguments generates the first next_solution()
and destroys the query. Returns the result of next_solution() or
an exception.
The class PlFrame provides an interface to discard
unused term-references as well as rewinding unifications (data-backtracking).
Reclaiming unused term-references is automatically performed after a
call to a C++-defined predicate has finished and returns control to
Prolog. In this scenario PlFrame is rarely of any use. This
class comes into play if the toplevel program is defined in C++ and
calls Prolog multiple times. Setting up arguments to a query requires
term-references and using PlFrame is the only way to
reclaim them.
A typical use for PlFrame is
the definition of C++ functions that call Prolog and may be called
repeatedly from C++. Consider the definition of assertWord(), adding a
fact to word/1:
void
assertWord(const char *word)
{ PlFrame fr;
PlTermv av(1);
av[0] = PlCompound("word", PlTermv(word));
PlQuery q("assert", av);
PlCheckFail(q.next_solution());
}
This example shows the most sensible use of PlFrame if
it is used in the context of a foreign predicate. The predicate's
thruth-value is the same as for the Prolog unification (=/2), but has no
side effects. In Prolog one would use double negation to achieve this.
PREDICATE(can_unify, 2)
{ PlFrame fr;
int rval = (A1=A2);
fr.rewind();
return rval;
}
PlRewindOnFail(f) is a convenience function that does a frame
rewind if unification fails. Here is an example, where name_to_term
contains a map from names to terms (which are made global by using the
PL_record() function):
static const std::map<const std::string, record_t> name_to_term =
{ {"a", PlTerm(...).record()}, ...};
bool lookup_term(const std::string name, PlTerm result)
{ const auto it = name_to_term.find(name);
if ( it == name_to_term.cend() )
return false;
PlTerm t = PlTerm_recorded(it->second);
return PlRewindOnFail([result,t]() -> bool { return result.unify_term(t); });
}
The PREDICATE macro is there to make your code look nice, taking care of the interface to the C-defined SWI-Prolog kernel as well as mapping exceptions. Using the macro
PREDICATE(hello, 1)
is the same as writing:18There
are a few more details, such as catching std::bad_alloc.:
static foreign_t pl_hello__1(PlTermv PL_av);
static foreign_t
_pl_hello__1(term_t t0, int arity, control_t ctx)
{ (void)arity; (void)ctx;
try
{ return pl_hello__1(PlTermv(1, t0));
} catch( PlFail& )
{ return false;
} catch ( PlException& ex )
{ return ex.plThrow();
}
}
static PlRegister _x_hello__1("hello", 1, _pl_hello__1);
static foreign_t
pl_hello__1(PlTermv PL_av)
The first function converts the parameters passed from the Prolog
kernel to a PlTermv instance and maps exceptions raised in
the body to simple failure or Prolog exceptions. The PlRegister
global constructor registers the predicate. Finally, the function header
for the implementation is created.
The PREDICATE() macros have a number of variations that deal with special cases.
PL_av is not used.
NAMED_PREDICATE("#", hash, 2)
{ A2 = (wchar_t*)A1;
}
Non-deterministic predicates are defined using PREDICATE_NONDET(plname, cname, arity) or NAMED_PREDICATE_NONDET(plname, cname, arity).
A non-deterministic predicate returns a "context", which is passed to
a a subsequent retry. Typically, this context is allocated on the first
call to the predicate and freed when the predicate either fails or does
its last successful return. To simplify this, a template helper class
PlForeignContextPtr<ContextType> provides a
"smart pointer" that frees the context on normal return or an exception;
if PlForeignContextPtr<ContextType>::keep() is called, the
pointer isn't freed on return or exception.
The skeleton for a typical non-deterministic predicate is:
struct PredContext { ... }; // The "context" for retries
PREDICATE_NONDET(pred, <arity>)
{ PlForeignContextPtr<PredContext> ctxt(handle);
switch( PL_foreign_control(handle) )
{ case PL_FIRST_CALL:
ctxt.set(new PredContext(...));
...
break;
case PL_REDO:
break;
case PL_PRUNED:
return true;
}
if ( ... )
return false; // Failure (and no more solutions)
// or throw PlFail();
if ( ... )
return true; // Success (and no more solutions)
...
ctxt.keep();
PL_retry_address(ctxt.get()); // Succeed with a choice point
}
With no special precautions, the predicates are defined into the
module from which load_foreign_library/1
was called, or in the module
user if there is no Prolog context from which to deduce the
module such as while linking the extension statically with the Prolog
kernel.
Alternatively, before loading the SWI-Prolog include file, the macro PROLOG_MODULE may be defined to a string containing the name of the destination module. A module name may only contain alpha-numerical characters (letters, digits, _). See the example below:
#define PROLOG_MODULE "math"
#include <SWI-Prolog.h>
#include <math.h>
PREDICATE(pi, 1)
{ A1 = M_PI;
}
?- math:pi(X). X = 3.14159
Prolog exceptions are mapped to C++ exceptions using the subclass
PlException of PlTerm to represent the Prolog
exception term. All type-conversion functions of the interface raise
Prolog-compliant exceptions, providing decent error-handling support at
no extra work for the programmer.
For some commonly used exceptions, subclasses of PlException
have been created to exploit both their constructors for easy creation
of these exceptions as well as selective trapping in C++. Currently,
these are PlTypeEror and PlDomainError,
PlTermvDomainError, PlInstantiationError,
PlExistenceError, PermissionError, PlResourceError,
and PlException_qid.
To throw an exception, create an instance of PlException
and use throw. This is intercepted by the PREDICATE macro
and turned into a Prolog exception. See section
2.19.2.
char *data = "users";
throw PlException(PlCompound("no_database", PlTerm(data)));
This subclass of PlTerm is used to represent exceptions.
Currently defined methods are:
...;
try
{ PlCall("consult(load)");
} catch ( PlException& ex )
{ cerr << ex.as_string() << endl;
}
A type error expresses that a term does not satisfy the expected basic Prolog type.
A domain error expresses that a term satisfies the basic
Prolog type expected, but is unacceptable to the restricted domain
expected by some operation. For example, the standard Prolog open/3
call expect an io_mode (read, write, append, ...). If an
integer is provided, this is a type error, if an atom other
than one of the defined io-modes is provided it is a domain error.
Most of the above assumes Prolog is‘in charge' of the
application and C++ is used to add functionality to Prolog, either for
accessing external resources or for performance reasons. In some
applications, there is a main-program and we want to use Prolog
as a
logic server. For these applications, the class
PlEngine has been defined.
Only a single instance of this class can exist in a process. When used in a multi-threading application, only one thread at a time may have a running query on this engine. Applications should ensure this using proper locking techniques.19For Unix, there is a multi-threaded version of SWI-Prolog. In this version each thread can create and destroy a thread-engine. There is currently no C++ interface defined to access this functionality, though ---of course--- you can use the C-functions.
argv[0]
from its main function, which is needed in the Unix version to find the
running executable. See PL_initialise() for details.argv[0].Section 1.4.11 has a simple example using this class.
Not all functionality of the C-interface is provided, but as
PlTerm and term_t are essentially the same
thing with type-conversion between the two (using the C_
field), this interface can be freely mixed with the functions defined
for plain C. For checking return codes from C functions, it is
recommended to use PlCheckFail() or PlCheck_PL().
Using this interface rather than the plain C-interface requires a
little more resources. More term-references are wasted (but reclaimed on
return to Prolog or using PlFrame). Use of some
intermediate types (functor_t etc.) is not supported in the
current interface, causing more hash-table lookups. This could be fixed,
at the price of slighly complicating the interface.
Global terms and atoms need to be handled slightly differently in C++ than in C - see section 2.19.3
Exceptions are normal Prolog terms that are handled specially by the
PREDICATE macro when they are used by a C++ throw, and
converted into Prolog exceptions. The exception term may not be unbound;
that is, throw(_) must raise an error. The C++ code and underlying C
code do not explicitly check for the term being a variable, and
behaviour of raising an exception that is an unbound term is undefined,
including the possibility of causing a crash or corrupting data.
The Prolog exception term error(Formal, _) is special. If the 2nd
argument of error/2
is undefined, and the term is thrown, the system finds the catcher (if
any), and calls the hooks in library(prolog_stack) to add the context
and stack trace information when appropriate. That is, throw
PlDomainError(Domain,Culprit) ends up doing the same thing as
calling
PL_domain_error(Domain,Culprit) which internally
calls
PL_raise_exception() and returns control back to Prolog.
The VM handling of calling to C finds the FALSE return
code, checks for the pending exception and propagates the exception into
the Prolog environment. As the term references (term_t)
used to create the exception are lost while returning from the foreign
function we need some way to protect them. That is done using a global term_t
handle that is allocated at the epoch of Prolog.
PL_raise_exception() sets this to the term using PL_put_term().
PL_exception(0) returns the global exception term_t
if it is bound and 0 otherwise.
Special care needs to be taken with data backtracking using
PL_discard_foreign_frame() or PL_close_query() because
that will invalidate the exception term. So, between raising the
exception and returning control back to Prolog we must make sure not to
do anything that invalidates the exception term. If you suspect
something like that to happen, use the debugger with a breakpoint on
__do_undo__LD() defined in pl-wam.c.
In order to always preserve Prolog exceptions and return as quickly as possible to Prolog on an exception, some of the C++ classes can throw an exception in their destructor. This is theoretically a dangerous thing to do, and can lead to a crash or program termination if the destructor is envoked as part of handling another exception.
Sometimes it is convenient to put constant terms and atoms as global
variables in a file (with a static qualifier), so that they
are only created (and looked up) cone. This is fine for atoms and
functors, which can be created by something like this:
static PlAtom ATOM_foo("foo");
static PlFunctor FUNCTOR_ff_2("ff", 2);
C++ makes no guarantees about the order of creating global variables
across "translation units" (that is, individual C++ files), but the
Prolog runtime ensures that the necessary initialization has been done
to allow PlAtom and PlFunctor objects to be
created. However, to be safe, it is best to put such global variables
inside functions - C++ will initialize them on their firstuse.
Global Terms need a bit of care. For one thing, terms are ephemeral,
so it is wrong to have a PlTerm static variable - instead,
a
PlRecord must be used, which will provide a fresh copy of
the term using PlRecord::term(). There is no guarantee that the Prolog
runtime has initialized everything needed for creating entries in the
recorded database (see
Recorded
database). Therefore, global recorded terms must be wrapped inside a
function. C++ will call the constructor upon first use. For example:
static PlTerm
term_foo_bar()
{ static PlRecord r(PlCompound("foo", PlTermv(PlTerm_atom("bar"))).record());
return r.term();
}
The mechanisms outlined in this document can be used for static linking with the SWI-Prolog kernel using swipl-ld(1). In general the C++ linker should be used to deal with the C++ runtime libraries and global constructors.
The current interface can be entirely defined in the .h
file using inlined code. This approach has a few advantages: as no C++
code is in the Prolog kernel, different C++ compilers with different
name-mangling schemas can cooperate smoothly. However, inlining
everything can lead to code bloat, so the larger functions and methods
have been put into a .cpp file that can be either compiled
separately (by the same compiler as used by the foreign predicate) or
inlined as if it were part of the .h file.
Also, changes to the header file have no consequences to binary compatibility with the SWI-Prolog kernel. This makes it possible to have different versions of the header file with few compatibility consequences.
As of 2023-04, some details remain to be decided, mostly to do with
encodings. A few methods have a PlEncoding optional
parameter (e.g., PlTerm::as_string()), but this hasn't yet been
extended to all methods that take or return a string. Also, the details
of how the default encoding is set have not yet been decided.
As of 2023-04, the various error convenience classes do not fully
match what the equivalent C functions do. That is, throw
PlInstantiationError(A1) does not result in the same context and
traceback information that would happen from
Plx_instantiation_error(A1.C_); throw PlFail(). See
section 2.19.2.
The Plx_*() wrappers may require small adjustments in whether their
return values require [[nodiscard]] or whether their return
values should be treated as an error.
The implementation of PlException is likely to change
somewhat in the future. Currently, to ensure that the exception term has
a sufficient lifetime, it is serialized using PL_record_external().
In future, if this proves unnecessary, the term will be stored as-is.
The API will not change if this implementation detail changes.
In this document, we presented a high-level interface to Prolog exploiting automatic type-conversion and exception-handling defined in C++.
Programming using this interface is much more natural and requires only little extra resources in terms of time and memory.
Especially the smooth integration between C++ and Prolog exceptions reduce the coding effort for type checking and reporting in foreign predicates.