11.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(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);
}