1 A C++ interface to SWI-Prolog
All Application Manual Name SummaryHelp

1.6 Overview

One useful area for exploiting C++ features is type-conversion. Prolog variables are dynamically typed and all information is passed around using the C-interface type term_t. In C++, term_t is embedded in the lightweight class PlTerm. Other lightweight classes, such as PlAtom for atom_t are also provided. Constructors and operator definitions provide flexible operations and integration with important C-types (char*, wchar_t*, long and double), plus the C++-types (std::string, std::wstring). (char* and wchar_t* are deprecated in the C++ API; std::string and std::wstring are safer and should be used instead.)

Another useful area is in handling errors and cleanup. Prolog errors can be modeled using C++ exceptions; and C++'s destructors can be used to clean up error situations, to prevent memory and other resource leaks.

1.6.1 Design philosophy of the classes

See also section 1.6.5 for more on naming conventions and standard methods.

The general philosophy for C++ classes is that a “half-created” object should not be possible - that is, the constructor should either succeed with a completely usable object or it should throw an exception. This API tries to follow that philosophy, but there are some important exceptions and caveats. (For more on how the C++ and Prolog exceptions interrelate, see section 1.15.)

Most of the PL_*() functions have corresponding wrapper methods. For example, PlTerm::get_atom() calls Plx_get_atom(), which calls PL_get_atom(). If the PL_get_atom() has an error, it creates a Prolog error; the Plx_get_atom() wrapper checks for this and converts the error to a C++ exception, which is thrown; upon return to Prolog, the exception is turned back into a Prolog error. Therfore, code typically does not need to check for errors.

Some functions return false to indicate either failure or an error, for example PlTerm::unify_term(); for such methods, a check is made for an error and an exception is thrown, so the return value of false only means failure. (The whole thing can be wrapped in PlCheckFail(), in which case a PlFail exception is thrown, which is converted to failure in Prolog.) For more on this, see section 1.6.4, and for handling failure, see section 1.13.1.

For PL_*() functions that take or return char* or wchar_t* values, there are also wrapper functions and methods that use std::string or std::wstring. Because these copy the values, there is usually no need to enclose the calls with PlStringBuffers (which wraps PL_STRING_MARK() and PL_STRING_RELEASE()). See also the rationale for string: section 1.8.2.

Many of the classes (PlAtom, PlTerm, etc.) are thin wrappers around the C interface's types (atom_t, term_t, etc.). As such, they inherit the concept of “null” from these types (which is abstracted as PlAtom::null, PlTerm::null, etc., which typically is equivalent to 0). Normally, you shouldn't need to check whether the object is “fully created” , for the rare situations where a check is needed, the methods is_null() and not_null() are provided.

Most of the classes have constructors that create a “complete” object. For example, 

PlAtom foo("foo");

will ensure that the object foo is useable and will throw an exception if the atom can't be created. However, if you choose to create a PlAtom object from an atom_t value, no checking is done (similarly, no checking is done if you create a PlTerm object from a term_t value).

In many situations, you will be using a term; for these, there are special constructors. For example: 

PlTerm_atom foo("foo"); // Same as PlTerm(PlAtom("foo"))
PlTerm_string str("a string");

To help avoid programming errors, some of the classes do not have a default “empty” constructor. For example, if you with to create a PlAtom that is uninitialized, you must explicitly use PlAtom(PlAtom::null). This make some code a bit more cumbersome because you can't omit the default constructors in struct initalizers.

Many of the classes have an as_string() method7This might be changed in future to to_string(), to be consistent with std::to_string(), which is useful for debugging.

The method names such as as_int32_t() were chosen itnstead of to_int32_t() because they imply that the representation is already an int32_t, and not that the value is converted to a int32_t. That is, if the value is a float, int32_t will fail with an error rather than (for example) truncating the floating point value to fit into a 32-bit integer.

Many of the classes wrap long-lived items, such as atoms, functors, predicates, or modules. For these, it's often a good idea to define them as static variables that get created at load time, so that a lookup for each use isn't needed (atoms are unique, so PlAtom("foo") requires a lookup for an atom foo and creates one if it isn't found).

C code sometimes creates objects “lazily” on first use: 

void my_function(...)
{ static atom_t ATOM_foo = 0;
   ...
  if ( ! foo  )
     foo = PL_new_atom("foo");
   ...
}

For C++, this can be done in a simpler way, because C++ will call a local “static” constructor on first use. 

void my_function(...)
{ static PlAtom ATOM_foo("foo");
}

The class PlTerm (which wraps term_t) is the most used. Although a PlTerm object can be created from a term_t value, it is intended to be used with a constructor that gives it an initial value. The default constructor calls PL_new_term_ref() and throws an exception if this fails. The various constructors are described in section 1.6.6. Note that the default constructor is not public; to create a “variable” term, you should use the subclass constructor PlTerm_var().

1.6.2 Summary of files

The following files are provided:

1.6.3 Summary of classes

The list below summarises the classes defined in the C++ interface.

PlTerm
Generic Prolog term that wraps term_t (for more details on term_t, see Interface Data Types).

This is a “base class” whose constructor is protected; subclasses specify the actual contents. Additional methods allow checking the Prolog type, unification, comparison, conversion to native C++-data types, etc. See section 1.11.1.

For more details about PlTerm, see section 1.6.6

PlCompound
Subclass of PlTerm with constructors for building compound terms. If there is a single string argument, then PL_chars_to_term() or PL_wchars_to_term() is used to parse the string and create the term. If the constructor has two arguments, the first is name of a functor and the second is a PlTermv with the arguments.
PlTermv
Vector of Prolog terms. See PL_new_term_refs(). The [] operator is overloaded to access elements in this vector. PlTermv is used to build complex terms and provide argument-lists to Prolog goals.
PlAtom
Wraps atom_t in their internal Prolog representation for fast comparison. (For more details on atom_t, see Interface Data Types). For more details of PlAtom, see section 1.11.12.4.
PlFunctor
A wrapper for functor_t, which maps to the internal representation of a name/arity pair.
PlPredicate
A wrapper for predicate_t, which maps to the internal representation of a Prolog predicate.
PlModule
A wrapper for module_t, which maps to the internal representation of a Prolog module.
PlQuery
Represents opening and enumerating the solutions to a Prolog query.
PlException
If a call to Prolog results in an error, the C++ interface converts the error into a PlException object and throws it. If the enclosing code doesn't intercept the exception, the PlException object is turned back into a Prolog error when control returns to Prolog from the PREDICATE() macros. This is a subclass of PlExceptionBase, which is a subclass of std::exception.
PlFrame
This utility-class can be used to discard unused term-references as well as to do data-backtracking.
PlEngine
This class is used in embedded applications (applications where the main control is held in C++). It provides creation and destruction of the Prolog environment.
PlRegister
Encapsulates PL_register_foreign() to allow using C++ global constructors for registering foreign predicates.
PlFail
Can be thrown to short-circuit processing and return failure to Prolog. Performance-critical code should use return false instead if failure is expected. An error can be signaled by calling Plx_raise_exception() or one of the PL_*_error() functions and then throwing PlFail; but it's better style to create the error throwing one of the subclasses of PlException e.g., throw PlTypeError("int", t). Subclass of PlExceptionFailBase.
PlExceptionFail
In some situations, a Prolog error cannot be turned into a PlException object, so a PlExceptionFail object is thrown. This is turned into failure by the PREDICATE() macro, resulting in normal Prolog error handling. Subclass of PlExceptionFailBase.
PlExceptionBase
A “do nothing” subclass of std::exception, to allow catching PlException, PlExceptionFail or PlFail in a single “catch” clause.
PlExceptionFailBase
A “do nothing” subclass of PlExceptionBase, to allow catching PlExceptionFail or PlFail in a single “catch” clause, excluding PlException.

1.6.4 Wrapper functions

The various PL_*() functions in SWI-Prolog.h have corresponding Plx_*() functions, defined in SWI-cpp2-plx.h, which is always included by SWI-cpp2.h. There are three kinds of wrappers, with the appropriate one being chosen according to the semantics of the wrapped function:

A few PL_*() functions do not have a corresponding Plx*() function because they do not fit into one of these categories. For example, PL_next_solution() has multiple return values (PL_S_EXCEPTION, PL_S_LAST, etc.) if the query was opened with the PL_Q_EXT_STATUS flag.

Most of the PL_*() functions whose first argument is of type term_t, atom_t, etc. have corresponding methods in classes PlTerm, PlAtom, etc.

Important: You should use the Plx_*() wrappers only in the context of a PREDICATE() call, which will handle any C++ exceptions. Some blob callbacks can also handle an exception (see section 1.6.8). Everywhere else, the result of calling a Plx_*() function is unpredicatable - probably a crash.

1.6.5 Naming conventions, utility functions and methods

See also the discussion on design philosophy in section 1.6.1.

The classes all have names starting with “Pl” , using CamelCase; this contrasts with the C functions that start with “PL_” and use underscores.

The wrapper classes (PlFunctor, PlAtom, PlTerm), etc. all contain a field C_ that contains the wrapped value (functor_t, atom_t, term_t respectively). If this wrapped value is needed, it should be accessed using the unwrap() or unwrap_as_ptr() methods.

In some cases, it's natural to use a pointer to a wrapper class. For those, the function PlUnwrapAsPtr() returns nullptr if the pointer is null; otherwise it returns the wrapped value (which itself might be some kind of “null” ).

The wrapper classes, which subclass WrappedC<...>, all define the following methods and constants:

The method unwrap() can be used to access the C_ field, and can be used wherever a atom_t or term_t is used. For example, the PL_scan_options() example code can be written as follows. Note the use of &callback.unwrap() to pass a pointer to the wrapped term_t value. 

PREDICATE(mypred, 2)
{ auto options = A2;
  int        quoted = false;
  size_t     length = 10;
  PlTerm_var callback;

  PlCheckFail(PL_scan_options(options, 0, "mypred_options", mypred_options,
                              &quoted, &length, &callback.unwrap()));
  callback.record(); // Needed if callback is put in a blob that Prolog doesn't know about.
                     // If it were an atom (OPT_ATOM): register_ref().

  <implement mypred>
}

For functions in SWI-Prolog.h that don't have a C++ equivalent in SWI-cpp2.h, PlCheckFail() is a convenience function that checks the return code and throws a PlFail exception on failure or PlException if there was an exception. The enclosing PREDICATE() code catches PlFail exceptions and converts them to the foreign_t return code for failure. If the failure from the C function was due to an exception (e.g., unification failed because of an out-of-memory condition), the foreign function caller will detect that situation and convert the failure to an exception.

The “getter” methods for PlTerm all throw an exception if the term isn't of the expected Prolog type. The “getter” methods typically start with “as” , e.g. PlTerm::as_string(). There are also other “getter” methods, such as PlTerm::get_float_ex() that wrap PL_*() functions.

“getters” for integers have an additional problem, in that C++ doesn't define the sizes of int, long, or size_t. It seems to be impossible to make an overloaded method that works for all the various combinations of integer types on all compilers, so there are specific methods for int64_t, uint64_t, size_t.

In some cases,it is possible to overload methods; for example, this allows the following code without knowing the exact definition of size_t: 

PREDICATE(p, 1)
{ size_t sz;
  A1.integer(&sz);
     ...
}

It is strongly recommended that you enable conversion checking. For example, with GNU C++, use these options (possibly with -Werror): -Wconversion -Warith-conversion -Wsign-conversion -Wfloat-conversion.

There is an additional problem with characters - C promotes them to int but C++ doesn't. In general, this shouldn't cause any problems, but care must be used with the various getters for integers.

1.6.6 PlTerm class

As we have seen from the examples, the PlTerm class plays a central role in conversion and operating on Prolog data. This section provides complete documentation of this class.

There are a number of subclasses that exist only to provide a safe way of constructing at term. There is also a subclass (PlTermScoped) that helps reclaim terms.

Most of the PlTerm constructors are defined as subclasses of PlTerm, with a name that reflects the Prolog type of what is being created (e.g., PlTerm_atom creates a term from an atom; PlTerm_string creates a term from a Prolog string). This is done to ensure that the there is no ambiguity in the constructors - for example, there is no way to distinguish between term_t, atom_t, and ordinary integers, so there are constructors PlTerm(), PlTerm_atom(), and PlTerm_integer. All of the constructors are “explicit” because implicit creation of PlTerm objects can lead to subtle and difficult to debug errors.

If a constructor fails (e.g., out of memory), a PlException is thrown. The class and subclass constructors are as follows.

PlTerm :: PlTerm(PlAtom a)
Creates a term reference containing an atom, using PL_put_atom(). It is the same as PlTerm_atom().
PlTerm :: PlTerm(term_t t)
Creates a term reference from a C term (by wrapping it). As this is a lightweight class, this is a no-op in the generated code.
PlTerm :: PlTerm(PlRecord r)
Creates a term reference from a record, using PL_recorded().
PlTerm_atom :: PlTerm_atom(atom_t a)
Creates a term reference containing an atom.
PlTerm_atom :: PlTerm_atom(PlAtom a)
Creates a term reference containing an atom.
PlTerm_atom :: PlTerm_atom(const char *text)
Creates a term reference containing an atom, after creating the atom from the text.
PlTerm_atom :: PlTerm_atom(const wchar_t *text)
Creates a term reference containing an atom, after creating the atom from the text.
PlTerm_atom :: PlTerm_atom(const std::string& text)
Creates a term reference containing an atom, after creating the atom from the text.
PlTerm_atom :: PlTerm_atom(const std::wstring& text)
Creates a term reference containing an atom, after creating the atom from the text.
PlTerm_var :: PlTerm_var()
Creates a term reference for an uninstantiated variable. Typically this term is then unified with another object.
PlTerm_term_t :: PlTerm_term_t()
Creates a term reference from a C term_t. This is a lightweight class, so no code is generated.
PlTerm_integer :: PlTerm_integer()
Subclass of PlTerm with constructors for building a term that contains a Prolog integer from a long.9PL_put_integer() takes a long argument.
PlTerm_int64 :: PlTerm_int64()
Subclass of PlTerm with constructors for building a term that contains a Prolog integer from a int64_t.
PlTerm_uint64 :: PlTerm_uint64()
Subclass of PlTerm with constructors for building a term that contains a Prolog integer from a uint64_t.
PlTerm_size_t :: PlTerm_size_t()
Subclass of PlTerm with constructors for building a term that contains a Prolog integer from a size_t.
PlTerm_float :: PlTerm_float()
Subclass of PlTerm with constructors for building a term that contains a Prolog float.
PlTerm_pointer :: PlTerm_pointer()
Subclass of PlTerm with constructors for building a term that contains a raw pointer. This is mainly for backwards compatibility; new code should use blobs. A pointer is represented in Prolog as a mangled integer. The mangling is designed to make most pointers fit into a 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 void *. 
PREDICATE(make_my_object, 1)
{ auto myobj = new MyClass();
  return A1.unify_pointer(myobj);
}

PREDICATE(my_object_contents, 2)
{ auto myobj = static_cast<MyClass*>(A1.as_pointer());
  return A2.unify_string(myobj->contents);
}

PREDICATE(free_my_object, 1)
{ auto myobj = static_cast<MyClass*>(A1.as_pointer());
  delete myobj;
  return true;
}
PlTerm_string :: PlTerm_string()
Subclass of PlTerm with constructors for building a term that contains a Prolog string object. For constructing a term from the text form, see PlCompound.
PlTerm_list_codes :: PlTerm_list_codes()
Subclass of PlTerm with constructors for building Prolog lists of character integer values.
PlTerm_chars :: PlTerm_chars()
Subclass of PlTerm with constructors for building Prolog lists of one-character atoms (as atom_chars/2).
PlTerm_tail :: PlTerm_tail()
SubClass of PlTerm for building and analysing Prolog lists.

The methods are:

bool PlTerm::get_atom(PlAtom* a)
Wrapper of PL_get_atom(), throwing an exception on Prolog error.
bool PlTerm::get_bool(int* value)
Wrapper of PL_get_bool(), throwing an exception on Prolog error.
chars PlTerm::get_chars(char**s, unsigned int flags)
Wrapper of PL_get_chars(), throwing an exception on Prolog error.
chars PlTerm::get_list_chars(char**s, unsigned int flags)
Wrapper of PL_get_list_chars(), throwing an exception on Prolog error.
bool PlTerm::get_list_chars(char **s, unsigned int flags)
Wrappper of PL_get_list_chars(), throwing an exception on Prolog error.
bool PlTerm::get_atom_nchars(size_t *len, char **a)
Wrappper of PL_get_atom_nchars(), throwing an exception on Prolog error.
bool PlTerm::get_list_nchars(size_t *len, char **s, unsigned int flags)
Wrappper of PL_get_list_nchars(), throwing an exception on Prolog error.
bool PlTerm::get_nchars(size_t *len, char **s, unsigned int flags)
Wrappper of PL_get_nchars(), throwing an exception on Prolog error. Deprecated: see PlTerm::get_nchars(flags) that returns a std::string. If you use this, be sure to wrap it with PlStringBuffers, and if you use the BUF_MALLOC flag, you can use std::unique_ptr<char, decltype(&PL_free)> to manage the pointer.
bool PlTerm::get_wchars(size_t *length, pl_wchar_t **s, unsigned flags)
Wrappper of PL_get_wchars(), throwing an exception on Prolog error. Deprecated: see PlTerm::getwchars(flags) that returns a std::wstring. If you use this, be sure to wrap it with PlStringBuffers, and if you use the BUF_MALLOC flag, you can use std::unique_ptr<char, decltype(&PL_close)> to manage the pointer.
bool PlTerm::get_integer(int *i)
Wrappper of PL_get_integer(), throwing an exception on Prolog error.
bool PlTerm::get_long(long *i)
Wrappper of PL_get_long(), throwing an exception on Prolog error.
bool PlTerm::get_intptr(intptr_t *i)
Wrappper of PL_get_intptr(), throwing an exception on Prolog error.
bool PlTerm::get_pointer(void **ptr)
Wrappper of PL_get_pointer(), throwing an exception on Prolog error.
bool PlTerm::get_float(double *f)
Wrapper Plx_get_float(), throwing an exception on Prolog error.
bool PlTerm::get_functor(PlFunctor *f)
Wrappper of PL_get_functor(), throwing an exception on Prolog error.
bool PlTerm::get_name_arity(PlAtom *name, size_t *arity)
Wrappper of PL_get_name_arity(), throwing an exception on Prolog error.
bool PlTerm::get_compound_name_arity(PlAtom *name, size_t *arity)
Wrappper of PL_get_compound_name_arity(), throwing an exception on Prolog error.
bool PlTerm::get_module(PlModule *module)
Wrappper of PL_get_module(), throwing an exception on Prolog error.
bool PlTerm::get_arg(size_t index, PlTerm a)
Wrappper of PL_get_arg(index,), throwing an exception on Prolog error.
bool PlTerm::get_dict_key(PlAtom key, PlTerm dict, PlTerm value)
Wrappper of PL_get_dict_key(key.), throwing an exception on Prolog error.
bool PlTerm::get_list(PlTerm h, PlTerm t)
Wrappper of PL_get_list(), throwing an exception on Prolog error.
bool PlTerm::get_head(PlTerm h)
Wrappper of PL_get_head(), throwing an exception on Prolog error.
bool PlTerm::get_tail(PlTerm t)
Wrappper of PL_get_tail(), throwing an exception on Prolog error.
bool PlTerm::get_nil()
Wrappper of PL_get_nil(), throwing an exception on Prolog error.
bool PlTerm::get_blob(void **blob, size_t *len, PL_blob_t **type)
Wrappper of PL_get_blob(), throwing an exception on Prolog error.
bool PlTerm::get_file_name(char **name, int flags)
Wrappper of PL_get_file_name() (does not throw a C++ exception).
bool PlTerm::get_file_nameW(wchar_t **name, int flags)
Wrappper of PL_get_file_nameW(), (does not throw a C++ exception).
std::string PlTerm::get_file_name(char **name, int flags)
Wrapper of PL_get_file_name(), ignoring PL_FILE_NOERRORS - throws PlFail on failure, which is interpreted by the enclosing PREDICATE as either failure or an error, depending on the flag bit PL_FILE_NOERRORS.
std::wstring PlTerm::get_file_nameW(int flags)
Same as PlTerm::get_file_name(), but returns a wide-character string.
bool PlTerm::get_attr(term_t a)
Wrappper of PL_get_attr(), throwing an exception on Prolog error.
void PlTerm::get_atom_ex(PlAtom *a)
Wrapper of PL_get_atom_ex(), throwing an exception on Prolog error.
void PlTerm::get_integer_ex(int *i)
Wrapper of PL_get_integer_ex(), throwing an exception on Prolog error.
void PlTerm::get_long_ex(long *i)
Wrapper of PL_get_long_ex(), throwing an exception on Prolog error.
void PlTerm::get_int64_ex(int64_t *i)
Wrapper of PL_get_int64_ex(), throwing an exception on Prolog error.
void PlTerm::get_uint64_ex(uint64_t *i)
Wrapper of PL_get_uint64_ex(), throwing an exception on Prolog error.
void PlTerm::get_intptr_ex(intptr_t *i)
Wrapper of PL_get_intptr_ex(), throwing an exception on Prolog error.
void PlTerm::get_size_ex(size_t *i)
Wrapper of PL_get_size_ex(), throwing an exception on Prolog error.
void PlTerm::get_bool_ex(int *i)
Wrapper of PL_get_bool_ex(), throwing an exception on Prolog error.
void PlTerm::get_float_ex(double *f)
Wrapper of PL_get_float_ex(), throwing an exception on Prolog error.
void PlTerm::get_char_ex(int *p, int eof)
Wrapper of PL_get_char_ex(), throwing an exception on Prolog error.
void PlTerm::unify_bool_ex(int val)
Wrapper of PL_unify_bool_ex(), throwing an exception on Prolog error.
void PlTerm::get_pointer_ex(void **addrp)
Wrapper of PL_get_pointer_ex(), throwing an exception on Prolog error.
bool PlTerm::unify_list_ex(PlTerm h, PlTerm t)
Wrappper of PL_unify_list_ex(), throwing an exception on Prolog error.
void PlTerm::unify_nil_ex()
Wrapper of PL_unify_nil_ex(), throwing an exception on Prolog error.
bool PlTerm::get_list_ex(PlTerm h, PlTerm t)
Wrappper of PL_get_list_ex(), throwing an exception on Prolog error.
void PlTerm::get_nil_ex()
Wrapper of PL_get_nil_ex(), throwing an exception on Prolog error.
int PlTerm::type()
Wrapper of PL_term_type(unwrap()), returning PL_VARIABLE, PL_ATOM, etc, throwing an exception on Prolog error. bo
ol PlTerm::is_attvar()
Wrappper of PL_is_attvar(), throwing an exception on Prolog error.
bool PlTerm::is_variable()
Wrappper of PL_is_variable(), throwing an exception on Prolog error.
bool PlTerm::is_ground()
Wrappper of PL_is_ground(), throwing an exception on Prolog error.
bool PlTerm::is_atom()
Wrappper of PL_is_atom(), throwing an exception on Prolog error.
bool PlTerm::is_integer()
Wrappper of PL_is_integer(), throwing an exception on Prolog error.
bool PlTerm::is_string()
Wrappper of PL_is_string(), throwing an exception on Prolog error.
bool PlTerm::is_atom_or_string()
is_atom() or is_string().
bool PlTerm::is_float()
Wrappper of PL_is_float(), throwing an exception on Prolog error.
bool PlTerm::is_rational()
Wrappper of PL_is_rational(), throwing an exception on Prolog error.
bool PlTerm::is_compound()
Wrappper of PL_is_compound(), throwing an exception on Prolog error.
bool PlTerm::is_callable()
Wrappper of PL_is_callable(), throwing an exception on Prolog error.
bool PlTerm::is_list()
Wrappper of PL_is_list(), throwing an exception on Prolog error.
bool PlTerm::is_dict()
Wrappper of PL_is_dict(), throwing an exception on Prolog error.
bool PlTerm::is_pair()
Wrappper of PL_is_pair(), throwing an exception on Prolog error.
bool PlTerm::is_atomic()
Wrappper of PL_is_atomic(), throwing an exception on Prolog error.
bool PlTerm::is_number()
Wrappper of PL_is_number(), throwing an exception on Prolog error.
bool PlTerm::is_acyclic()
Wrappper of PL_is_acyclic(), throwing an exception on Prolog error.
bool PlTerm::is_functor(PlFunctor f)
Wrappper of PL_is_functor(), throwing an exception on Prolog error.
bool PlTerm::is_blob(PL_blob_t **type)
Wrappper of PL_is_blob(), throwing an exception on Prolog error.
void PlTerm::must_be_attvar()
Throw PlTypeError if PlTerm::is_attvar() fails.
void PlTerm::must_be_variable()
Throw PlTypeError if PlTerm::is_variable() fails.
void PlTerm::must_be_ground()
Throw PlTypeError if PlTerm::is_ground() fails.
void PlTerm::must_be_atom()
Throw PlTypeError if PlTerm::is_atom() fails.
void PlTerm::must_be_integer()
Throw PlTypeError if PlTerm::is_integer() fails.
void PlTerm::must_be_string()
Throw PlTypeError if PlTerm::is_string() fails.
void PlTerm::must_be_atom_or_string()
Throw PlTypeError if PlTerm::is_atom_or_string() fails.
void PlTerm::must_be_float()
Throw PlTypeError if PlTerm::is_float() fails.
void PlTerm::must_be_rational()
Throw PlTypeError if PlTerm::is_rational() fails.
void PlTerm::must_be_compound()
Throw PlTypeError if PlTerm::is_compound() fails.
void PlTerm::must_be_callable()
Throw PlTypeError if PlTerm::is_callable() fails.
void PlTerm::must_be_list()
Throw PlTypeError if PlTerm::is_list() fails.
void PlTerm::must_be_dict()
Throw PlTypeError if PlTerm::is_dict() fails.
void PlTerm::must_be_pair()
Throw PlTypeError if PlTerm::is_pair() fails.
void PlTerm::must_be_atomic()
Throw PlTypeError if PlTerm::is_atomic() fails.
void PlTerm::must_be_number()
Throw PlTypeError if PlTerm::is_number() fails.
void PlTerm::must_be_acyclic()
Throw PlTypeError if PlTerm::is_acyclic() fails.
void PlTerm::put_variable()
Wrapper of PL_put_variable(), throwing an exception on Prolog error.
void PlTerm::put_atom(PlAtom a)
Wrapper of PL_put_atom(), throwing an exception on Prolog error.
void PlTerm::put_bool(int val)
Wrapper of PL_put_bool(), throwing an exception on Prolog error.
void PlTerm::put_atom_chars(const char *chars)
Wrapper of PL_put_atom_chars(), throwing an exception on Prolog error.
void PlTerm::put_string_chars(const char *chars)
Wrapper of PL_put_string_chars(), throwing an exception on Prolog error.
void PlTerm::put_chars(int flags, size_t len, const char *chars)
Wrapper of PL_put_chars(), throwing an exception on Prolog error.
void PlTerm::put_list_chars(const char *chars)
Wrapper of PL_put_list_chars(), throwing an exception on Prolog error.
void PlTerm::put_list_codes(const char *chars)
Wrapper of PL_put_list_codes(), throwing an exception on Prolog error.
void PlTerm::put_atom_nchars(size_t l, const char *chars)
Wrapper of PL_put_atom_nchars(), throwing an exception on Prolog error.
void PlTerm::put_string_nchars(size_t len, const char *chars)
Wrapper of PL_put_string_nchars(), throwing an exception on Prolog error.
void PlTerm::put_list_nchars(size_t l, const char *chars)
Wrapper of PL_put_list_nchars(), throwing an exception on Prolog error.
void PlTerm::put_list_ncodes(size_t l, const char *chars)
Wrapper of PL_put_list_ncodes(), throwing an exception on Prolog error.
void PlTerm::put_integer(long i)
Wrapper of PL_put_integer(), throwing an exception on Prolog error.
void PlTerm::put_pointer(void *ptr)
Wrapper of PL_put_pointer(), throwing an exception on Prolog error.
void PlTerm::put_float(double f)
Wrapper of PL_put_float(), throwing an exception on Prolog error.
void PlTerm::put_functor(PlFunctor functor)
Wrapper of PL_put_functor(), throwing an exception on Prolog error.
void PlTerm::put_list()
Wrapper of PL_put_list(), throwing an exception on Prolog error.
void PlTerm::put_nil()
Wrapper of PL_put_nil(), throwing an exception on Prolog error.
void PlTerm::put_term(PlTerm t2)
Wrapper of PL_put_term(), throwing an exception on Prolog error.
void PlTerm::put_blob(void *blob, size_t len, PL_blob_t *type)
Wrapper of PL_put_blob(), throwing an exception on Prolog error.
PlRecord PlTerm::record()
Returns a PlRecord constructed from the term. Same as PlRecord(*this).
void PlTerm::integer(bool *v)
Wrapper of PL_cvt_i_bool().
void PlTerm::integer(char *v)
Wrapper of PL_cvt_i_char().
void PlTerm::integer(int *v)
Wrapper of PL_cvt_i_int().
void PlTerm::integer(long *v)
Wrapper of PL_cvt_i_long().
void PlTerm::integer(long long *v)
Wrapper of PL_cvt_i_llong().
void PlTerm::integer(short *v)
Wrapper of PL_cvt_i_short().
void PlTerm::integer(signed char *v)
Wrapper of PL_cvt_i_schar().
void PlTerm::integer(unsigned char *v)
Wrapper of PL_cvt_i_uchar().
void PlTerm::integer(unsigned int *v)
Wrapper of PL_cvt_i_uint().
void PlTerm::integer(unsigned long *v)
Wrapper of PL_cvt_i_ulong().
void PlTerm::integer(unsigned long long *v)
Wrapper of PL_cvt_i_ullong().
void PlTerm::integer(unsigned short *v)
Wrapper of PL_cvt_i_ushort().
const std::string PlTerm::as_string(PlEncoding enc=ENC_OUTPUT)
Calls PlTerm::get_nchars(CVT_ALL|CVT_WRITEQ|CVT_EXCEPTION). This method is provided mainly for debugging. The definition is subject to change in future - if you want precise control, use PlTerm::get_nchars().
const std::wstring PlTerm::as_wstring()
Calls PlTerm::get_wchars(CVT_ALL|CVT_WRITEQ|CVT_EXCEPTION). This method is provided mainly for debugging. The definition is subject to change in future - if you want precise control, use PlTerm::get_nchars().
long PlTerm::as_long()
Wrapper of PL_cvt_i_*().
int32_t PlTerm::as_int32_t()
Wrapper of PL_cvt_i_*().
uint32_t PlTerm::as_uint32_t()
Wrapper of PL_cvt_i_*().
uint64_t PlTerm::as_uint64_t()
Wrapper of PL_cvt_i_*().
int64_t PlTerm::as_int64_t()
Wrapper of PL_cvt_i_*().
size_t PlTerm::as_size_t()
Wrapper of PL_cvt_i_*().
int PlTerm::as_int()
Wrapper of PL_cvt_i_*().
unsigned PlTerm::as_uint()
Wrapper of PL_cvt_i_*().
unsigned long PlTerm::as_ulong()
Wrapper of PL_cvt_i_*().
bool PlTerm::as_bool()
Wrapper of PL_cvt_i_*().
void PlTerm::as_nil()
Wrapper of PL_get_nil_ex(), throwing an exception if the term isn't “nil” .
double PlTerm::as_float()
Wrapper of PL_get_float_ex(), throwing an exception if the term isn't a float.
double PlTerm::as_double()
Wrapper of PL_get_float_ex(), throwing an exception if the term isn't a float.
void * PlTerm::as_pointer()
(Deprecated: should use blob API). Wrapper of PL_get_pointer_ex(), throwing an exception if the term isn't a blob.
const std::string PlTerm::get_nchars(unsigned int flags)
Calls PL_get_nchars(..., flags) and converts the result to a std::string. The flags BUF_MALLOC, BUF_STACK, and BUF_ALLOW_STACK are ignored and replaced by BUF_DISCARDABLE.
const std::wstring PlTerm::get_wchars(unsigned int flags)
Calls PL_get_wchars(..., flags) and converts the result to a std::wstring. The flags BUF_MALLOC, BUF_STACK, and BUF_ALLOW_STACK are ignored and replaced by BUF_DISCARDABLE.
PlAtom PlTerm::as_atom()
Wrapper of PL_get_atom_ex(), throwing an exception if the term is not an atom.
bool PlTerm::eq_if_atom(PlAtom a)
Returns true if the term is an atom and equal to a.
PlTerm::operator[] size_t index(W)
rapper for PL_get_arg(), throwing an exception if the term isn't a compound or the index is out of range.
size_t PlTerm::arity()
Gets the arity of the term; throws PlTypeError if not a "compound" or atom.
PlAtom PlTerm::name()
Gets the name of the term; PlTypeError if not a "compound" or atom.
bool name_arity(PlAtom *name, size_t *arity)
Wrapper of PL_get_name_arity(); name and/or arity can be nullptr. Returns false if the term isn't a compound or atom.
PlTerm PlTerm::copy_term_ref()
Wrapper of PL_copy_term_ref(). Throws an exception error (e.g., PlResourceError).
void PlTerm::free_term_ref()
Wrapper of PL_free_term_ref(). Is safe to use if the object wraps PlTerm::null. Does not reset the wrapped term. This is used implicitly in PlTermScoped’s destructor, which does reset the wrapped term.
void PlTerm::free_term_ref_reset()
Same as PlTerm::free_term_ref() plus PlTerm::reset(). PlTermScoped’s destructor, which does reset the wrapped term.
bool nify_term(PlTerm t2)
Wrapper of PL_unify(). Throws an exception on error and returns false if unification fails. If on failure, there isn't an immediate return to Prolog (e.g., by wrapping the call with PlCheckFail()), this method should be called within the context of PlFrame, and PlFrame::rewind() should be called.
bool PlTerm::unify_atom(PlAtom a)
Wrapper of PL_unify_atom(), throwing an exception on error.
bool PlTerm::unify_chars(int flags, size_t len, const char *s)
Wrapper of PL_unify_chars(), throwing an exception on error.
bool PlTerm::unify_chars(int flags, const std::string& s)
Wrapper of PL_unify_chars(), throwing an exception on error.
bool PlTerm::unify_atom(const char* v)
Wrapper of PL_unify_atom_chars(), throwing an exception on error.
bool PlTerm::unify_atom(const wchar_t* v)
Wrapper of PL_unify_wchars(), throwing an exception on error.
bool PlTerm::unify_atom(const std::string& v)
Wrapper of PL_unify_atom_nchars(), throwing an exception on error.
bool PlTerm::unify_atom(const std::wstring& v)
Wrapper of PL_unify_wchars(), throwing an exception on error. cfunctionboolPlTerm::unify_integerbool v Wrapper of PL_unify_int64(), throwing an exception on error.
bool PlTerm::unify_integer(char v)
Wrapper of PL_unify_int64(), throwing an exception on error.
bool PlTerm::unify_integer(int v)
Wrapper of PL_unify_int64(), throwing an exception on error.
bool PlTerm::unify_integer(long v)
Wrapper of PL_unify_int64(), throwing an exception on error.
bool PlTerm::unify_integer(long long v)
Wrapper of PL_unify_int64(), throwing an exception on error.
bool PlTerm::unify_integer(short v)
Wrapper of PL_unify_int64(), throwing an exception on error.
bool PlTerm::unify_integer(signed char v)
Wrapper of PL_unify_int64(), throwing an exception on error.
bool PlTerm::unify_integer(unsigned char v)
Wrapper of PL_unify_uint64(), throwing an exception on error.
bool PlTerm::unify_integer(unsigned int v)
Wrapper of PL_unify_uint64(), throwing an exception on error.
bool PlTerm::unify_integer(unsigned long v)
Wrapper of PL_unify_uint64(), throwing an exception on error.
bool PlTerm::unify_integer(unsigned long long v)
Wrapper of PL_unify_uint64(), throwing an exception on error.
bool PlTerm::unify_integer(unsigned short v)
Wrapper of PL_unify_uint64(), throwing an exception on error.
bool PlTerm::unify_float(double v)
Wrapper of PL_unify_float(), throwing an exception on error.
bool PlTerm::unify_string(const std::string& v)
Wrapper of PL_unify_string_nchars(), throwing an exception on error.
bool PlTerm::unify_string(const std::wstring& v)
Wrapper of PL_unify_wchars(), throwing an exception on error.
bool PlTerm::unify_functor(PlFunctor f)
Wrapper of PL_unify_functor(), throwing an exception on error.
bool PlTerm::unify_pointer(void *ptr)
Wrapper of PL_unify_pointer(), throwing an exception on error. An alternative to this is to use a blob that wraps a pointer - see section 1.6.8.7.
bool PlTerm::unify_nil()
Wrapper of PL_unify_nil(), throwing an exception on error.
bool PlTerm::unify_list(PlTerm h, PlTerm t)
Wrapper of PL_unify_list(), throwing an exception on error.
bool PlTerm::unify_bool(bool val)
Wrapper of PL_unify_bool(), throwing an exception on error.
bool PlTerm::unify_blob(const PlBlob* blob)
Wrapper of PL_unify_blob(), throwing an exception on error.
bool PlTerm::unify_blob(const void *blob, size_t len, const PL_blob_t *type)
Wrapper of PL_unify_blob(), throwing an exception on error.
int PlTerm::compare(PlTerm t2)
Wrapper for PL_compare(), returning -1, 0, 1 for the result of standard order comparison of the term with a2.
bool operator ==(PlTerm t2)
compare(t2) == 0.
bool operator !=(PlTerm t2)
compare(t2) != 0.
bool operator <(PlTerm t2)
compare(t2) < 0.
bool operator >(PlTerm t2)
compare(t2) > 0.
bool operator <=(PlTerm t2)
compare(t2) <= 0.
bool operator >=(PlTerm t2)
compare(t2) >= 0.
int write(IOSTREAM *s, int precedence, int flags)
Wrapper for PL_write_term().
void reset_term_refs()
Wrapper for PL_reset_term_refs().
bool call(PlModule module)
Wrapper for PL_call(unwrap()); module defaults to “null” . Throws a C++ exception if there's a Prolog error, otherwise returns the success or failure of the call.

1.6.7 PlTermScoped class (experimental)

This class is experimental and subject to change.

Normally all term references in a scope are discarded together or all term references created after a specific one are reclaimed using PlTerm::reset_term_refs(). A PlTermScoped object is the same as a PlTerm object except that PL_free_term_ref() is called on its wrapped term when the object goes out of scope. This shrinks the current foreign frame if the term is the last one in the frame and otherwise it marks it for reuse.

Here is an example, where PlTermScoped is inside a for-loop. If PlTerm were used instead, the stack would grow by the number of items in the array; PlTermScoped ensures that stack doesn't grow.10Assuming that unify_atom_list() is called from a predicate implementation, if PlTerm were used instead of PlTermCopy, all the created terms would be discarded when the Prolog stack frame is unwound; the use of PlTermScoped reuses the terms in that stack frame. A slightly more effiicient way of preventing the Prolog stack from growing is to use PlTerm::put_term() to reuse a term reference; but that is more difficult to understand and also more error-prone. 

bool
unify_atom_list(const std::vector<std::string>& array, PlTerm list)
{ PlTermScoped tail(list); // calls PL_copy_term_ref() to copy `list`
  for( auto item : array )
  { PlTermScoped head; // var term
    PlCheckFail(tail.unify_list(head, tail));
    PlCheckFail(head.unify_chars(PL_ATOM, item));
  }
  return tail.unify_nil();
}

The design of PlTermScoped is modeled on std::unique_ptr11unique_ptr was originally called scoped_ptr in the Boost libraries, but the name was changed to contrast with std::shared_ptr, which is reference-counted. and uses move semantics to ensure safety.12Move semantics are a relatively new feature in C++ and can be a bit difficult to understand. Roughly speaking, a move is a copies the object and then calls its destructor, so that any further use of the object is an error. If an object defines move methods or constructors, it can optimize this operation, and also can catch certain kinds of errors at compile time.

A PlTermScoped object can be created either with or without a wrapped term - the PlTermScoped::reset() method sets (or nulls) the wrapped term. A PlTermScoped object cannot be copied or passed as a value to a function; the PlTermScoped::release() method returns the wrapped term and resets the PlTermScoped object so that any further use of the PlTermScoped object is an error.

As shown in the example above, PlTermScoped can be used instead of PlTerm, in places where a loop would otherwise cause the stack to grow. There are limitations on the operations that are allowed on a PlTermScoped object; in particular, a PlTermScoped object cannot be copied and cannot be implicitly converted to a Plterm.

The PlTermScoped constructors always create a new term ref, by calling either PL_new_term_ref() or PL_copy_term_ref(). If you try to copy or create a PlTermScoped object from another PlTermScoped object, you will get a compile-time error; you can set the value from a PlTerm object, which can be obtained by calling PlTermScoped::release().

The methods derived from the PL_put_*() and PL_cons_*() functions should not be used with a PlTermScoped object. If you need to use these, you can use PlTermScoped::get() to get a PlTerm, for which a put_*() method can be used.

To copy a PlTermScoped object or to pass it as a value in a function call, use the PlTermScoped::release() method or std::move(): 

  PlTermScoped ts(...);
  PlTerm t;

  // Copy to a PlTerm:
  t = ts.release(); // or: t = std::move(ts);

  // Pass as a value to a function:
  foo(ts.release()); // or: foo(std::move(ts);

  // Copy to a PlTermScoped:
  PlTermScoped ts2;
  ts2.reset(ts.release()); // or: ts2.reset(std::move(ts));

The methods are (in addition to, or overriding the methods in PlTerm):

PlTermScoped :: PlTermScoped()
- same as PlTermScoped(PlTerm::null).
PlTermScoped :: PlTermScoped(PlTerm t)
- set the value from t.copy_term_ref()
PlTermScoped :: PlTermScoped(term_t t)
- same as PlTermScoped(PlTerm(t)).
PlTermScoped :: PlTermScoped(PlTermScoped&& m)
- create a new wrapped object from m and reset m. This is typically used with std::move().
PlTermScoped& PlTermScoped::operator=(PlTermScoped&& m)
- copy m and reset it. This is typically used with std::move().
~ PlTermScoped()
- if the wrapped term not null, call PL_free_term_ref() on it.
PlTermScoped :: PlTermScoped(PlTermScoped& m)
- deleted method.
PlTermScoped& operator=(PlTermScoped& m)
- deleted method.
void PlTermScoped::reset()
- same as PlTermScoped::reset(PlTerm::null).
void PlTermScoped::reset(PlTerm src)
- sets the wrapped term from src. To set the wrapped term from a PlTermScoped, use PlTermScoped::release() to convert it to a PlTerm.
PlTerm PlTermScoped::get()
- convert the object to a PlTerm. This is typically used when calling a function that expects a PlTerm object and which will not call PlTerm::free_term_ref() on it.
PlTerm PlTermScoped::release()
- typically used in the context t2.reset(t.release()) to copy a PlTermScoped; this can also be written t2=std::move(t).
void PlTermScoped::swap(PlTermScoped& src)
- swap two PlTermScoped objects’wrapped terms.

1.6.8 Blobs

Nomenclature warning:

There are two different release() functions:

Disclaimer:

The blob API for C++ is not completely general, but is designed to make common use cases easy to write. For other use cases, the underlying C API can still be used. The use case is:

A Prolog blob consists of five parts:

For the PL_blob_t structure, the C++ API provides the PL_BLOB_DEFINITION(blob_class,blob_name) macro, which references a set of template functions that allow easily setting up the callbacks. The C interface allows more flexibility by allowing some of the callbacks to default; however, the C++ API for blobs provides suitable callbacks for all of them, using the PL_BLOB_DEFINITION() macro.

For the data, which is subclassed from PlBlob, the programmer defines the various fields, a constructor that initializes them, and a destructor. Optionally, override methods can be defined for one of more of the methods PlBlob::compare_fields(), PlBlob::write_fields(), PlBlob::save(), PlBlob::load(), PlBlob::pre_delete(). 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() callback 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() callback that assumes that the blob was created using PL_BLOB_NOCOPY and manages memory using a std::unique_ptr.15This release() function has nothing to do with std::unique_ptr::release(). More details on this are in section 1.6.8.1.

The C blob interface has a flag that determines how memory is managed: PL_BLOB_NOCOPY. The PL_BLOB_DEFINITION() macro sets this, so Prolog will call the C++ destructor when the blob is garbage collected. (This call is done indirectly, using a callback that is registeered with Prolog.)

The C++ API for blobs only supports blobs with PL_BLOB_NOCOPY.16The API can probably also support blobs with PL_BLOB_UNIQUE, but there seems to be little point in setting this flag for non-text blobs.

1.6.8.1 A review of C++ features used by the API

Some slightly obscure features of C++ are used with PlBlob and ContextType, and can easily cause subtle bugs or memory leaks if not used carefully.

When a C++ object is created, its memory is allocated (either on the stack or on the heap using new), and the constructors are called in this order:

When the object is deleted (either by stack pop or the delete operator), the destructors are called in the reverse order.

There are special forms of the constructor for copying, moving, and assigning. The “copy constructor” has a signature Type(const Type& and is used when an object is created by copying, for example by assignment or passing the object on the stack in a function call. The “move constructor” has the signature Type(Type&& and is equivalent to the copy constructor for the new object followed by the destructor for the old object. (Assignment is usually allowed to default but can also be specified).

Currently, the copy and move constructors are not used, so it is best to explicitly mark them as not existing: 

Type(const Type&) = delete;
Type(Type&&) = delete;
Type& operator =(const Type&) = delete;
Type& operator =(Type&&) = delete;

A constructor may throw an exception - good programming style is to not leave a “half constructed” object but to throw an exception. Destructors are not allowed to throw exceptions,17because the destructor might be invoked by another exception, and C++ has no mechanism for dealing with a second exception. which complicates the API somewhat.

More details about constructors and destructors can be found in the FAQs for constructors and destructors.

Many classes or types have a constructor that simply assigns a default value (e.g., 0 for int) and the destructor does nothing. In particular, the destructor for a pointer does nothing, which can lead to memory leaks. To avoid memory leaks, the smart pointer std::unique_ptr18The name “unique” is to distinguish this from a “shared” pointer. A shared pointer can share ownership with multiple pointers and the pointed-to object is deleted only when all pointers to the object have been deleted. A unique pointer allows only a single pointer, so the pointed-to object is deleted when the unique pointer is deleted. can be used, whose destructor deletes its managed object. Note that std::unique_ptr does not enforce single ownership; it merely makes single ownership easy to manage and it detects most common mistakes, for example by not having copy constructor or assignment operator.

For example, in the following, the implicit destructor for p does nothing, so there will be a memory leak when a Ex1 object is deleted: 

class Ex1 {
public:
  Ex1() : p(new int) { }
  int *p;
};

To avoid a memory leak, the code could be changed to this: 

class Ex1 {
public:
  Ex1() p(new int) { }
  ~Ex1() { delete p; }
  int *p;
};

but it is easier to do the following, where the destructor for std::unique_ptr will free the memory: 

class Ex1 {
public:
  Ex1() p(new int) { }
  std::unique_ptr<int> p;
};

The same concept applies to objects that are created in code - if a C++ object is created using new, the programmer must manage when its destructor is called. In the following, if the call to data->validate() fails, there will be a memory leak: 

MyData *foo(int some_value) {
  MyData *data = new MyData(...);
  data->some_field = some_value;
  if (! data->validate() )
    throw std::runtime_error("Failed to validate data");
  return data;
}

Ths could fixed by adding delete data before throwing the runtime_error; but this doesn't handle the situation of data->validate() throwing an exception (which would require a catch/throw). Instead, it's easiser to use std::unique_ptr, which takes care of every return or exception path: 

MyData *foo(int some_value) {
  std::unique_ptr<MyData> data(new MyData(...));
  data->some_field = some_value;
  if (! data->validate() )
    throw std::runtime_error("Failed to validate data");
  return data.release(); // don't delete the new MyData
}

The destructor for std::unique_ptr will delete the data when it goes out of scope (in this case, by return or throw) unless the std::unique_ptr::release() method is called.19The call to unique_ptr<MYData>::release doesn't call the destructor; it can be called using std::unique_ptr::get_deleter().

In the code above, the throw will cause the unique_ptr’s destructor to be called, which will free the data; but the data will not be freed in the return statement because of the unique_ptr::release(). Using this style, a pointer to data on the heap can be managed as easily as data on the stack. The current C++ API for blobs takes advantage of this - in particular, there are two methods for unifying a blob:

unique_ptr allows specifying the delete function. For example, the following can be used to manage memory created with PL_malloc(): 

  std::unique_ptr<void, decltype(&PL_free)> ptr(PL_malloc(...), &PL_free);

or, when memory is allocated within a PL_*() function (in this case, using the Plx_*() wrapper for PL_get_nchars()): 

  size_t len;
  char *str = nullptr;
  Plx_get_nchars(t, &len, &str.get(), BUF_MALLOC|CVT_ALL|CVT_WRITEQ|CVT_VARIABLE|REP_UTF8|CVT_EXCEPTION);
  std::unique_ptr<char, decltype(&PL_free)> _str(str, &PL_free);

The current C++ API assumes that the C++ blob is allocated on the heap. If the programmer wishes to use the stack, they can use std::unique_ptr to automatically delete the object if an error is thrown - PlTerm::unify_blob(std::unique_ptr<PlBlob>*) prevents the automatic deletion if unification succeeds.

A unique_ptr needs a bit of care when it is passed as an argument. The unique_ptr::get() method can be used to get the “raw” pointer; the delete must not be used with this pointer. Or, the unique_ptr::release() method can be used to transfer ownership without calling the object's destructor.

Using unique_ptr::release() is a bit incovenient, so instead the unique_ptr can be passed as a pointer (or a reference). This does not create a new scope, so the pointer must be assigned to a local variable. For example, the code for unify_blob() is something like: 

bool PlTerm::unify_blob(std::unique_ptr<PlBlob>* b) const
{ std::unique_ptr<PlBlob> blob(std::move(*b));
  if ( !unify_blob(blob.get()) )
    return false;
  (void)blob.release();
  return true;
}

The line declaration for blob uses the “move constructor” to set the value of a newly scoped variable (std::move(*b) is a cast, so unique_ptr’s move constructor is used). This has the same effect as calling b->reset(), so from this point on, b has the value nullptr.

Alternatively, the local unique_ptr could be set by 

std::unique_ptr<PlBlob> blob(b->release());

or 

std::unique_ptr<PlBlob> blob;
blob.swap(*b);

If the call to PlTerm::unify_blob() fails or throws an exception, the virtual destructor for blob is called. Otherwise, the call to blob.release() prevents the destructor from being called - Prolog now owns the blob object and can call its destructor when the garbage collector reclaims it.

1.6.8.2 How to define a blob using C++

TL;DR: Use PL_BLOB_DEFINITION() to define the blob with the flag PL_BLOB_NOCOPY and the default PlBlob wrappers; define your struct as a subclass of PlBlob with no copy constructor, move constructor, or assignment operator; create a blob using std::unique_ptr<PlBlob>(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).

1.6.8.3 The life of a PlBlob

In this section, the blob is of type MyBlob, a subclass of PlBlob. (Example code is given in section 1.6.8.5) and section 1.6.8.7.

A blob is typically created by calling a predicate that does the following:

At this point, the blob is owned by Prolog and may be freed by its atom garbage collector, which will call the blob's destructor (if the blob shouldn't be deleted, it can override the the PlBlob::pre_delete() method to return false).

Whenever a predicate is called with the blob as an argument (e.g., as A1), the blob can be accessed by PlBlobv<MyBlob>::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 PlTerm_var.

When the atom garbage collector runs, it frees the blob by first calling the release() callback, which does 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 that 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.

1.6.8.4 C++ exceptions and blobs

When a blob is used in the context of a PREDICATE() macro, it can raise a C++ exception (PlFail or PlException) and the PREDICATE() code will convert the exception 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:

void PlBlob::acquire()
, which is called from PlBlobV<MyBlob>::acquire(), can throw a C++ exception. The programmer cannot override this.
int PlBlob::compare_fields(const PlBlob *_b)
, which is called from PlBlobV<MyBlob>::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.
bool PlBlob::write_fields(IOStream *s, int flags)
, which is called from PlBlobV<MyBlob>::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.
void PlBlob::PlBlob::save(IOStream *fd)
can throw a C++ exception, including PlFail().
PlAtom PlBlob::PlBlob::load(IOSTREAM *fd)
can throw a C++ exception, which is converted to a return value of PlAtom::null, which is interpreted by Prolog as failure.
bool PlBlob::PlBlob::pre_delete()
, which is called from PlBLobV<MyBLOB>::release(), can return false (or throw a PlException or PlExceptinFailBase, which will be interpreted as a return value of false), resulting in the blob not being garbage collected, and the destructor not being called. Note that this doesn't work well with final clean-up atom garbage collection, which disregards the return value and also doesn't respect the ordering of blob dependencies (e.g., if an iterator blob refers to a file-like blob, the file-like blob might be deleted before the iterator is deleted).

This code runs in the gc thread. The only PL_*() function that can safely be called are PL_unregister_atom() (which is what PlAtom::unregister_ref() calls).

1.6.8.5 Sample PlBlob code (connection to database)

Here is minimal sample code for creating a blob that owns a connection to a database. It has a single field (connection) and defines compare_fields() and write_fields().

A second sample code shows how to wrap a system pointer - section 1.6.8.7 

struct MyConnection
{ std::string name;

  explicit MyConnection();
  explicit MyConnection(const std::string& _name);
  bool open();
  bool close() noexcept;
  void portray(PlStream& strm) const;
};

struct MyBlob;

static PL_blob_t my_blob = PL_BLOB_DEFINITION(MyBlob, "my_blob");

struct MyBlob : public PlBlob
{ std::unique_ptr<MyConnection> connection;

  explicit MyBlob()
    : PlBlob(&my_blob) { }

  explicit MyBlob(const std::string& connection_name)
    : PlBlob(&my_blob),
      connection(std::make_unique<MyConnection>(connection_name))
  { if ( !connection->open() )
      throw MyBlobError("my_blob_open_error");
  }

  PL_BLOB_SIZE

  ~MyBlob() noexcept
  { if ( !close() )
      Sdprintf("***ERROR: Close MyBlob failed: %s\n", name().c_str()); // Can't use PL_warning()
  }

  inline std::string
  name() const
  { return connection ? connection->name : "";
  }

  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<const MyBlob*>(_b_data); // See note about cast
    return name().compare(b_data->name());
  }

  bool write_fields(IOSTREAM *s, int flags) const override
  { PlStream strm(s);
    strm.printf(",");
    return write_fields_only(strm);
  }

  bool write_fields_only(PlStream& strm) const
  { if ( connection )
      connection->portray(strm);
    else
      strm.printf("closed");
    return true;
  }

  bool portray(PlStream& strm) const
  { strm.printf("MyBlob(");
    write_fields_only(strm);
    strm.printf(")");
    return true;
  }
};

// %! create_my_blob(+Name: atom, -MyBlob) is semidet.
PREDICATE(create_my_blob, 2)
{ // Allocating the blob uses std::unique_ptr<MyBlob> so that it'll be
  // deleted if an error happens - the auto-deletion is disabled by
  // ref.release() inside unify_blob() before returning success.

  auto ref = std::unique_ptr<PlBlob>(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<MyBlob>::cast_ex(A1, my_blob);
  if ( !ref->close() )
    throw ref->MyBlobError("my_blob_close_error");
  return true;
}

// %! portray_my_blob(+Stream, +MyBlob) is det.
// % Hook predicate for
// %   user:portray(MyBlob) :-
// %     blob(MyBlob, my_blob), !,
// %     portray_my_blob(current_output, MyBlob).
PREDICATE(portray_my_blob, 2)
{ auto ref = PlBlobV<MyBlob>::cast_ex(A2, my_blob);
  PlStream strm(A1, 0);
  return ref->portray(strm);
}

1.6.8.6 Discussion of the sample PlBlob code

1.6.8.7 Sample PlBlob code (wrapping a pointer)

struct MyFileBlob;

static PL_blob_t my_file_blob = PL_BLOB_DEFINITION(MyFileBlob, "my_file_blob");

static const PlOptionsFlag<int>
MyFileBlob_options("MyFileBlob-options",
                   { {"absolute", PL_FILE_ABSOLUTE},
                     {"ospath",   PL_FILE_OSPATH},
                     {"search",   PL_FILE_SEARCH},
                     {"exist",    PL_FILE_EXIST},
                     {"read",     PL_FILE_READ},
                     {"write",    PL_FILE_WRITE},
                     {"execute",  PL_FILE_EXECUTE},
                     {"noerrors", PL_FILE_NOERRORS} });

struct MyFileBlob : public PlBlob
{ std::FILE* file_;

  std::string mode_;
  int flags_;
  std::string filename_;
  std::vector<char> buffer_; // used by read(), to avoid re-allocation

  explicit MyFileBlob()
    : PlBlob(&my_file_blob) { }

  explicit MyFileBlob(PlTerm filename, PlTerm mode, PlTerm flags)
    : PlBlob(&my_file_blob),
      mode_(mode.as_string())
  { flags_ = MyFileBlob_options.lookup_list(flags);
    filename_ = filename.get_file_name(flags_);
    file_ = fopen(filename_.c_str(), mode_.c_str());
    if ( !file_ ) // TODO: get error code (might not be existence error)
      throw PlExistenceError("my_file_blob_open", PlTerm_string(filename_));
    // for debugging:
    //   PlTerm_string(filename.as_string() + "\" => \"" +
    //                 filename_ + "\", \"" + mode_ +
    //                 ", flags=" + MyFileBlob_options.as_string(flags_) + "\")")
  }

  PL_BLOB_SIZE

  std::string read(size_t count)
  { assert(sizeof buffer_[0] == sizeof (char));
    assert(sizeof (char) == 1);

    buffer_.reserve(count);
    return std::string(buffer_.data(),
                       std::fread(buffer_.data(), sizeof buffer_[0], count, file_));
  }

  bool eof() const
  { return std::feof(file_);
  }

  bool error() const
  { return std::ferror(file_);
  }

  virtual ~MyFileBlob() noexcept
  { if ( !close() )
      // Can't use PL_warning()
      Sdprintf("***ERROR: Close MyFileBlob failed: (%s)\n", filename_.c_str());
  }

  bool close() noexcept
  { if ( !file_ )
      return true;
    int rc = std::fclose(file_);
    file_ = nullptr;
    return rc == 0;
  }

  PlException MyFileBlobError(const std::string error) const
  { return PlGeneralError(PlCompound(error, PlTermv(symbol_term())));
  }

  int compare_fields(const PlBlob* _b_data) const override
  { // dynamic_cast is safer than static_cast, but slower (see documentation)
    // It's used here for testing (the documentation has static_cast)
    auto b_data = dynamic_cast<const MyFileBlob*>(_b_data);
    return filename_.compare(b_data->filename_);
  }

  bool write_fields(IOSTREAM *s, int flags) const override
  { PlStream strm(s);
    strm.printf(",");
    return write_fields_only(strm);
  }

  bool write_fields_only(PlStream& strm) const
  { // For debugging:
    // strm.printf("%s mode=%s flags=%s", filename_.c_str(), mode_.c_str(),
    //             MyFileBlob_options.as_string(flags_).c_str());
    strm.printf("%s", filename_.c_str());
    if ( !file_ )
      strm.printf("-CLOSED");
    return true;
  }

  bool portray(PlStream& strm) const
  { strm.printf("MyFileBlob(");
    write_fields_only(strm);
    strm.printf(")");
    return true;
  }
};

PREDICATE(my_file_open, 4)
{ auto ref = std::unique_ptr<PlBlob>(new MyFileBlob(A2, A3, A4));
  return A1.unify_blob(&ref);
}

PREDICATE(my_file_close, 1)
{ auto ref = PlBlobV<MyFileBlob>::cast_ex(A1, my_file_blob);
  if ( !ref->close() ) // TODO: get the error code
    throw ref->MyFileBlobError("my_file_blob_close_error");
  return true;
}

1.6.8.8 Discussion of the sample PlBlob code (wrapping a pointer)

1.6.8.9 Identifying blobs by atoms

Passing a Prolog blob around can be inconvenient; it is easier if a blob can be identified an atom. An example of this is with streams, which are identified by atoms such as user_input.

A utility class AtomMap is provided for this situation. See section 1.17.4.

1.6.9 Limitations of the interface

The C++ API remains a work in progress.

1.6.9.1 Strings

SWI-Prolog string handling has evolved over time. The functions that create atoms or strings using char* or wchar_t* are “old school” ; similarly with functions that get the string as char* or wchar_t*. The PL_get,unify,put_[nw]chars() family is more friendly when it comes to different input, output, encoding and exception handling.

Roughly, the modern API is PL_get_nchars(), PL_unify_chars() and PL_put_chars() on terms. There is only half of the API for atoms as PL_new_atom_mbchars() and PL-atom_mbchars(), which take an encoding, length and char*.

For return values, char* is dangerous because it can point to local or stack memory. For this reason, wherever possible, the C++ API returns a std::string, which contains a copy of the string. This can be slightly less efficient that returning a char*, but it avoids some subtle and pervasive bugs that even address sanitizers can't detect.23If 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.

Some functions require allocating string space using PL_STRINGS_MARK(). The PlStringBuffers class provides a RAII wrapper that ensures the matching PL_STRINGS_RELEASE() is done. The PlAtom or PlTerm member functions that need the string buffer use PlStringBuffers, and then copy the resulting string to a std::string value.

The C++ API has functions such as PlTerm::get_nchars() that use PlStringBuffers and then copy the result to a std::string result, so the programmer often doesn't need to use PlStringBuffers.

PlStringBuffers
A RAII wrapper for allocating a string that is created using BUF_STACK. This isn't needed if you use a method such as PlTerm::as_string(), but is needed for calling certain PL_*() or Plx_*() wrapped functions.

The constructor calls PL_STRINGS_MARK() and the destructor calls PL_STRINGS_RELEASE(). Here is an example of its use, for writing an atom to a stream, using Plx_atom_wchars(), which must be called within a strings buffer: 

PREDICATE(w_atom_cpp, 2)
{ auto stream(A1), term(A2);
  PlStream strm(stream, STIO_OUTPUT);
  PlStringBuffers _string_buffers;
  const pl_wchar_t *sa = Plx_atom_wchars(term.as_atom().unwrap(), nullptr);
  strm.printfX("/%Ws/", sa);
  return true;
}

1.6.9.2 Stream I/O

PlStream can be used to get a stream from a Prolog term, or to lock the stream so that other threads cannot interleave their output. With either usage, PlStream is a RAII class that ensure the matchin PL_release_stream() is done, and also handles some subtle problems with C++ exceptions.

The methods are:

PlStream :: PlStream(term_t t, int flags)
- see PL_get_stream() for documentation of the flags. Throws a C++ exception on error.
PlStream :: PlStream(IOSTREAM *s)
- calls PL_acquire_stream() to lock the stream. Throws a C++ exception on error.
~ PlStream()
- calls PlStream::release(). See below for caveats if there are exceptions.
void PlStream::release()
calls PL_release_stream(), throwing an exception if there has been an I/O error on the stream, and sets the PlStream object to an invalid stream (see PlStream::check_stream()).
IOSTREAM* ::operator PlStream(void)
- when used in a context that requires an IOSTREAM*, PlStream is implicitly converted to IOSTREAM*.
void check_stream()
checks that the PlStream object contains a valid stream and throws an exception if it doesn't. This is used to ensure that PlStream::release() hasn't been called.

Most of the stream I/O functions have corresponding methods in PlStream. For example, Sfprintf() corresponds to PlStream::printf(). PlStream::seek() and PlStream::tell() call Sseek64() and Stell64() instead of long (they are also deprecated: PlStream::seek64() and PlStream::tell64() are preferred).

The C interface to stream I/O doesn't raise a Prolog error when there's a stream error (typically indicated by a -1 return code). Instead, the error sets a flag on the stream and PL_release_stream() creates the error term. The PlStream destructor calls PL_release_stream(); but it's a fatal error in C++ to raise an exception in a destructor if the destructor is invoked by stack-unwinding due to another exception, including the pseudo-exceptions PlFail and PlExceptionFail.

To get around this, the various stream I/O functions have wrapper methods in the PlStream class that check for an error and call PlStream::release() to create the Prolog error, which is thrown as a C++ error.

The destructor calls PlStream::release(), which throws a C++ exception if there is a stream error. This is outside the destructor, so it is safe - the destructor checks if the stream has been released and does nothing in that situation.

The following two code examples do essentially the same thing: 

PREDICATE(name_arity, 1)
{ PlStream strm(Scurrent_output);
  strm.printf("name = %s, arity = %zd\n", A1.name().as_string().c_str(), A1.arity());
  return true;
}
PREDICATE(name_arity, 1)
{ PlStream strm(Scurrent_output);
  try
  { strm.printf("name = %s, arity = %zd\n", A1.name().as_string().c_str(), A1.arity());
  } PREDICATE_CATCH({strm.release(); return false;})
  return true;
}

If you write the code as follows, using Sfprintf() directly, it is possible that a fatal exception will be raised on an I/O error: 

PREDICATE(name_arity, 1)
{ PlStream strm(Scurrent_output);
  Sfprintf(strm, "name = %s, arity = %zd\n", A1.name().as_string().c_str(), A1.arity());
  return true;
  // WARNING: the PlStream destructor might throw a C++
  //          exception on stack unwinding, giving a fatal
  //          fatal runtime exception.
}

If you don't use these, and want to throw an exception if there's an error, the following code works because PlStream (and the underlying PL_acquire_stream()) can be called recursively: 

{ PlStream strm(...);
  strm.release();
}

1.6.9.3 Object handles

Many of the “opaque object handles” , such as atom_t, term_t, and functor_t are integers.24Typically uintptr_t values, which the C standard defines as “an unsigned integer type with the property that any valid pointer to void can be converted to this type, then converted back to pointer to void, and the result will compare equal to the original pointer.’ As such, there is no compile-time detection of passing the wrong handle to a function.

This leads to a problem with classes such as PlTerm - C++ overloading cannot be used to distinguish, for example, creating a term from an atom versus creating a term from an integer. There are a number of possible solutions, including:

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.

1.6.10 Linking embedded applications using swipl-ld

The utility program swipl-ld (Win32: swipl-ld.exe) works with both C and C++ programs. See Linking embedded applications using swipl-ld for more details.

Your C++ compiler should support at least C++-17.

To avoid incompatibilities amongst the various C++ compilers’ABIs, the object file from compiling SWI-cpp2.cpp is not included in the shared object libswipl; instead, it must be compiled along with any foreign predicate files. If the macro _SWI_CPP2_CPP_SEPARATE is defined before the include for SWI-cpp2.h, then SWI-cpp2.cpp is not automatically included and must be compiled separately - either by creating a .a file or by adding a #include <SWI-cpp2.cpp> to one of your source files.

ClioPatria (version V3.1.1-51-ga0b30a5)