SWI-Prolog -- Manual

#abort/0">abort/0 is executed. SWI-Prolog abort/0 is implemented using C setjmp()/longjmp() construct. The hooks are executed in the reverse order of their registration after the longjmp() took place and before the Prolog top level is reinvoked. The type PL_abort_hook_t is defined as:

typedef void (*PL_abort_hook_t)(void);

int PL_abort_unhook(PL_abort_hook_t)

Remove a hook installed with PL_abort_hook(). Returns FALSE if no such hook is found, TRUE otherwise.

void PL_on_halt(int (*f)(int, void *), void *closure)

Register the function f to be called if SWI-Prolog is halted. The function is called with two arguments: the exit code of the process (0 if this cannot be determined) and the closure argument passed to the PL_on_halt() call. Handlers must return 0. Other return values are reserved for future use. See also at_halt/1.^{bugAlthough
both PL_on_halt()
and at_halt/1
are called in FIFO order, all at_halt/1
handlers are called before all PL_on_halt()
handlers.} These handlers are called before system cleanup and can therefore access all normal Prolog resources. See also PL_exit_hook().

void PL_exit_hook(int (*f)(int, void *), void *closure)

Similar to PL_on_halt(), but the hooks are executed by PL_halt() instead of PL_cleanup() just before calling exit().

PL_agc_hook_t PL_agc_hook(PL_agc_hook_t new)

Register a hook with the atom-garbage collector (see garbage_collect_atoms/0) that is called on any atom that is reclaimed. The old hook is returned. If no hook is currently defined, NULL is returned. The argument of the called hook is the atom that is to be garbage collected. The return value is an int. If the return value is zero, the atom is not reclaimed. The hook may invoke any Prolog predicate.

The example below defines a foreign library for printing the garbage collected atoms for debugging purposes.

#include <SWI-Stream.h>
#include <SWI-Prolog.h>

static int
atom_hook(atom_t a)
{ Sdprintf("AGC: deleting %s\n", PL_atom_chars(a));

  return TRUE;
}

static PL_agc_hook_t old;

install_t
install()
{ old = PL_agc_hook(atom_hook);
}

install_t
uninstall()
{ PL_agc_hook(old);
}

12.4.22 Storing foreign data

When combining foreign code with Prolog, it can be necessary to make data represented in the foreign language available to Prolog. For example, to pass it to another foreign function. At the end of this section, there is a partial implementation of using foreign functions to manage bit-vectors. Another example is the SGML/XML library that manages a‘parser' object, an object that represents the current state of the parser and that can be directed to perform actions such as parsing a document or make queries about the document content.

This section provides some hints for handling foreign data in Prolog. There are four options for storing such data:

Natural Prolog data
Uses the representation one would choose if no foreign interface was required. For example, a bitvector representing a list of small integers can be represented as a Prolog list of integers.
Opaque packed data on the stacks
It is possible to represent the raw binary representation of the foreign object as a Prolog string (see section 5.2). Strings may be created from foreign data using PL_put_string_nchars() and retrieved using PL_get_string_chars(). It is good practice to wrap the string in a compound term with arity 1, so Prolog can identify the type. The hook portray/1 rules may be used to streamline printing such terms during development.
Opaque packed data in a blob
Similar to the above solution, binary data can be stored in an atom. The blob interface (section 12.4.8) provides additional facilities to assign a type and hook-functions that act on creation and destruction of the underlying atom.
Natural foreign data, passed as a pointer
An alternative is to pass a pointer to the foreign data. Again, the pointer is often wrapped in a compound term.

The choice may be guided using the following distinctions

Is the data opaque to Prolog
With‘opaque' data, we refer to data handled in foreign functions, passed around in Prolog, but where Prolog never examines the contents of the data itself. If the data is opaque to Prolog, the selection will be driven solely by simplicity of the interface and performance.
What is the lifetime of the data
With‘lifetime' we refer to how it is decided that the object is (or can be) destroyed. We can distinguish three cases:
1. The object must be destroyed on backtracking and normal Prolog garbage collection (i.e., it acts as a normal Prolog term). In this case, representing the object as a Prolog string (second option above) is the only feasible solution.
2. The data must survive Prolog backtracking. This leaves two options. One is to represent the object using a pointer and use explicit creation and destruction, making the programmer responsible. The alternative is to use the blob-interface, leaving destruction to the (atom) garbage collector.
3. The data lives as during the lifetime of a foreign function that implements a predicate. If the predicate is deterministic, foreign automatic variables are suitable. If the predicate is non-deterministic, the data may be allocated using malloc() and a pointer may be passed. See section 12.4.1.1.

12.4.22.1 Examples for storing foreign data

In this section, we outline some examples, covering typical cases. In the first example, we will deal with extending Prolog's data representation with integer sets, represented as bit-vect