12.3.2 Other foreign interface types
- The type
atom_tactually represents a blob (see section 12.4.9). 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 handle is enough to prove equivalence of the content; i.e., given two different atom handles we know they represent different texts. This uniqueness feature allows the core engine to reason about atoms without considering their content. Strings (section 5.2) and blobs without the
PL_BLOB_UNIQUEfeature do not have this uniqueness property - to test for equality, the contents of the strings or blobs must be compared.
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.
- 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.
- Handle to a Prolog predicate. Predicate handles live forever (although they can lose their definition).
- Query identifier. Used by PL_open_query(), PL_next_solution(), PL_cut_query(), and PL_close_query() to handle calling Prolog from C.
- Frame identifier. Used by PL_open_foreign_frame() and PL_close_foreign_frame().
- A module is a unique handle to a Prolog module. Modules are used only to call predicates in a specific module.
- Return type for a C function implementing a Prolog predicate.
- Passed as additional argument to non-deterministic foreign functions. See PL_retry*() and PL_foreign_context*().
- Type for the install() and uninstall() functions of shared or dynamic link libraries. See section 12.2.3.
- 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_tis defined in the
stdint.hstandard 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
FALSEon 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.
As of SWI-Prolog 7.3.12, the arity of terms has changed from
size_t. To deal with this transition, all affecting
functions have two versions, where the old name exchanges the arity as
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
functions. As of 8.1.29/8.2.x, the default is to use
and the old behaviour can be restored by defining
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
size_t. Please be
size_t is unsigned. At some point representing
int will be dropped completely.