9.4.19 Foreign Code Hooks

For various specific applications some hooks are provided.

PL_dispatch_hook_t PL_dispatch_hook(PL_dispatch_hook_t)

If this hook is not NULL, this function is called when reading from the terminal. It is supposed to dispatch events when SWI-Prolog is connected to a window environment. It can return two values: PL_DISPATCH_INPUT indicates Prolog input is available on file descriptor 0 or PL_DISPATCH_TIMEOUT to indicate a timeout. The old hook is returned. The type PL_dispatch_hook_t is defined as:

typedef int  (*PL_dispatch_hook_t)(void);

void PL_abort_hook(PL_abort_hook_t)

Install a hook when 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(void (*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 on your operating system) and the closure argument passed to the PL_on_halt() call. See also at_halt/1.

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);
}