12.3.2 Other foreign interface types

atom_t

The type atom_t actually represents a blob (see section 12.4.10). Blobs are the super type of Prolog atoms, where atoms are blobs that represent textual content. Textual content is also represented by Prolog string (see section 5.2), which makes the general notion of string in Prolog ambiguous. The core idea behind blobs/atoms is to represent arbitrary content using a unique handle, such that comparing the handles is enough to prove equivalence of the contents; i.e., given two different atom handles we know they represent different texts. This uniqueness feature allows the core engine to reason about atom equality and inequality without considering their content. Blobs without the PL_BLOB_UNIQUE feature are also tested for uniqueness without considering their content. Each time an atom or a PL_BLOB_UNIQUE blob is created, it must be looked up in the atom table; if a blob without PL_BLOB_UNIQUE is created, no lookup is done. Strings (section 5.2) and blobs without the PL_BLOB_UNIQUE feature do not have this uniqueness property - to test for equality, the contents of the strings or blobs must be compared. For both atoms and strings, comparisons for ordering (e.g., used by sort/2 or @</2) must use the contents; in the case of blobs, compare() can be specified in the PL_blob_t structure to override the default bitwise comparison.

Because atoms are often used to represent (parts of) arbitrary input, intermediate results, and output of data processed by Prolog, it is necessary that atoms be subject to garbage collection (see garbage_collect_atoms/0). The garbage collection makes atoms ideal handles for arbitrary data structures, which are generalized as blobs. Blobs provide safe access to many internal Prolog data structures such as streams, clause references, etc.

functor_t

A functor is the internal representation of a name/arity pair. They are used to find the name and arity of a compound term as well as to construct new compound terms. Like atoms they live for the whole Prolog session and are unique.

predicate_t

Handle to a Prolog predicate. Predicate handles live forever (although they can lose their definition).

qid_t

Query identifier. Used by PL_open_query(), PL_next_solution(), PL_cut_query(), and PL_close_query() to handle calling Prolog from C.

fid_t

Frame identifier. Used by PL_open_foreign_frame() and PL_close_foreign_frame().

module_t

A module is a unique handle to a Prolog module. Modules are used only to call predicates in a specific module.

foreign_t

Return type for a C function implementing a Prolog predicate.

control_t

Passed as additional argument to non-deterministic foreign functions. See PL_retry*() and PL_foreign_context*().

install_t

Type for the install() and uninstall() functions of shared or dynamic link libraries. See section 12.2.3.

int64_t

Actually part of the C99 standard rather than Prolog. As of version 5.5.6, Prolog integers are 64-bit on all hardware. The C99 type int64_t is defined in the stdint.h standard header and provides platform-independent 64-bit integers. Portable code accessing Prolog should use this type to exchange integer values. Please note that PL_get_long() can return FALSE on Prolog integers that cannot be represented as a C long. Robust code should not assume any of the integer fetching functions to succeed, even if the Prolog term is known to be an integer.

12.3.2.1 PL_ARITY_AS_SIZE

As of SWI-Prolog 7.3.12, the arity of terms has changed from int to size_t. To deal with this transition, all affecting functions have two versions, where the old name exchanges the arity as int and a new function with name *_sz() exchanges the arity as size_t. Up to 8.1.28, the default was to use the old int functions. As of 8.1.29/8.2.x, the default is to use size_t and the old behaviour can be restored by defining PL_ARITY_AS_SIZE to 0 (zero). This makes old code compatible, but the following warning is printed when compiling:

#warning "Term arity has changed from int to size_t."
#warning "Please update your code or use #define PL_ARITY_AS_SIZE 0."

To make the code compile silently again, change the types you use to represent arity from int to size_t. Please be aware that size_t is unsigned. At some point representing arity as int will be dropped completely.

12.3.2.2 Notes on C API bool return values

Most of the SWI-Prolog C-API consists of C functions that return a Boolean result. Up to version 9.3.10, these functions are defined to return int. Later versions define these functions to return the bool. This type is provided by the standard header stdbool.h and will be supported as a native type starting with the C23 standard, which introduces the keywords false, true and bool. SWI-Prolog.h defines the constants FALSE and TRUE. These constants are consistent with false, and true and may be used interchangeably. Future versions will deprecate FALSE and TRUE. As of version 9.3.11 SWI-Prolog.h includes stdbool.h and thus provides the standard names.

The Boolean result true indicates success, while false may indicate an error or logical failure. Which of the two happened can be examined by calling PL_exception(0), which returns a term_t of value 0 if there was a logical failure. Otherwise the returned term reference is a handle to the Prolog exception. Typically there is no need to test whether or not there has been an exception. Instead, the implementation of a foreign predicate can often simply return false in case some API returned false. Prolog will map this to logical failure or raise the pending exception. The C API defines several groups of bool functions that behave consistently. Note that errors which as the Prolog term handle (term_t) not being a valid is not reported through the API. If this is detected PL_api_error() is called, which aborts the process with a diagnostic message. If not detected, such errors lead to undefined behaviour (read: arbitrary crashes or wrong behaviour now or later).

PL_is_*()

These are type checking functions. They have no side effects and no error conditions. Returning false implies the argument is not of the tested type.

PL_get_*()

This group extracts C value from a Prolog term. If the term is not of the expected type or the C value cannot represent the value the function returns false. No exception is raised.

PL_get_*_ex()

This group is similar to PL_get_*(), but raises a Prolog exception. The exception is either an instantiation_error in case the term is unbound but should not be, a type_error in case the term is of the wrong type or a representation_error in case the C type cannot represent the Prolog value (e.g., a C int while the Prolog integer is out of reach for this type).

PL_put_*()

This group converts C data to a Prolog term. Such a function returning false always raises a resource_error, indicating that Prolog does not have sufficient resources to store the result.

PL_unify_*()

This group unifies a Prolog term to a converted C value. Here, the failure can be logical if the unification failed because the term was already bound to some other value or the failure may be the result of a resource error as with the PL_put_*() group.