\chapter{A C++ interface to SWI-Prolog (Version 2)} \label{sec:cpp2} \section{Summary of changes between Versions 1 and 2} \label{sec:summary-cpp2-changes} Version 1 is in \file{SWI-cpp.h}; version 2 is in \file{SWI-cpp2.h}, \file{SWI-cpp2.cpp}, and \file{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 \file{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 \const{[]} operator for \ctype{PlTerm} and \ctype{PlTermv} doesn't cause unexpected implicit conversions. \footnote{If there is an implicit conversion operator from \ctype{PlTerm} to \ctype{term_t} and also to \ctype{char*}, then the \const{[]} operator is ambiguous if \exam{f} is overloaded to accept a \ctype{term_t} or \ctype{char*} in the code \exam{PlTerm t=...; f(t[0])} } Prolog exceptions are now converted to C++ exceptions (which contain the exception term rather being a subclass of \ctype{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 \ctype{PlFail} has been added, to allow "short circuit" return to Prolog on failure. A convenience class for creating blobs has been added, so that an existing structure can be converted to a blob with only a few lines of code. More specifically: \begin{itemize} \item \file{SWI-cpp2.cpp} has been added, containing the implementation of some functions that are too long to inline. The user must either \verb$#include $ or compile it separately and link it with the other foreign function code. \item The constructor PlTerm() is restricted to a few unambiguous cases - instead, you should use the appropriate subclass' constructors (PlTerm_var(), PlTerm_atom(), PlTerm_term_t(), PlTerm_integer(), PlTerm_int64(), PlTerm_uint64(), PlTerm_size_t(), PlTerm_float(), or PlTerm_pointer()). \item Wrapper functions have been provided for almost all the PL_*() functions in \file{SWI-Prolog.h}, and have the same names with the ``PL'' replaced by ``Plx''.\footnote{``Pl'' is used throughout the \file{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 \secref{cpp2-wrapper-functions}. Many of these wrapper functions are also methods in the \ctype{PlAtom} and \ctype{PlTerm} classes, with the arguments changed from \ctype{atom_t} and \ctype{term_t} to \ctype{PlAtom} and \ctype{PlTerm}. These wrappers are available if you include \file{SWI-cpp2.h} (they are in a separate \file{SWI-cpp2-plx.h} file for ease of maintenance). \item Instead of returning \const{false} from a foreign predicate to indicate failure, you can use \exam{throw PlFail()}. The convenience function PlCheckFail(rc) can be used to throw PlFail() if \const{false} is returned from a function in \file{SWI-Prolog.h}. If the wrapper functions or class methods are used, Prolog errors result in a C++ \ctype{PlException} exception.\footnote{If a ``Plx_'' wrapper is used to call a \file{SWI-Prolog.h} function, a Prolog error will have already resulted in throwing \ctype{PlException}}; PlCheckFail(rc) is used to additionally throw \ctype{PlFail}, similar to returning \const{false} from the top-level of a foreign predicate - Prolog will check for an error and call throw/1 if appropriate. \item The \ctype{PlException} class is a subclass of \ctype{std::exception} and encapsulates a Prolog error. Prolog errors are converted into \exam{throw PlException(...)}. If the user code does not catch the \ctype{PlException}, the PREDICATE() macro converts the error to a Prolog error upon return to the Prolog caller. \item The C++ constructors, functions, and methods use the wrapper functions to a C++ exception on error (and the C++ exception is converted to a Prolog exception when control returns to Prolog). \item The "cast" operators (e.g., \exam{(char*)t}, \exam{(int64_t)t}, \exam{static_cast(t)} have been deprecated, replaced by "getters" (e.g., \exam{t.as_string()}, \exam{t.as_int64_t()}). \item The overloaded assignment operator for unification is deprecated; replaced by unify_term(), unify_atom(), etc., and the helper PlCheckFail(). \item Many of the equality and inequality operators are deprecated; replaced by the as_string() method and the associated \ctype{std::string}, comparison operators. The as_string() method allows specifying the encoding to use whereas the \exam{==} and similar operators do not allow for this. \item Methods that return \ctype{char*} have been replaced by methods that return \ctype{std::string} to ensure that lifetime issues don't cause subtle bugs.\footnote{If you want to return a \ctype{char*} from a function, you should not do \exam{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 \ctype{std::string} and apply the \exam{c_str()} method to it. These lifetime errors can \emph{sometimes} be caught by specifying the Gnu C++ or Clang options \exam{-Wreturn-stack-address} or \exam{-Wreturn-local-addr} - as of 2023-04, Clang seems to do a better analysis.} \item Most constructors, methods, and functions that accept \ctype{char*} or \ctype{wchar_t*} arguments also accept \ctype{std::string} or \ctype{std::wstring} arguments. Where possible, encoding information can also be specified. \item Type-checking methods have been added: PlTerm::type(), PlTerm::is_variable(), PlTerm::is_atom(), etc. \item \ctype{PlString} has been renamed to \ctype{PlTerm_string} to make it clear that it's a term that contains a Prolog string. \item More \exam{PL_...(term_t, ...)} methods have been added to \ctype{PlTerm}, and \exam{PL_...(atom_t, ...)} methods have been added to \ctype{PlAtom}. Where appropriate, the arguments use \ctype{PlTerm}, \ctype{PlAtom}, etc. instead of \ctype{term_t}, \ctype{atom_t}, etc. \item Most functions/methods that return an \ctype{int} for true/false now return a C++ \ctype{bool}. \item The wrapped C types fields (\ctype{term_t}, \ctype{atom_t}, etc.) have been renamed from \exam{handle}, \exam{ref}, etc. to \exam{C_}.\footnote{This is done by subclassing from \ctype{Wrapped}, \ctype{Wrapped}, etc., which define the field \exam{C_}, standard constructors, the methods is_null(), not_null(), reset(), reset(v), plus the constant \const{null}.} \item A convenience function PlControl::context_unique_ptr() has been added, to simplify dynamic memory allocation in non-deterministic predicates. \item A convenience function PlRewindOnFail() has been added, to simplify non-deterministic code that does backtracking by checking unification results. \item \ctype{PlStringBuffers} provides a simpler interface for allocating strings on the stack than PL_STRINGS_MARK() and PL_STRINGS_RELEASE(). \item Wrapper classes for \ctype{record_t} have been added. The \ctype{PlRecordExternalCopy} class contains the opaque handle, as a convenience. \item Wrapper class for \ctype{control_t} has been added and the PREDICATE_NONDET() has been modified to use it. \end{itemize} More details are given in \secref{cpp2-rationale} and \secref{cpp2-porting-1-2}. \section{Sample code (version 2)} \label{sec:cpp2-sample-code} The file \href{https://github.com/SWI-Prolog/packages-cpp/blob/master/test_cpp.cpp}{test_cpp.cpp} contains examples of Prolog predicates written in C++. This file is used for testing (called from \href{https://github.com/SWI-Prolog/packages-cpp/blob/master/test_cpp.pl}{test_cpp.pl}). Notable examples: \begin{itemize} \item add_num(A1,A2,A3) - same as \exam{A3 is A1+A2}, converting the sum to an integer if possible. \item name_arity/3 - same as functor/3. \item average/3 - computes the average of all the solutions to \arg{Goal} \item can_unify/2 - tests whether the two arguments can unify with each other, without instantiating anything (similar to unifiable/3). \item eq1/1, eq2/2, eq3/2 - three different ways of implementing =/2. \item write_list/1 - outputs the elements of a list, each on a new line. \item cappend/3 - appends two lists (requires that the two lists are instantiated). \item square_roots/2 - same as \exam{bagof(Sqrt, X^(between(0,4,X), Sqrt is sqrt(X)), A2)}. \item range_cpp/3 - on backtracking, generates all integers starting at \arg{A1} and less than \arg{A2} (that is, one less than between/3). \item int_info/2 - on backtracking generates all the integral types with their minimum and maximum values. \end{itemize} The file \href{https://github.com/SWI-Prolog/packages-cpp/blob/master/test_cpp.cpp}{likes.cpp} contains a simple program that calls the Prolog predicate likes/2 and happy/1 (these predicates are defined in \href{https://github.com/SWI-Prolog/packages-cpp/blob/master/test_cpp.pl}{likes.pl}. The usage and how to compile the code are in comments in \file{likes.cpp} \section{Introduction (version 2)} \label{sec:cpp2-intro} 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 (\jargon{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 \href{https://www.swi-prolog.org/pldoc/man?section=foreigntypes}{Interface Data Types}. It would be tempting to use C++ implicit conversion operators and method overloading to automatically convert between C++ types such as \ctype{std::string} and \ctype{int64_t} and Prolog foreign language interface types such as \ctype{term_t} and \ctype{atom_t}. However, types such as \ctype{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. \subsection{Acknowledgements (version 2)} \label{sec:cpp2-acknowledgements} 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 \secref{summary-cpp2-changes}). \section{The life of a PREDICATE (version 2)} \label{sec:cpp2-life-of-a-predicate} A foreign predicate is defined using the PREDICATE() macro, plus 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 \exam{A1}, \exam{A2}, etc. for the arguments.\footnote{You can define your own names for the arguments, for example: \exam{auto dir=A1, db=A2, options=A3;}.} If a non-deterministic predicate is being defined, an additional parameter \exam{handle} is defined (of type \ctype{PlControl}). The foreign predicate returns a value: \begin{itemize} \item \const{true} - success \item \const{false} - failure or an error (see \secref{cpp2-exceptions} and \href{https://www.swi-prolog.org/pldoc/man?section=foreign-exceptions}{Prolog exceptions in foreign code}). \item "retry" - for non-deterministic predicates, gives a "context" for backtracking / redoing the call for the next solution. \end{itemize} 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 PlCheckFail() 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 essentially the same thing (for implementing the equivalent of =/2); however the thrid option (with PlWrap()) throws a C++ \ctype{PlExceptionFail} exception if there's an error; the second option (with PlCheckFail()) throws a \ctype{PlFail} exception for both failure and an error - the PREDICATE() wrapper handles all of these appropriately and reports the same result back to Prolog; but you might wish to distinguish the two situations in more complex code. \begin{code} PREDICATE(eq, 2) { return A1.unify_term(A2); } \end{code} \begin{code} PREDICATE(eq, 2) { PlCheckFail(A1.unify_term(A2)); return true; } \end{code} \begin{code} PREDICATE(eq, 2) { return PlWrap(PL_unify(A1.C_, A2.C_)); } \end{code} \section{Overview (version 2)} \label{sec:cpp2-overview} 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 \ctype{term_t}. In C++, \ctype{term_t} is embedded in the \jargon{lightweight} class \ctype{PlTerm}. Constructors and operator definitions provide flexible operations and integration with important C-types (\ctype{char *}, \ctype{wchar_t*}, \ctype{long} and \ctype{double}), plus the C++-types (\ctype{std::string}, \ctype{std::wstring}). \subsection{Design philosophy of the classes} \label{sec:cpp2-philosophy} See also \secref{cpp2-naming}. 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 \secref{cpp2-exceptions}.) The various classes (\ctype{PlAtom}, \ctype{PlTerm}, etc.) are thin wrappers around the C interface's types (\ctype{atom_t}, \ctype{term_t}, etc.). As such, they inherit the concept of "null" from these types (which is abstracted as \ctype{PlAtom::null}, \ctype{PlTerm::null}, etc., which typically is equivalent to \const{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, \begin{code} PlAtom foo("foo"); \end{code} will ensure that the object \exam{foo} is useable and will throw an exception if the atom can't be created. However, if you choose to create an \ctype{PlAtom} object from a \ctype{atom_t} value, no checking is done (similarly, no checking is done if you create a \ctype{PlTerm} object using the \ctype{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 \ctype{PlAtom} that is uninitialized, you must explicitly use \exam{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 \ctype{static} variables that get created at load time, so that a lookup for each use isn't needed (atoms are unique, so \exam{PlAtom("foo")} requires a lookup for an atom \exam{foo} and creates one if it isn't found). C code sometimes creates objects "lazily" on first use: \begin{code} void my_function(...) { static atom_t ATOM_foo = 0; ... if ( ! foo ) foo = PL_new_atom("foo"); ... } \end{code} For C++, this can be done in a simpler way, because C++ will call a local ``\ctype{static}'' constructor on first use. \begin{code} void my_function(...) { static PlAtom ATOM_foo("foo"); } \end{code} The class \ctype{PlTerm} (which wraps \ctype{term_t}) is the most used. Although a \ctype{PlTerm} object can be created from a \ctype{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 \secref{cpp2-plterm-constructurs}. Note that the default constructor is not public; to create a "variable" term, you should use the subclass constructor PlTerm_var(). \subsection{Summary of files} \label{sec:cpp2-files-summary} The following files are provided: \begin{itemize} \item \file{SWI-cpp2.h} Include this file to get the C++ API. It automatically includes \file{SWI-cpp2-plx.h} but does not include \file{SWI-cpp2.cpp}. \item \file{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 \file{SWI-cpp2.h} with this macro definition: \begin{code} #define _SWI_CPP2_CPP_inline inline \end{code} \item \file{SWI-cpp2-plx.h} Contains the wrapper functions for the most of the functions in \file{SWI-Prolog.h}. This file is not intended to be used by itself, but is \exam{\#include}d by \file{SWI-cpp2.h}. \item \file{test_cpp.cpp}, \file{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 \file{test_ffi.cpp}, \file{test_ffi.pl}, which often have the same tests written in C, without the C++ API. \end{itemize} \subsection{Summary of classes} \label{sec:cpp2-class-summary} The list below summarises the classes defined in the C++ interface. \begin{description} \classitem{PlTerm} Generic Prolog term that wraps \ctype{term_t} (for more details on \ctype{term_t}, see \href{https://www.swi-prolog.org/pldoc/man?section=foreigntypes}{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 \secref{cpp2-plterm-casting}. The subclass constructors are as follows. If a constructor fails (e.g., out of memory), a \ctype{PlException} is thrown. \begin{description} \classitem{PlTerm_atom} Subclass of \ctype{PlTerm} with constructors for building a term that contains an atom. \classitem{PlTerm_var} Subclass of \ctype{PlTerm} with constructors for building a term that contains an uninstantiated variable. Typically this term is then unified with another object. \classitem{PlTerm_term_t} Subclass of \ctype{PlTerm} with constructors for building a term from a C \ctype{term_t}. \classitem{PlTerm_integer} Subclass of \ctype{PlTerm} with constructors for building a term that contains a Prolog integer from a \ctype{long}.\footnote{PL_put_integer() takes a \ctype{long} argument.} \classitem{PlTerm_int64} Subclass of \ctype{PlTerm} with constructors for building a term that contains a Prolog integer from a \ctype{int64_t}. \classitem{PlTerm_uint64} Subclass of \ctype{PlTerm} with constructors for building a term that contains a Prolog integer from a \ctype{uint64_t}. \classitem{PlTerm_size_t} Subclass of \ctype{PlTerm} with constructors for building a term that contains a Prolog integer from a \ctype{size_t}. \classitem{PlTerm_float} Subclass of \ctype{PlTerm} with constructors for building a term that contains a Prolog float. \classitem{PlTerm_pointer} Subclass of \ctype{PlTerm} with constructors for building a term that contains a raw pointer. This is mainly for backwards compatibility; new code should use \jargon{blobs}. \classitem{PlTerm_string} Subclass of \ctype{PlTerm} with constructors for building a term that contains a Prolog string object. \classitem{PlTerm_list_codes} Subclass of \ctype{PlTerm} with constructors for building Prolog lists of character integer values. \classitem{PlTerm_chars} Subclass of \ctype{PlTerm} with constructors for building Prolog lists of one-character atoms (as atom_chars/2). \classitem{PlTerm_tail} SubClass of \ctype{PlTerm} for building and analysing Prolog lists. \end{description} Additional subclasses of \ctype{PlTerm} are: \begin{description} \classitem{PlCompound} Subclass of \ctype{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 \ctype{PlTermv} with the arguments. \classitem{PlTermv} Vector of Prolog terms. See PL_new_term_refs(). The \const{[]} operator is overloaded to access elements in this vector. \ctype{PlTermv} is used to build complex terms and provide argument-lists to Prolog goals. \end{description} \classitem{PlException} Subclass of \ctype{PlExceptionBase}, representing a Prolog exception. Provides methods for the Prolog communication and mapping to human-readable text representation. \begin{description} \cfunction{PlTerm}{PlTypeError}{} Creates a \ctype{PlException} object for representing a Prolog \except{type_error} exception. \cfunction{PlTerm}{PlDomainError}{} Creates a \ctype{PlException} object for representing a Prolog \except{domain_error} exception. \cfunction{PlTerm}{PlExistenceError}{} Creates a \ctype{PlException} object for representing a Prolog \except{existence_error} exception. \cfunction{PlTerm}{PlPermissionError}{} Creates a \ctype{PlException}object for representing a Prolog \except{permission_error} exception. \end{description} \classitem{PlExceptionBase} A "do nothing" subclass of \ctype{std::exception}, to allow catching \ctype{PlException}, \ctype{PlExceptionFail} or \ctype{PlFail} in a single "catch" clause. \classitem{PlAtom} Allow for manipulating atoms (\ctype{atom_t}) in their internal Prolog representation for fast comparison. (For more details on \ctype{atom_t}, see \href{https://www.swi-prolog.org/pldoc/man?section=foreigntypes}{Interface Data Types}). \classitem{PlFunctor} A wrapper for \ctype{functor_t}, which maps to the internal representation of a name/arity pair. \classitem{PlPredicate} A wrapper for \ctype{predicate_t}, which maps to the internal representation of a Prolog predicate. \classitem{PlModule} A wrapper for \ctype{module_t}, which maps to the internal representation of a Prolog module. \classitem{PlQuery} Represents opening and enumerating the solutions to a Prolog query. \classitem{PlFail} Can be thrown to short-circuit processing and return failure to Prolog. Performance-critical code should use \exam{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 \ctype{PlFail}; but it's better style to create the error throwing one of the subclasses of \ctype{PlException} e.g., \exam{throw PlTypeError("int", t)}. \classitem{PlException} If a call to Prolog results in an error, the C++ interface converts the error into a \ctype{PlException} object and throws it. If the enclosing code doesn't intercept the exception, the \ctype{PlException} object is turned back into a Prolog error. \classitem{PlExceptionFail} In some situations, a Prolog error cannot be turned into a \ctype{PlException} object, so a \ctype{PlExceptionFail} object is thrown. This is turned into failure by the PREDICATE() macro, resulting in normal Prolog error handling. \classitem{PlFrame} This utility-class can be used to discard unused term-references as well as to do `\jargon{data-backtracking}'. \classitem{PlEngine} This class is used in \jargon{embedded} applications (applications where the main control is held in C++). It provides creation and destruction of the Prolog environment. \classitem{PlRegister} The encapsulation of PL_register_foreign() is defined to be able to use C++ global constructors for registering foreign predicates. \end{description} The required C++ function header and registration of a predicate is arranged through a macro called PREDICATE(). \subsection{Wrapper functions} \label{sec:cpp2-wrapper-functions} The various PL_*() functions in \file{SWI-Prolog.h} have corresponding Plx_*() functions. There are three kinds of wrappers: \begin{itemize} \item "as-is" - the PL_*() function cannot cause an error. If it has a return value, the caller will want to use it. (These are defined using the PLX_ASIS() and PLX_VOID() macros.) \item "exception wrapper" - the PL_*() function can return \const{false}, indicating an error. The Plx*() function checks for this and throws a \ctype{PlException} object containing the error. The wrapper uses \exam{template C_t PlExce(C_t rc)}, where \exam{C_t} is the return type of the PL_*() function. (These are defined using the PLX_WRAP() macro.) \item "success, failure, or error" - the PL_*() function can return \const{true} if it succeeds and \const{false} if it fails or has a runtime error. If it fails, the wrapper checks for a Prolog error and throws a \ctype{PlException} object containing the error. The wrapper uses \exam{template C_t PlWrap(C_t rc)}, where \exam{C_t} is the return type of the PL_*() function. (These are defined using the PLX_EXCE() macro.) \end{itemize} 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 (\const{PL_S_EXCEPTION}, \const{PL_S_LAST}, etc.) if the query was opened with the \const{PL_Q_EXT_STATUS} flag. Most of the PL_*() functions whose first argument is of type \ctype{term_t}, \ctype{atom_t}, etc. have corresponding methods in classes \ctype{PlTerm}, \ctype{PlAtom}, etc. \emph{Important}: You should use the Plx_*() wrappers only in the context of a PREDICATE() call, which will handle any C++ exceptions. If you use a Plx_*() wrapper in another situation (e.g., in a callback for a blob), results are unpredicatable (probably a crash). \subsection{Naming conventions, utility functions and methods (version 2)} \label{sec:cpp2-naming} See also \secref{cpp2-philosophy}. 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 (\ctype{PlFunctor}, \ctype{PlAtom}, \ctype{PlTerm}), etc. all contain a field \exam{C_} that contains the wrapped value (\ctype{functor_t}, \ctype{atom_t}, \ctype{term_t} respectively). The wrapper classes (which subclass \ctype{WrappedC<\ldots>}) all define the following methods and constants: \begin{itemize} \item default constructor (sets the wrapped value to \exam{null}) \item constructor that takes the wrapped value (e.g., for \ctype{PlAtom}, the constructor takes an \ctype{atom_t} value). \item \exam{C_} - the wrapped value. This can be used directly when calling C functions, for example, if \exam{t} and \exam{a} are of type \ctype{PlTerm} and \ctype{PlAtom}: \verb$Plcheck_PL(PL_put_atom(t.C_,a.C_))$. \item \exam{null} - the null value (typically \exam{0}, but code should not rely on this) \item \exam{is_null()}, \exam{not_null()} - test for the wrapped value being \exam{null}. \item \exam{reset()} - set the wrapped value to \exam{null} \item \exam{reset(new_value)} - set the wrapped value \item The \ctype{bool} operator is turned off - you should use not_null() instead.\footnote{The reason: a \ctype{bool} conversion causes ambiguity with \exam{PlAtom(PlTterm)} and \exam{PlAtom(atom_t)}.} \end{itemize} The \exam{C_} field can be used wherever a \ctype{atom_t} or \ctype{term_t} is used. For example, the PL_scan_options() example code can be written as follows. Note the use of \exam{\&callback.C_} to pass a pointer to the wrapped \ctype{term_t} value. \begin{code} 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(). } \end{code} For functions in \file{SWI-Prolog.h} that don't have a C++ equivalent in \file{SWI-cpp2.h}, PlCheck_PL() is a convenience function that checks the return code and throws a \ctype{PlFail} exception on failure or \ctype{PlException} if there was an exception. The PREDICATE() code catches \ctype{PlFail} exceptions and converts them to the \ctype{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 \ctype{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 \ctype{int} or \ctype{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 \ctype{int} and \ctype{long}, nor for \ctype{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 \ctype{int64_t}, \ctype{uint64_t}, \ctype{size_t}. In some cases,it is possible to overload methods; for example, this allows the following code without knowing the exact definition of \ctype{size_t}: \begin{code} PREDICATE(p, 1) { size_t sz; A1.integer(&sz); ... } \end{code} \emph{It is strongly recommended that you enable conversion checking.} For example, with GNU C++, these options (possibly with \exam{-Werror}: \exam{-Wconversion -Warith-conversion -Wsign-conversion -Wfloat-conversion}. There is an additional problem with characters - C promotes them to \ctype{int} but C++ doesn't. In general, this shouldn't cause any problems, but care must be used with the various getters for integers. \subsection{Blobs} \label{sec:cpp2-blobs} \emph{Disclaimer:} The blob API for C++ is not completely general, but is designed to make a specific use case easier to write. For other use cases, the underlying C API can still be used. The use case is: \begin{itemize} \item The blob contains the foreign object (e.g., contains a pointer to a database connection), plus optionally some other data. \item The blob is created by a predicate that makes the foreign object and stores it (or a pointer to it) within the blob - for example, making a connection to a database or compiling a regular expression into an internal form. \item Optionally, there is a predicate that deletes the foreign object, such as a file or database connection close(). \item The blob will not be subclassed. \item The blob is defined as a subclass of \ctype{PlBlob}, which provides a number of fields and methods, of which a few can be overridden in the blob (notably: write_fields(), compare_fields(), save(), load(), and the destructor). \item The blob must have a default constructor that sets all the fields to appropriate initial values.\footnote{This is used by the load() method, which by default throws an error.} \item The blob's constructor throws an exception and cleans up any resources if it cannot create the blob.\footnote{This is not a strong requirement, but the code is simpler if this style is used.} \item The foreign object can be deleted when the blob is deleted. That is, the foreign object is created using the \const{new} operator and passes ownership to the blob. \item The blob's allocation is controlled by Prolog and its destructor is envoked when the blob is garbage collected. Optionally, the predicate that deletes the foreign object deletes the foreign object and the Prolog garbage collector only frees the blob. \end{itemize} A Prolog blob consists of five parts: \begin{itemize} \item A \ctype{PL_blob_t} structure that defines the callbacks. \item A structure that contains the blob data. \item A "create" or "open" predicate that unifies one of its arguments with a newly created blob that contains the foreign object. \item (Optionally) a "close" predicate that does the opposite of the "create" or "open" predicate. \item Predicates that manipulate the foreign object (e.g., for a file-like object, these could be read, write, seek, etc.). \end{itemize} For the \ctype{PL_blob_t} structure, the C++ API provides a set of template functions that allow easily setting up the callbacks, and defining the corresonding methods in the blob "contents" class. The C interface allows more flexibility by allosing some of the callbacks to default; however, the C++ API for blobs provides suitable callbacks for all of them, so usually the programmer will specify all the template callbacks using the PL_BLOB_DEFINITION(blob_class,blob_name) macro. For the data, which is subclassed from \ctype{PlBlob}, the programmer defines the various fields, a constructor that initializes them, and a destructor. Optionally, methods can be defined for one of more of blob compare_fields(), write_fields(), save(), load(). More details on these are given later. There is a mismatch between how Prolog does memory management (and garbage collection) and how C++ does it. In particular, Prolog assumes that cleanup will be done in the release() function associated with the blob whereas C++ typically does cleanup in a destructor. The blob interface gets around this mismatch by providing a default release() function that assumes that the blob was created using \const{PL_BLOB_NOCOPY} and manages memory using a \ctype{std::unique_ptr}. The C blob interface has a flag that determines how memory is managed: \const{PL_BLOB_NOCOPY}. The PL_BLOB_DEFINITION() macro sets this, so Prolog does not do a call to free() when the blob is garbage collected; instead, it lets the blob's release() free the memory, which is done by calling the C++ destructor. The C++ API for blobs only supports blobs with \const{PL_BLOB_NOCOPY}.\footnote{The API can probably also support blobs with \const{PL_BLOB_UNIQUE}, but there seems to be little point in setting this flag for non-text blobs.} \subsubsection{How to define a blob using C++} \label{sec:cpp2-blobs-howto} TL;DR: Use PL_BLOB_DEFINITION() to define the blob with the flag \const{PL_BLOB_NOCOPY} and the default \ctype{PlBlob} wrappers; define your struct as a subclass of \ctype{PlBlob} with no copy constructor, move constructor, or assignment operator; create blob using exam{std::unique_ptr(new ...)}, call PlTerm::unify_blob(). Optionally, define one or more of: compare_fields(), write_fields(), save(), load() methods (these are described after the sample code). \subsubsection{The life of a PlBlob} \label{sec:cpp2-blobs-life} In this section, the blob is of type \ctype{MyBlob}, a subclass of \ctype{PlBlob}. A blob is typically created by calling a predicate that does the following: \begin{itemize} \item Creates the blob using \exam{auto ref = std::unique_ptr(new MyBlob>(...))} (std::make_unique() can't be used because it returns type \ctype{std::unique_ptr} but PlTerm::unify_blob() requires a \ctype{std::unique_ptr} and C++'s type inferencing can't figure out that this is a covariant type. \item Calls PlTerm::unify_blob(ref), using PlCheckFail() to throw an exception if it fails. This, in turn, calls: \begin{itemize} \item PlBlobVacquire(), which calls \item MyBlob::acquire(), which sets \arg{MyBlob::symbol_}. \arg{MyBlob::symbol_} is usually accessed using the method MyBlob::symbol_term(). If this all succeeds, PlTerm::unify_blob(ref) calls \exam{ref.release()} to pass ownership to the Prolog blob. If you wish to use std::make_unique(), you could instead do: \begin{code} auto ref = std::make_unique(...); ... // code that accesses fields in *ref std::unique_ptr refb(ref.release()); // transfer ownership of ptr // from here on, can't access fields in *ref return A2.unify_blob(refb); \end{code} \end{itemize} \end{itemize} At this point, the blob is owned by Prolog and will be freed by its atom garbage collector. Whenever a predicate is called with the blob as an argument (e.g., as \arg{A1}), the blob can be accessed by \exam{PlBlobv::cast_check(A1.as_atom())}. Within a method, the Prolog blob can be accessed as a term (e.g., for constructing an error term) using the method MyBlob::symbol_term(). This field is initialized by the call to PlTerm::unify_blob(); if MyBlob::symbol_term() is called before a successful call to PlTerm::unify_blob(), MyBlob::symbol_term() returns a \ctype{PlTerm_var}. When the atom garbage collector runs, it frees the blob by first calling the release() callback, which does \const{delete}, which calls the destructor MyBlob::~MyBlob(). Note that C++ destructors are not supposed to raise exception; they also should not cause a Prolog error, which could cause deadlock unless the real work is done in another thread. Often it is desired to release the resources before the garbage collector runs. To do this, the programmer can provide a "close" predicate which is the inverse of the "open" predicate that created the blob. This typically has the same logic as the destructor, except that it can raise a Prolog error. \subsubsection{C++ exceptions and blobs} \label{sec:cpp2-blobs-exceptions} When a blob is used in the context of a PREDICATE() macro, it can raise a C++ exception (\ctype{PlFail} or \ctype{PlException}) and the PREDICATE() code will convert it to the appropriate Prolog failure or error; memory allocation exceptions are also handled. Blobs have callbacks, which can run outside the context of a PREDICATE(). Their exception handling is as follows: \begin{itemize} \item acquire(), which is called from PlBlobV::acquire() can throw a C++ exception. \item compare_fields(), which is called from PlBlobV::compare() should not throw an exception. A Prolog error won't work as it uses "raw pointers" and thus a GC or stack shift triggered by creating the exception will upset the system. \item write_fields(), which is called from PlBlobV::write() can throw an exception, just like code inside a PREDICATE(). In particular, you can wrap calls to Sfprintf() in PlCheckFail(), although the calling context will check for errors on the stream, so checking the Sfprintf() result isn't necessary. \item save() can throw a C++ exception, including PlFail(). \item load() can throw a C++ exception, which is converted to a return value of\tag{PlAtom::null}, which is interpreted by Prolog as failure. \end{itemize} \subsubsection{Sample PlBlob code} \label{sec:cpp2-blobs-sample-code} Here is minimal sample code for creating a blob that owns a connection to a database. It has a single field (\exam{connection}) and defines compare_fields() and write_fields(). Note that you must add the boilerplate definition for the virtual method blob_size_(), using the convenience macros PL_BLOB_DEFINITION(blob_class,blob_name) and \const{PL_BLOB_SIZE}. \begin{code} struct MyBlob; static PL_blob_t my_blob = PL_BLOB_DEFINITION(MyBlob, "my_blob"); struct MyBlob : public PlBlob { std::unique_ptr connection; std::string name_; // Used for error terms explicit MyBlob() : PlBlob(&my_blob) { } explicit MyBlob(const std::string& connection_name) : PlBlob(&my_blob), connection(std::make_unique(connection_name)), name_(connection_name) { if ( !connection->open() ) throw MyBlobError("my_blob_open_error"); } PL_BLOB_SIZE ~MyBlob() noexcept { if ( !close() ) Sdprintf("Close MyBlob failed: %s", name_.c_str()); // Can't use PL_warning() } bool close() noexcept { if ( !connection ) return true; bool rc = connection->close(); connection.reset(); // Can be omitted, leaving deletion to ~MyBlob() return rc; } PlException MyBlobError(const char* error) const { return PlGeneralError(PlCompound(error, PlTermv(symbol_term()))); } int compare_fields(const PlBlob* _b_data) const override { auto b_data = static_cast(_b_data); // See note about cast return name_.compare(b_data->name_); } bool write_fields(IOSTREAM *s, int flags) const override { if ( !Sfprintf(s, ",name=%s", name_.c_str()) ) return false; if ( !connection ) return Sfprintf(s, ",closed"); return true; } }; // %! create_my_blob(+Name: atom, -MyBlob) is semidet. PREDICATE(create_my_blob, 2) { // Allocating the blob uses std::unique_ptr so that it'll be // deleted if an error happens - the auto-deletion is disabled by // ref.release() before returning success. auto ref = std::unique_ptr(new MyBlob(A1.as_atom().as_string())); return A2.unify_blob(&ref); } // %! close_my_blob(+MyBlob) is det. // % Close the connection, silently succeeding if is already // % closed; throw an exception if something goes wrong. PREDICATE(close_my_blob, 1) { auto ref = PlBlobV::cast_ex(A1, my_blob); if ( !ref->close() ) throw ref->MyBlobError("my_blob_close_error"); return true; } \end{code} \subsubsection{Discussion of the sample PlBlob code} \label{sec:cpp2-blobs-sample-code-discussion} \begin{itemize} \item PL_BLOB_DEFINITION(MyBlob, "my_blob") creates a \ctype{PL_blob_t} structure with the wrapper functions and flags set to \const{PL_BLOB_NOCOPY}. It should be declared outside the \ctype{PlBlob} class and should not be marked \exam{const} - otherwise, a runtime error can occur.\footnote{The cause of the runtime error is not clear, but possibly has to do with the order of initializing globals, which is unspecified for C++.} \item The \ctype{MyBlob} struct is a subclass of \ctype{PlBlob}. See below for a discussion of the default behaviors. \begin{itemize} \item \ctype{MyBlob} contains a pointer to a \ctype{MyConnection} object and keeps a copy of the connection's name. The \ctype{MyConnection} object is handled by a \ctype{std::unique_ptr} smart pointer, so that it is automatically freed when the \ctype{MyBlob} object is freed. \item A default constructor is defined - this is needed for the load() and save() methods; it invokes the \ctype{PlBlob} constructor. \item The \ctype{MyBlob} class must not provide a copy or move constructor, nor an assignment operator (PlBlob defines these as deleted, so if you try to use one of these, you will get a compile-time error). \item \ctype{PlBlob}'s constructor sets \exam{blob_t_} to a pointer to the \ctype{my_blob} definition. This is used for run-time consistency checking by the various callback functions and for constructing error terms (see PlBlob::symbol_term()). \item \ctype{PlBlob}'s acquire() is called by PlBlobV::acuire() and fills in the \exam{symbol} field. \ctype{MyBlob} must not override this - it is not a virtual method. \item PlBlob::symbol_term() Creates a term from the blob, for use in error terms. It is always safe to use this; if the symbol hasn't been set (because acquire() hasn't been called), symbol_term() returns a "var" term. \item The MyBlob(connection_name) constructor creates a \ctype{MyConnection} object. If this fails, an exception is thrown. The constructor then calls MyConnection::open() and throws an exception if that fails. (The code would be similar if the constructor for \ctype{MyConnection} also did an open and threw an exception on failure.) \item The \const{PL_BLOB_SIZE} is boilerplate that defines a blob_size_() method that is used when the blob is created. \item The destructor ~MyBlob() is called when the blob is released by the garbage collector and in turn calls the MyBlob::close(), throwing away the result. If there is an error, a message is printed because there is no other way report the error. For this reason, it is preferred that the program explicitly calls the close_my_blob/1 predicate, which can raise an error. One way of doing this is by using the at_halt/1 hook. \item The MyBlob::close() method is called by either the destructor or by the close_my_blob/1 predicate. Because it can be called by the garbage collector, which does not provide the usual environment and which may also be in a different thread, the only Prolog function that can be called is PlAtom::unregister_ref(); and the MyBlob::close() method must not throw an exception.\footnote{It isn't enough to just catch exceptions; for example, if the code does \exam{throw PlUnknownErro("...")}, that will try to create a Prolog term, which will crash because the environment for creating terms is not available.} Because there is no mechanism for reporting an error, the destructor prints a message on failure (calling PL_warning() would cause a crash). PlBlob::close() calls MyConnection::close() and then frees the object. Error handling is left to the caller because of the possibility that this is called in the context of garbage collection. It is not necessary to free the \ctype{MyConnection} object here - if it is not freed, the \ctype{std::unique_ptr}'s destructor would free it. \item PlBlob::MyBlobError() is a convenience method for creating errror terms. \item PlBlob::compare_fields() makes the blob comparison function more deterministic by comparing the name fields; if the names are the same, the comparison will be done by comparing the addresses of the blobs (this is the default behavior for blobs). PlBlob::compare_fields() is called by PlBlobV::compare(), which provides the default comparison if PlBlob::compare_fields() returns \const{0} ("equal"). The \arg{_b_data} argument is of type \ctype{const PlBlob*} - this is cast to \ctype{const MyBlob*} using a \const{static_cast}. This is safe because Prolog guarantees that PlBlobV::compare() will only be called if both blobs are of the same type. \item PlBlob::write_fields() outputs the name and the status of the connection, in addition to the default of outputting the blob type and its address. This is for illustrative purposes only; an alternative is to have a my_blob_properties/2 predicate to provide the information. The \arg{flags} argument is the same as given to PlBlobV::write(), which is a bitwise \emph{or} of zero or more of the \const{PL_WRT_*} flags that were passed in to the caling PL_write_term() (defined in \file{SWI-Prolog.h}). The \arg{flags} do not have the \const{PL_WRT_NEWLINE} bit set, so it is safe to call PlTerm::write() and there is no need for writing a trailing newline. If anything in PlBlob::write_fields() throws a C++ exception, it will be caught by the calling PlBlobV::write() and handled appropriately. \item PlBlob::save() and PlBlob::load() are not defined, so the defaults are used - they throw an error on an attempt to save the blob (e.g., by using \qsave_program/[1,2]).\footnote{If these weren't specified, the defaults would save the internal form of the blob, which is probably not what you want.} \end{itemize} \item create_my_blob/2 predicate: \begin{itemize} \item \exam{std::unique_ptr()} creates a MyBlob that is deleted when it goes out of scope. If an exception occurs between the creation of the blob or if the call to unify_blob() fails, the pointer will be automatically freed (and the \ctype{MyBlob} destructor will be called). If PlTerm::unify_blob() is called with a pointer to a \ctype{std::unique_ptr}, it takes ownership of the object by calling std::unique_ptr::release(). This sets \arg{ref} to \const{nullptr}, so any attempt to use \arg{ref} after a successful call to PlTerm::unify_blob() will be an error. If you wish to create a \ctype{MyBlob} object instead of a \ctype{PlBlob} object, a slightly different form is used: \begin{code} auto ref = std::make_unique(...); ... std::unique_ptr refb(ref.release()); PlCheckFail(A2.unify_blob(&refb); return true; \end{code} \end{itemize} \item close_my_blob/1 predicate: \begin{itemize} \item The argument is turned into a \ctype{MyBlob} pointer using the PlBlobV::cast_ex() function, which will throw a \const{type_error} if the argument isn't a blob of the expected type. \item The MyBlob::close() method is called - if it fails, a Prolog error is thrown. \end{itemize} \end{itemize} \subsection{Limitations of the interface} \label{sec:cpp2-limitations} The C++ API remains a work in progress. \subsubsection{Strings} \label{sec:cpp2-limitations-strings} SWI-Prolog string handling has evolved over time. The functions that create atoms or strings using \ctype{char*} or \ctype{wchar_t*} are "old school"; similarly with functions that get the string as \ctype{char*} or \ctype{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 \ctype{char*} strings can be automatically cast to string. If a C++ interface provides only \ctype{std::string} arguments or return values, that can introduce some inefficiency; therefore, many of the functions and constructors allow either a \ctype{char*} or \ctype{std::string} as a value (also \ctype{wchar_t*} or \ctype{std::wstring}. For return values, \ctype{char*} is dangerous because it can point to local or stack memory. For this reason, wherever possible, the C++ API returns a \ctype{std::string}, which contains a copy of the the string. This can be slightly less efficient that returning a \ctype{char*}, but it avoids some subtle and pervasive bugs that even address sanitizers can't detect.\footnote{If 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 \exam{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 \ctype{int32_t}, and not that the value is converted to a \ctype{int32_t}. That is, if the value is a float, \ctype{int32_t} will fail with an error rather than (for example) truncating the floating point value to fit into a 32-bit integer. \subsubsection{Object handles} \label{sec:cpp2-limitations-handles} Many of the "opaque object handles", such as \ctype{atom_t}, \ctype{term_t}, and \ctype{functor_t} are integers.\footnote{Typically \ctype{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 \ctype{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: \begin{itemize} \item A subclass for each kind of initializer; \item A tag for each kind of intializer; \item Change the the C code to use a \ctype{struct} instead of an integer. \end{itemize} 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. \subsection{Linking embedded applications using swipl-ld} \label{sec:cpp2-plld} The utility program \program{swipl-ld} (Win32: swipl-ld.exe) works with both C and C++ programs. See \href{https://www.swi-prolog.org/pldoc/man?section=plld}{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 \file{SWI-cpp2.cpp} is not included in the shared object \file{libswipl}; instead, it must be compiled along with any foreign predicate files. You can do this in three ways: \begin{itemize} \item Compile \file{SWI-cpp2.cpp} separately. \item Add \verb$#include SWI-cpp2.cpp$ to one of the foreign predicate files. \item Wherever you have \verb$#include SWI-cpp2.h%$, add \begin{code} #define _SWI_CPP2_CPP_inline inline #include \end{code} 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. \end{itemize} \section{Examples (version 2)} \label{sec:cpp2-examples} Before going into a detailed description of the C++ classes we present a few examples illustrating the `feel' of the interface. \subsection{Hello(World) (version 2)} \label{sec:cpp2-hello-world} This simple example shows the basic definition of the predicate hello/1 and how a Prolog argument is converted to C-data: \begin{code} PREDICATE(hello, 1) { cout << "Hello " << A1.as_string() << endl; return true; } \end{code} The arguments to PREDICATE() are the name and arity of the predicate. The macros A provide access to the predicate arguments by position and are of the type \ctype{PlTerm}. The C or C++ string for a \ctype{PlTerm} can be extracted using as_string(), or as_wstring() methods;\footnote{The C-string values can be extracted from \ctype{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: \begin{code} ?- hello(world). Hello world Yes ?- hello(X) Hello _G170 X = _G170 \end{code} \subsection{Adding numbers (version 2)} \label{sec:cpp2-ex-adding-numbers} 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. \begin{code} PREDICATE(add, 3) { return A3.unify_integer(A1.as_long() + A2.as_long()); } \end{code} You can use your own variable names instead of \exam{A1}, \exam{A2}, etc.: \begin{code} 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()); } \end{code} The as_long() method for a \ctype{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 \ctype{long}. The unify_integer() method of \ctype{PlTerm} is defined to perform unification and returns \const{true} or \const{false} depending on the result. \begin{code} ?- add(1, 2, X). X = 3. ?- add(a, 2, X). [ERROR: Type error: `integer' expected, found `a'] Exception: ( 7) add(a, 2, _G197) ? \end{code} \subsection{Average of solutions (version 2)} \label{sec:cpp2-ex-average} This example is a bit harder. The predicate average/3 is defined to take the template \mbox{average(+Var, :Goal, -Average)}, where \arg{Goal} binds \arg{Var} and will unify \arg{Average} with average of the (integer) results. \ctype{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 \const{true} if there was a solution and \const{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. \begin{code} 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)); } \end{code} \begin{code} ?- [user]. |: p(1). |: p(10). |: p(20). |: % user://1 compiled 0.00 sec, 3 clauses true. ?- average(X, p(X), Average). Average = 10.333333333333334. \end{code} \section{Rationale for changes from version 1 (version 2)} \label{sec:cpp2-rationale} \subsection{Implicit constructors and conversion operators} \label{sec:cpp2-rationale-ctors} The original version of the C++ interface heavily used implicit constructors and conversion operators. This allowed, for example: \begin{code} PREDICATE(hello, 1) { cout << "Hello " << A1.as_string() << endl; return true; } PREDICATE(add, 3) { return A3 = (long)A1 + (long)A2; } \end{code} Version 2 is a bit more verbose: \begin{code} PREDICATE(hello, 1) { cout << "Hello " << A1.as_string() << endl; return true; } PREDICATE(add, 3) { return A3.unify_int(A1.as_long() + A2.as_long()); } \end{code} There are a few reasons for this: \begin{itemize} \item The C-style of casts is deprecated in C++, so the expression \exam{(char *)A1} becomes the more verbose \exam{static_cast(A1)}, which is longer than \exam{A1.as_string()}. Also, the string casts don't allow for specifying encoding. \item The implicit constructors and conversion operators allowed directly calling the foreign language interface functions, for example: \begin{code} PlTerm t; Pl_put_atom_chars(t, "someName"); \end{code} whereas this is now required: \begin{code} PlTerm t; Pl_put_atom_chars(t.as_term_t(), "someName"); \end{code} However, this is mostly avoided by methods and constructors that wrap the foreign language functions: \begin{code} PlTerm_atom t("someName"); \end{code} or \begin{code} auto t = PlTerm_atom("someName"); \end{code} \item The implicit constructors and conversion operators, combined with the C++ conversion rules for integers and floats, could sometimes lead to subtle bugs that were difficult to find -- in one case, a typo resulted in terms being unified with floating point values when the code intended them to be atoms. This was mainly because the underlying C types for terms, atoms, etc. are unsigned integers, leading to confusion between numeric values and Prolog terms and atoms. \item The overloaded assignment operator for unification changed the usual C++ semantics for assignments from returning a reference to the left-hand-side to returning a ctype{bool}. In addition, the result of unification should always be checked (e.g., an "always succeed" unification could fail due to an out-of-memory error); the unify_XXX() methods return a \ctype{bool} and they can be wrapped inside a PlCheckFail() to raise an exception on unification failure. \end{itemize} 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. \subsection{Strings} \label{sec:cpp2-rationale-strings} The version API often used \ctype{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 \ctype{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 \ctype{char*} to \ctype{std::string}, so some of the API support only \ctype{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 \ctype{std::string}); but for performance-critical code, the C functions can still be used. There still remains the problems of Unicode and encodings. \ctype{std::wstring} is one way of dealing with this. And for interfaces that use \ctype{std::string}, an encoding can be specified.\footnote{As 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. \section{Porting from version 1 to version 2} \label{sec:cpp2-porting-1-2} \file{SWI-cpp2.h} is not complete; it needs `file{SWI-cpp2.cpp} to implement some functions. The easiest way of taking care of this is to add \verb$#include $ in your "main" file; alternatively, you can create another source file that contains the "include" statement. The easiest way of porting from \file{SWI-cpp.h} to \file{SWI-cpp2.h} is to change the \exam{\#include "SWI-cpp.h"} to \exam{\#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 \ctype{term_t}, \ctype{atom_t}, etc. have corresponding methods in \ctype{PlTerm}, \ctype{PlAtom}, etc. Here is a list of typical changes: \begin{itemize} \item Replace PlTerm() constructor with PlTerm_var() for uninstantiated variables, \cfuncref{PlTerm_atom}{a} for atoms, \cfuncref{PlTerm_term_t}{t} for the raw \ctype{term_t}, \cfuncref{PlTerm_integer}{i}, \cfuncref{PlTerm_float}{v}, or \cfuncref{PlTerm_pointer}{p}. \item Examine uses of \ctype{char*} or \ctype{wchar_t} and replace them by \ctype{std::string} or \ctype{std::wstring} if appropriate. For example, \exam{cout << "Hello " << A1.as_string().c_str()() << endl} can be replaced by \exam{cout << "Hello " << A1.as_string() << endl}. In general, \ctype{std::string} is safer than \ctype{char*} because the latter can potentially point to freed memory. \item Instead of returning \const{false} from a predicate for failure, you can do \exam{throw PlFail()}. This mechanism is also used by \cfuncref{PlCheckFail}{rc}. Note that throwing an exception is significantly slower than returning \const{false}, so performance-critical code should avoid \cfuncref{PlCheckFail}{rc}. \item You can use the \cfuncref{PlCheck_PL}{rc} to check the return code from a function in \file{SWI-Prolog} and throw a \ctype{PlFail} exception to short-circuit execution and return failure (\const{false}) to Prolog (or throw a \ctype{PlException} if there was a Prolog error. \item \exam{PlAtom::handle} has been replaced by \exam{PlAtom::C_}. \item \exam{PlTerm::ref} has been replaced by \exam{PlAtom::C_}. \item \exam{PlFunctor::functor} has been replaced by \exam{PlAtom::C_}. \item The operator \exam{=} for unification has been deprecated, replaced by various \exam{unify_XXX}` methods (\cfuncref{PlTerm::unify_term}{t2}, \cfuncref{PlTerm::unify_atom}{a}, etc.). \item The various "cast" operators have been deprecated or deleted; you should use the various "getter" methods. For example, \exam{static_cast(t)} is replaced by \exam{t.as_string().c_str()}; \exam{static_cast(t)} is replaced by \exam{t.as_int32_t()}. \item It is recommended that you do not use \ctype{int} or \ctype{long} because of problems porting between Unix and Windows platforms; instead, use \ctype{int32_t}, \ctype{int64_t}, \ctype{uint32_t}, \ctype{uint64_t}, etc. \end{itemize} \section{The class PlFail (version 2)} \label{sec:cpp2-plfail} The \ctype{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 \secref{cpp2-exceptions-notes}). For example, this code: \begin{code} PREDICATE(unify_zero, 1) { if ( !PL_unify_integer(A1.C_, 0) ) return false; return true; } \end{code} can instead be written this way: \begin{code} void PREDICATE(unify_zero, 1) { if ( !PL_unify_integer(A1.C_, 0) ) throw PlFail(); return true; } \end{code} or: \begin{code} PREDICATE(unify_zero, 1) { PlCheck_PL(PL_unify_integer(t.C_, 0)); return true; } \end{code} or: \begin{code} PREDICATE(unify_zero, 1) { PlCheckFail(A1.unify_integer(0)); return true; } \end{code} or: \begin{code} PREDICATE(unify_zero, 1) { return A1.unify_integer(0); } \end{code} Using \exam{throw PlFail()} in performance-critical code can cause a signficant slowdown. A simple benchmark showed a 15x to 20x slowdown using \exam{throw PlFail()} compared to \exam{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: \begin{code} static foreign_t unify_zero(term_t a1) { return PL_unify_integer(a1, 0); } \end{code} \subsection{PlCheckFail(), PlCheckEx(), and PlCheck_PL() convenience functions} \label{sec:cpp2-plcheck} If one of the C "PL_" functions in \file{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++ \ctype{PlException}. PlCheckFail() calls PlCheckEx() and additionally throws PlFail() if the failure is for Prolog failure. The code for PlCheck() is just \begin{code} void PlCheck(int rc) { if ( !PlCheckEx(rc) ) throw PlFail(); } \end{code} PlCheckEx() calls PL_exception() to see if there is a Prolog exception; if so, the Prolog exception is converted to a \ctype{PlException} object, which is then thrown. For more details on the C++ exceptions, see \secref{cpp2-exceptions}. \section{The class PlTerm (version 2)} \label{sec:cpp2-plterm} As we have seen from the examples, the \ctype{PlTerm} class plays a central role in conversion and operating on Prolog data. This section provides complete documentation of this class. \subsection{Constructors (version 2)} \label{sec:cpp2-plterm-constructurs} The constructors are defined as subclasses of \ctype{PlTerm}, with a name that reflects the Prolog type of what is being created (e.g., \ctype{PlTerm_atom} creates an atom; \ctype{PlTerm_string} creates a Prolog string). All of the constructors are "explicit" because implicit creation of \ctype{PlTerm} objects can lead to subtle and difficult to debug errors. \begin{description} \constructor{PlTerm}{} Creates a new initialised "null" term (holding a Prolog variable). \constructor{PlTerm_term_t}{term_t t} Converts between the C-interface and the C++ interface by turning the term-reference into an instance of \ctype{PlTerm}. Note that, being a lightweight class, this is a no-op at the machine-level! \constructor{PlTerm_atom}{const char *text} Creates a term-references holding a Prolog atom representing \arg{text}. \constructor{PlTerm_atom}{const wchar_t *text} Creates a term-references holding a Prolog atom representing \arg{text}. \constructor{PlTerm_atom}{const PlAtom \&atom} Creates a term-references holding a Prolog atom from an atom-handle. \constructor{PlTerm_int}{long n} Creates a term-references holding a Prolog integer representing \arg{n}. \constructor{PlTerm_int}{int64_t n} Creates a term-references holding a Prolog integer representing \arg{n} (up to 64 bits signed). \constructor{PlTerm_int}{uint64_t n} Creates a term-references holding a Prolog integer representing \arg{n} (up to 64 bits unsigned). \constructor{PlTerm_float}{double f} Creates a term-references holding a Prolog float representing \arg{f}. \constructor{PlTerm_pointer}{void *ptr} Creates a term-references holding a Prolog pointer. A pointer is represented in Prolog as a mangled integer. The mangling is designed to make most pointers fit into a \jargon{tagged-integer}. Any valid pointer can be represented. This mechanism can be used to represent pointers to C++ objects in Prolog. Please note that `MyClass' should define conversion to and from \ctype{void *}. Also note that in general \jargon{blobs} are a better way of doing this (see the section on \jargon{blobs} in the Foreign Language Interface part of the SWI-Prolog manual). \begin{code} PREDICATE(make_my_object, 1) { auto myobj = new MyClass(); return A1.unify_pointer(myobj); } PREDICATE(my_object_contents, 2) { auto myobj = static_cast(A1.pointer()); return A2.unify_string(myobj->contents); } PREDICATE(free_my_object, 1) { auto myobj = static_cast(A1.pointer()); delete myobj; return true; } \end{code} \end{description} \subsection{Overview of accessing and changing values (version 2)} \label{sec:cpp2-plterm-get-put-unify} The \file{SWI-Prolog.h} header provides various functions for accessing, setting, and unifying terms, atoms and other types. Typically, these functions return a \const{0} (\const{false}) or \const{1} (\const{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: \begin{itemize} \item Put (set) a value, corresponding to the PL_put_*() functions. \item Get a value, corresponding to the PL_get_*() and PL_get_*_ex() functions. \item Unify a value, corresponding to the PL_unify_*() and PL_unify_*_ex() functions. \end{itemize} 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 \href{https://www.swi-prolog.org/pldoc/man?section=foreign-term-construct}{Constructing Terms}. For the "get" and "unify" operations, there are three possible failures: \begin{itemize} \item \const{false} return code \item unification failure \item exception (value of unexpected type or out of resources) \end{itemize} Each of these is communicated to Prolog by returning \const{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 \exam{throw PlFail()} for failure or \exam{throw PlException()} (or one of \ctype{PlException}'s subclasses) and the C++ API will take care of everything. \subsection{Converting PlTerm to native C and C++ types (version 2)} \label{sec:cpp2-plterm-casting} These are \emph{deprecated} and replaced by the various \exam{as_*()} methods. \ctype{PlTerm} can be converted to the following types: \begin{description} \cppcast{PlTerm}{term_t} This cast is used for integration with the C-interface primitives. \cppcast{PlTerm}{long} Yields a \ctype{long} if the \ctype{PlTerm} is a Prolog integer or float that can be converted without loss to a long. throws a \except{type_error} exception otherwise. \cppcast{PlTerm}{int} Same as for \ctype{long}, but might represent fewer bits. \cppcast{PlTerm}{double} Yields the value as a C double if \ctype{PlTerm} represents a Prolog integer or float. \cppcast{PlTerm}{wchar_t *} \nodescription \cppcast{PlTerm}{char *} Converts the Prolog argument using PL_get_chars() using the flags \const{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. \cppcast{PlTerm}{void *} Extracts pointer value from a term. The term should have been created by PlTerm::PlTerm(void*). \end{description} 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: \begin{description} \cfunction{int}{type}{} See PL_term_type() \cfunction{bool}{is_variable}{} See PL_is_variable() \cfunction{bool}{is_ground}{} See PL_is_ground() \cfunction{bool}{is_atom} See PL_is_atom() \cfunction{bool}{is_integer} See PL_is_integer() \cfunction{bool}{is_string} See PL_is_string() \cfunction{bool}{is_float} See PL_is_float() \cfunction{bool}{is_rational} See PL_is_rational() \cfunction{bool}{is_compound} See PL_is_compound() \cfunction{bool}{is_callable} See PL_is_callable() \cfunction{bool}{is_list} See PL_is_list() \cfunction{bool}{is_dict} See PL_is_dict() \cfunction{bool}{is_pair} See PL_is_pair() \cfunction{bool}{is_atomic} See PL_is_atomic() \cfunction{bool}{is_number} See PL_is_number() \cfunction{bool}{is_acyclic} See PL_is_acyclic() \cfunction{bool}{is_functor}{PlFunctor} See PL_is_functor() \end{description} \subsection{Unification (version 2)} \label{sec:cpp2-plterm-unification} See also \secref{cpp2-foreign-frame}. \begin{description} \cfunction{bool}{PlTerm::unify_term}{PlTerm} \nodescription \cfunction{bool}{PlTerm::unify_atom}{PlAtom} \nodescription \cfunction{bool}{PlTerm::unify_atom}{string} \nodescription \cfunction{bool}{PlTerm::unify_list_codes}{string} \nodescription \cfunction{bool}{PlTerm::unify_list_chars}{string} \nodescription \cfunction{bool}{PlTerm::unify_integer}{int} \nodescription \cfunction{bool}{PlTerm::unify_float}{double} \nodescription \cfunction{bool}{PlTerm::unify_string}{string} \nodescription \cfunction{bool}{PlTerm::unify_functor}{PlFunctor} \nodescription \cfunction{bool}{PlTerm::unify_pointer}{void *} \nodescription \cfunction{bool}{PlTerm::unify_nil}{} \nodescription \cfunction{bool}{PlTerm::unify_blob}{PlBlob* blob} \nodescription \cfunction{bool}{PlTerm::unify_blob}{std::unique_ptr blob} Does a call to PL_unify_blob() and, if successful, calls std::unique_ptr::release() to pass ownership to the Prolog blob. \cfunction{bool}{PlTerm::unify_blob}{void *blob, size_t len, PL_blob_t *type} \nodescription \cfunction{bool}{PlTerm::unify_chars}{int flags, size_t len, const char *s} A family of unification methods are defined for the various Prolog types and C++ types. Wherever \ctype{string} is shown, you can use: \begin{itemize} \item \ctype{char*} \item \ctype{whar_t*} \item \ctype{std::string} \item \ctype{std::wstring} \end{itemize} \end{description} Here is an example: \begin{code} PREDICATE(hostname, 1) { char buf[256]; if ( gethostname(buf, sizeof buf) == 0 ) return A1.unify_atom(buf); return false; } \end{code} An alternative way of writing this would use the PlCheckFail() to raise an exception if the unification fails. \begin{code} PREDICATE(hostname2, 1) { char buf[256]; PlCheckFail(gethostname(buf, sizeof buf) == 0); PlCheckFail(A1.unify_atom(buf)); return true; } \end{code} Of course, in a real program, the failure of \cfuncref{gethostname}{buf}{sizeof buf} should create an error term than contains information from \const{errno}. \subsection{Comparison (version 2)} \label{sec:cpp2-plterm-comparison} \begin{description} \cfunction{int}{PlTerm::compare}{const PlTerm \&t2} \nodescription \cfunction{bool}{PlTerm::operator ==}{const PlTerm \&t} \nodescription \cfunction{bool}{PlTerm::operator !=}{const PlTerm \&t} \nodescription \cfunction{bool}{PlTerm::operator $<$}{const PlTerm \&t} \nodescription \cfunction{bool}{PlTerm::operator $>$}{const PlTerm \&t} \nodescription \cfunction{bool}{PlTerm::operator $<=$}{const PlTerm \&t} \nodescription \cfunction{bool}{PlTerm::operator $>=$}{const PlTerm \&t} Compare the instance with \arg{t} and return the result according to the Prolog defined \jargon{standard order of terms}. \cfunction{bool}{PlTerm::operator ==}{long num} \nodescription \cfunction{bool}{PlTerm::operator !=}{long num} \nodescription \cfunction{bool}{PlTerm::operator $<$}{long num} \nodescription \cfunction{bool}{PlTerm::operator $>$}{long num} \nodescription \cfunction{bool}{PlTerm::operator $<=$}{long num} \nodescription \cfunction{bool}{PlTerm::operator $>=$}{long num} Convert \ctype{PlTerm} to a \ctype{long} and perform standard C-comparison between the two long integers. If \ctype{PlTerm} cannot be converted a \except{type_error} is raised. \cfunction{bool}{PlTerm::operator ==}{const wchar_t *} \nodescription \cfunction{bool}{PlTerm::operator ==}{const char *} \nodescription \cfunction{bool}{PlTerm::operator ==}{std::wstring} \nodescription \cfunction{bool}{PlTerm::operator ==}{std::string} Yields \const{true} if the \ctype{PlTerm} is an atom or string representing the same text as the argument, \const{false} if the conversion was successful, but the strings are not equal and an \except{type_error} exception if the conversion failed. \end{description} Below are some typical examples. See \secref{cpp2-dirplatom} for direct manipulation of atoms in their internal representation. \begin{center} \begin{tabularlp}{\tt A1 == PlCompound("a(1)")} \hline \tt A1 $<$ 0 & Test \arg{A1} to hold a Prolog integer or float that can be transformed lossless to an integer less than zero. \\ \tt A1 $<$ PlTerm(0) & \arg{A1} is before the term `0' in the `standard order of terms'. This means that if \arg{A1} represents an atom, this test yields \const{true}. \\ \tt A1 == PlCompound("a(1)") & Test \arg{A1} to represent the term \exam{a(1)}. \\ \tt A1 == "now" & Test \arg{A1} to be an atom or string holding the text ``now''. \\ \hline \end{tabularlp} \end{center} \subsection{Analysing compound terms (version 2)} \label{sec:cpp2-plterm-compound} Compound terms can be viewed as an array of terms with a name and arity (length). This view is expressed by overloading the \const{[]} operator. A \except{type_error} is raised if the argument is not compound and a \except{domain_error} if the index is out of range. In addition, the following functions are defined: \begin{description} \cfunction{PlTerm}{PlTerm::operator []}{int arg} If the \ctype{PlTerm} is a compound term and \arg{arg} is between 1 and the arity of the term, return a new \ctype{PlTerm} representing the arg-th argument of the term. If \ctype{PlTerm} is not compound, a \except{type_error} is raised. Id \arg{arg} is out of range, a \except{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 \ctype{PlCompound}. The following example tests \arg{x} to represent a term with first-argument an atom or string equal to \exam{gnat}. \begin{code} ..., if ( x[1] == "gnat" ) ... \end{code} \cfunction{const char *}{PlTerm::name}{} Return a \ctype{const char *} holding the name of the functor of the compound term. Raises a \except{type_error} if the argument is not compound. \cfunction{size_t}{PlTerm::arity}{} Returns the arity of the compound term. Raises a \except{type_error} if the argument is not compound. \end{description} \subsection{Miscellaneous (version 2)} \label{sec:cpp2-plterm-misc} \begin{description} \cfunction{bool}{is_null}{} \exam{t.is_null()} is the same as \exam{t.C_ == PlTerm::null} \cfunction{bool}{not_null}{} \exam{t.not_null()} is the same as \exam{t.C_ != PlTerm::null} \cfunction{bool}{reset}{} \exam{t.reset()} is the same as \exam{t.C_ = PlTerm::null} \cfunction{bool}{reset}{term_t} \exam{t.reset(x)} is the same as \exam{t.C_ = x} \cfunction{int}{PlTerm::type}{} Yields the actual type of the term as PL_term_type(). Return values are \const{PL_VARIABLE}, \const{PL_FLOAT}, \const{PL_INTEGER}, \const{PL_ATOM}, \const{PL_STRING} or \const{PL_TERM} \end{description} To avoid very confusing combinations of constructors and therefore possible undesirable effects a number of subclasses of \ctype{PlTerm} have been defined that provide constructors for creating special Prolog terms. These subclasses are defined below. \subsection{The class PlTermString (version 2)} \label{sec:cpp2-plstring} 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 \exam{PlTerm_pointer(void *ptr)}). \begin{description} \constructor{PlString}{const wchar_t *text} \nodescription \constructor{PlString}{const char *text} Create a SWI-Prolog string object from a 0-terminated C-string. The \arg{text} is copied. \constructor{PlString}{const wchar_t *text, size_t len} \nodescription \constructor{PlString}{const char *text, size_t len} Create a SWI-Prolog string object from a C-string with specified length. The \arg{text} may contain 0-characters and is copied. \end{description} \subsection{The class PlCodeList (version 2)} \label{sec:cpp2-codelist} \begin{description} \constructor{PlCodeList}{const wchar_t *text} \nodescription \constructor{PlCodeList}{const char *text} Create a Prolog list of ASCII codes from a 0-terminated C-string. \end{description} \subsection{The class PlCharList (version 2)} \label{sec:cpp2-plcharlist} Character lists are compliant to Prolog's atom_chars/2 predicate. \begin{description} \constructor{PlCharList}{const wchar_t *text} \nodescription \constructor{PlCharList}{const char *text} Create a Prolog list of one-character atoms from a 0-terminated C-string. \end{description} \subsection{The class PlCompound (version 2)} \label{sec:cpp2-plcompound} \begin{description} \constructor{PlCompound}{const wchar_t *text} \nodescription \constructor{PlCompound}{const char *text} Create a term by parsing (as read/1) the \arg{text}. If the \arg{text} is not valid Prolog syntax, a \except{syntax_error} exception is raised. Otherwise a new term-reference holding the parsed text is created. \constructor{PlCompound}{const wchar_t *functor, PlTermv args} \nodescription \constructor{PlCompound}{const char *functor, PlTermv args} Create a compound term with the given name from the given vector of arguments. See \ctype{PlTermv} for details. The example below creates the Prolog term \exam{hello(world)}. \begin{code} PlCompound("hello", PlTermv("world")) \end{code} \end{description} \subsection{The class PlTail (version 2)} \label{sec:cpp2-pltail} The class \ctype{PlTail} is both for analysing and constructing lists. It is called \ctype{PlTail} as enumeration-steps make the term-reference follow the `tail' of the list. \begin{description} \constructor{PlTail}{PlTerm list} A \ctype{PlTail} is created by making a new term-reference pointing to the same object. As \ctype{PlTail} is used to enumerate or build a Prolog list, the initial \arg{list} term-reference keeps pointing to the head of the list. \cfunction{int}{PlTail::append}{const PlTerm \&element} Appends \arg{element} to the list and make the \ctype{PlTail} reference point to the new variable tail. If \arg{A} is a variable, and this function is called on it using the argument \exam{"gnat"}, a list of the form \exam{[gnat|B]} is created and the \ctype{PlTail} object now points to the new variable \arg{B}. This function returns \const{true} if the unification succeeded and \const{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. \begin{code} int main(int argc, char **argv) { PlEngine e(argv[0]); PlTermv av(1); PlTail l(av[0]); for(int i=0; i r(new PlRecord(t.record()), PlRecordDeleter()); assert(t.unify_term(r->term())); \end{code} The class \ctype{PlRecordExternalCopy} keeps the \jargon{external record} as an uninterpreted string. It supports the following methods. \begin{description} \cfunction{}{PlRecordExternalCopy}{} Constructor. Creates a string using Pl_record_external(), copies it into the object, then deletes the reference using PL_erase_external(). \cfunction{PlTerm}{term}{} - creates a term from the record, using PL_recorded_external()). \end{description} \section{Unification and foreign frames (version 2)} \label{sec:cpp2-foreign-frame} 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 \ctype{PlFrame}, whose destructor calls PL_close_foreign_frame(). Using this, the example code with PL_unify() can be written: \begin{code} { PlFrame frame; ... if ( !t1.unify_term(t2) ) frame.rewind(); ... } \end{code} Note that PlTerm::unify_term() checks for an exception and throws an exception to Prolog; if you with to handle exceptions, you must call \exam{PL_unify_term(t1.C_,t2.C_)}. \section{The class PlRegister (version 2)} \label{sec:cpp2-plregister} This class encapsulates PL_register_foreign(). It is defined as a class rather then a function to exploit the C++ \jargon{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. \begin{description} \constructor{PlRegister}{const char *module, const char *name, int arity, foreign_t (f)(term_t t0, int a, control_t ctx)} Register \arg{f} as a the implementation of the foreign predicate /. This interface uses the \const{PL_FA_VARARGS} calling convention, where the argument list of the predicate is passed using an array of \ctype{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. \constructor{PlRegister}{const char *module, const char *name, foreign_t (*f)(PlTerm a0, \ldots)} Registers functions for use with the traditional calling conventional, where each positional argument to the predicate is passed as an argument to the function \arg{f}. This can be used to define functions as predicates similar to what is used in the C-interface: \begin{code} static foreign_t pl_hello(PlTerm a1) { ... } PlRegister x_hello_1(NULL, "hello", 1, pl_hello); \end{code} This construct is currently supported upto 3 arguments. \end{description} \section{The class PlQuery (version 2)} \label{sec:cpp2-plquery} This class encapsulates the call-backs onto Prolog. \begin{description} \constructor{PlQuery}{const char *name, const PlTermv \&av} Create a query where \arg{name} defines the name of the predicate and \arg{av} the argument vector. The arity is deduced from \arg{av}. The predicate is located in the Prolog module \module{user}. \constructor{PlQuery}{const char *module, const char *name, const PlTermv \&av} Same, but performs the predicate lookup in the indicated module. \cfunction{int}{PlQuery::next_solution}{} Provide the next solution to the query. Yields \const{true} if successful and \const{false} if there are no (more) solutions. Prolog exceptions are mapped to C++ exceptions. \cfunction{void}{PlQuery::cut()}{} Discards the query, but does not delete an of the data created by the query. If there is any pending Prolog exception, it is mapped to a C++ exception and thrown. The call to PlQuery::cut() is done implicitly by \ctype{PlQuery}'s destructor. Below is an example listing the currently defined Prolog modules to the terminal. \begin{code} PREDICATE(list_modules, 0) { PlTermv av(1); PlQuery q("current_module", av); while( q.next_solution() ) cout << av[0].as_string() << endl; return true; } \end{code} \end{description} In addition to the above, the following functions have been defined. \begin{description} \cfunction{int}{PlCall}{const char *predicate, const PlTermv \&av} Creates a \ctype{PlQuery} from the arguments generates the first next_solution() and destroys the query. Returns the result of next_solution() or an exception. \cfunction{int}{PlCall}{const char *module, const char *predicate, const PlTermv \&av} Same, locating the predicate in the named module. \cfunction{int}{PlCall}{const wchar_t *goal} \nodescription \cfunction{int}{PlCall}{const char *goal} Translates \arg{goal} into a term and calls this term as the other PlCall() variations. Especially suitable for simple goals such as making Prolog load a file. \end{description} \subsection{The class PlFrame (version 2)} \label{sec:cpp2-plframe} The class \ctype{PlFrame} provides an interface to discard unused term-references as well as rewinding unifications (\jargon{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 \ctype{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 \ctype{PlFrame} is the only way to reclaim them. \begin{description} \constructor{PlFrame}{} Creating an instance of this class marks all term-references created afterwards to be valid only in the scope of this instance. \destructor{PlFrame} Reclaims all term-references created after constructing the instance. \cfunction{void}{PlFrame::rewind}{} Discards all term-references {\bf and} global-stack data created as well as undoing all unifications after the instance was created. \end{description} \index{assert}% A typical use for \ctype{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: \begin{code} void assertWord(const char *word) { PlFrame fr; PlTermv av(1); av[0] = PlCompound("word", PlTermv(word)); PlQuery q("assert", av); PlCheckFail(q.next_solution()); } \end{code} This example shows the most sensible use of \ctype{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. \begin{code} PREDICATE(can_unify, 2) { PlFrame fr; int rval = (A1=A2); fr.rewind(); return rval; } \end{code} \cfuncref{PlRewindOnFail}{f} is a convenience function that does a frame rewind if unification fails. Here is an example, where \exam{name_to_term} contains a map from names to terms (which are made global by using the PL_record() function): \begin{code} static const std::map 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); }); } \end{code} \section{The PREDICATE and PREDICATE_NONDET macros (version 2)} \label{sec:cpp2-predicate-macro} 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 \begin{code} PREDICATE(hello, 1) \end{code} is the same as writing:\footnote{There are a few more details, such as catching \exam{std::bad_alloc}.}: \begin{code} 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) \end{code} The first function converts the parameters passed from the Prolog kernel to a \ctype{PlTermv} instance and maps exceptions raised in the body to simple failure or Prolog exceptions. The \ctype{PlRegister} global constructor registers the predicate. Finally, the function header for the implementation is created. \subsection{Variations of the PREDICATE macro (version 2)} \label{sec:cpp2-predicate-macro-variations} The PREDICATE() macros have a number of variations that deal with special cases. \begin{description} \cmacro{}{PREDICATE0}{name} This is the same as PREDICATE(name, 0). It avoids a compiler warning about that \const{PL_av} is not used. \cmacro{}{NAMED_PREDICATE}{plname, cname, arity} This version can be used to create predicates whose name is not a valid C++ identifier. Here is a ---hypothetical--- example, which unifies the second argument with a stringified version of the first. The `cname' is used to create a name for the functions. The concrete name does not matter, but must be unique. Typically it is a descriptive name using the limitations imposed by C++ indentifiers. \begin{code} NAMED_PREDICATE("#", hash, 2) { A2 = (wchar_t*)A1; } \end{code} \cmacro{}{PREDICATE_NONDET}{name, arity} Define a non-deterministic Prolog predicate in C++. See also \secref{cpp2-nondet}. \cmacro{}{NAMED_PREDICATE_NONDET}{plname, cname, arity} Define a non-deterministic Prolog predicate in C++, whose name is not a valid C++ identifier. See also \secref{cpp2-nondet}. \end{description} \subsection{Non-deterministic predicates (version 2)} \label{sec:cpp2-nondet} Non-deterministic predicates are defined using \cfuncref{PREDICATE_NONDET}{plname, cname, arity} or \cfuncref{NAMED_PREDICATE_NONDET}{plname, cname, arity}. A non-deterministic predicate returns a "context", which is passed to 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 (the context is \const{nullptr} on the first call). To simplify this, a template helper function PlControl::context_unique_ptr() provides a "smart pointer" that frees the context on normal return or an exception; when used with PL_retry_address(), the context's std:unique_ptr::release() is used to pass the context to Prolog for the next retry, and to prevent the context from being freed. If the predicate is called with \const{PL_PRUNE}, the normal \exam{return true} will implicitly free the context. The skeleton for a typical non-deterministic predicate is: \begin{code} struct PredContext { ... }; // The "context" for retries PREDICATE_NONDET(pred, ) { auto ctxt = handle.context_unique_ptr(); switch( PL_foreign_control(handle) ) { case PL_FIRST_CALL: ctxt.reset(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) ... PL_retry_address(ctxt.release()); // Succeed with a choice point } \end{code} \subsection{Controlling the Prolog destination module (version 2)} \label{sec:cpp2-module} With no special precautions, the predicates are defined into the module from which load_foreign_library/1 was called, or in the module \const{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, {\em 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: \begin{code} #define PROLOG_MODULE "math" #include #include PREDICATE(pi, 1) { A1 = M_PI; } \end{code} \begin{code} ?- math:pi(X). X = 3.14159 \end{code} \section{Exceptions (version 2)} \label{sec:cpp2-exceptions} See also \href{https://www.swi-prolog.org/pldoc/man?section=foreign-exceptions}{Prolog exceptions in foreign code}. Prolog exceptions are mapped to C++ exceptions using the class \ctype{PlException} (a subclass of \ctype{PlExceptionBase} 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, convenience functions have been created to exploit both their constructors for easy creation of these exceptions. If you wish to trap these, you should use \ctype{PlException} or \ctype{PlExceptionBase} and then look for the appropriate error name. For example, the following code catches \exam{"type_error"} and passes all other exceptions: \begin{code} try { do_something(...); } catch (const PlException& e) { PlTerm e_t = e.term(); PlAtom ATOM_type_error("type_error"); // e_t.name() == PlAtom("error") && e_t.arity() == 2 if ( e_t[1].name() == ATOM_type_error) ) { ... // expected type and culprit are \exam{e_t[1][1]} and \exam{e_t[1][2]} } else throw; } \end{code} The convenience functions are PlTypeEror() and PlDomainError(), PlDomainError(), PlInstantiationError(), PlExistenceError(), PlUninstantiationError(), PlRepresentationError(), PlPermissionError(), PlResourceError(), PlUnknownError(). There is also a PlGeneralError(inside) that creates \exam{error(inside,_)} terms and is used by the other error convience functions. To throw an exception, create an instance of \ctype{PlException} and use \exam{throw}. This is intercepted by the PREDICATE macro and turned into a Prolog exception. See \secref{cpp2-exceptions-notes}. \begin{code} char *data = "users"; throw PlException(PlCompound("no_database", PlTerm(data))); \end{code} \subsection{The class PlException (version 2)} \label{sec:cpp2-plexception} This subclass of \ctype{PlExceptionBase} is used to represent exceptions. Currently defined methods are: \begin{description} \constructor{PlException}{const PlTerm \&t} Create an exception from a general Prolog term. This provides the interface for throwing any Prolog terms as an exception. \cfunction{std::string}{as_string}{} The exception is translated into a message as produced by print_message/2. The character data is stored in a ring. Example: \begin{code} ...; try { PlCall("consult(load)"); } catch ( PlException& ex ) { cerr << ex.as_string() << endl; } \end{code} \cfunction{int}{plThrow}{} Used in the PREDICATE() wrapper to pass the exception to Prolog. See PL_raise_exeption(). \end{description} \subsection{The class PlTypeError (version 2)} \label{sec:cpp2-pl-type-error} A \jargon{type error} expresses that a term does not satisfy the expected basic Prolog type. \begin{description} \constructor{PlTypeError}{const std::string& expected, const PlTerm \&actual} Creates an ISO standard Prolog error term expressing the \arg{expected} type and \arg{actual} term that does not satisfy this type. \end{description} \subsection{The class PlDomainError (version 2)} \label{sec:cpp2-pl-domain-error} A \jargon{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 \const{io_mode} (read, write, append, ...). If an integer is provided, this is a \jargon{type error}, if an atom other than one of the defined io-modes is provided it is a \jargon{domain error}. \begin{description} \constructor{PlDomainError}{const std::string& expected, const PlTerm \&actual} Creates an ISO standard Prolog error term expressing a the \arg{expected} domain and the \arg{actual} term found. \end{description} \section{Embedded applications (version 2)} \label{sec:cpp2-embedding} 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 \jargon{main-program} and we want to use Prolog as a \jargon{logic server}. For these applications, the class \ctype{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.% \footnote{For 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.} \begin{description} \constructor{PlEngine}{int argc, char **argv} Initialises the Prolog engine. The application should make sure to pass \exam{argv[0]} from its main function, which is needed in the Unix version to find the running executable. See PL_initialise() for details. \constructor{PlEngine}{char *argv0} Simple constructure using the main constructor with the specified argument for \exam{argv[0]}. \destructor{PlEngine} Calls PL_cleanup() to destroy all data created by the Prolog engine. \end{description} \Secref{pltail} has a simple example using this class. \section{Considerations (version 2)} \label{sec:cpp2-considerations} \subsection{The C++ versus the C interface (version 2)} \label{sec:cpp2-vs-c} Not all functionality of the C-interface is provided, but as \ctype{PlTerm} and \ctype{term_t} are essentially the same thing with type-conversion between the two (using the \exam{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 \ctype{PlFrame}). Use of some intermediate types (\ctype{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 \secref{cpp2-global} \subsection{Notes on exceptions} \label{sec:cpp2-exceptions-notes} Exceptions are normal Prolog terms that are handled specially by the PREDICATE macro when they are used by a C++ \exam{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, \exam{throw PlDomainError(Domain,Culprit)} ends up doing the same thing as calling \exam{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 \const{FALSE} return code, checks for the pending exception and propagates the exception into the Prolog environment. As the term references (\ctype{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 \ctype{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 \ctype{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 \file{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. \subsection{Global terms, atoms, and functors} \label{sec:cpp2-global} Sometimes it is convenient to put constant terms and atoms as global variables in a file (with a \exam{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: \begin{code} static PlAtom ATOM_foo("foo"); static PlFunctor FUNCTOR_ff_2("ff", 2); \end{code} 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 \ctype{PlAtom} and \ctype{PlFunctor} objects to be created. However, to be safe, it is best to put such global variables \emph{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 \ctype{PlTerm} static variable - instead, a \ctype{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 \href{https://www.swi-prolog.org/pldoc/man?section=foreign-recorded}{Recorded database}). Therefore, global recorded terms must be wrapped inside a function. C++ will call the constructor upon first use. For example: \begin{code} static PlTerm term_foo_bar() { static PlRecord r(PlCompound("foo", PlTermv(PlTerm_atom("bar"))).record()); return r.term(); } \end{code} \subsection{Static linking and embedding (version 2)} \label{sec:cpp2-linking} The mechanisms outlined in this document can be used for static linking with the SWI-Prolog kernel using \manref{swipl-ld}{1}. In general the C++ linker should be used to deal with the C++ runtime libraries and global constructors. \subsection{Status and compiler versions (version 2)} \label{sec:cpp2-status} The current interface can be entirely defined in the \fileext{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 \fileext{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 \fileext{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 \ctype{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, \exam{throw PlInstantiationError(A1)} does not result in the same context and traceback information that would happen from \exam{Plx_instantiation_error(A1.C_); throw PlFail()}. See \secref{cpp2-exceptions-notes}. The Plx_*() wrappers may require small adjustments in whether their return values require \exam{[[nodiscard]]} or whether their return values should be treated as an error. The implementation of \ctype{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. \section{Conclusions (version 2)} \label{sec:cpp2-conclusions} 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.