The hooks already described are intended to be populated by Scheme-level procedures. In addition to this, the Guile library provides an independent set of interfaces for the creation and manipulation of hooks that are designed to be populated by functions implemented in C.
The original motivation here was to provide a kind of hook that could safely be invoked at various points during garbage collection. Scheme-level hooks are unsuitable for this purpose as running them could itself require memory allocation, which would then invoke garbage collection recursively … However, it is also the case that these hooks are easier to work with than the Scheme-level ones if you only want to register C functions with them. So if that is mainly what your code needs to do, you may prefer to use this interface.
To create a C hook, you should allocate storage for a structure of type
scm_t_c_hook and then initialize it using scm_c_hook_init.
Data type for a C hook. The internals of this type should be treated as opaque.
Enumeration of possible hook types, which are:
SCM_C_HOOK_NORMAL ¶Type of hook for which all the registered functions will always be called.
SCM_C_HOOK_OR ¶Type of hook for which the sequence of registered functions will be called only until one of them returns C true (a non-NULL pointer).
SCM_C_HOOK_AND ¶Type of hook for which the sequence of registered functions will be called only until one of them returns C false (a NULL pointer).
void scm_c_hook_init (scm_t_c_hook *hook, void *hook_data, scm_t_c_hook_type type) ¶Initialize the C hook at memory pointed to by hook. type
should be one of the values of the scm_t_c_hook_type enumeration,
and controls how the hook functions will be called. hook_data is
a closure parameter that will be passed to all registered hook functions
when they are called.
To add or remove a C function from a C hook, use scm_c_hook_add
or scm_c_hook_remove. A hook function must expect three
void * parameters which are, respectively:
The hook closure data that was specified at the time the hook was
initialized by scm_c_hook_init.
The function closure data that was specified at the time that that
function was registered with the hook by scm_c_hook_add.
The call closure data specified by the scm_c_hook_run call that
runs the hook.
Function type for a C hook function: takes three void *
parameters and returns a void * result.
void scm_c_hook_add (scm_t_c_hook *hook, scm_t_c_hook_function func, void *func_data, int appendp) ¶Add function func, with function closure data func_data, to the C hook hook. The new function is appended to the hook’s list of functions if appendp is non-zero, otherwise prepended.
void scm_c_hook_remove (scm_t_c_hook *hook, scm_t_c_hook_function func, void *func_data) ¶Remove function func, with function closure data func_data,
from the C hook hook. scm_c_hook_remove checks both
func and func_data so as to allow for the same func
being registered multiple times with different closure data.
Finally, to invoke a C hook, call the scm_c_hook_run function
specifying the hook and the call closure data for this run:
void * scm_c_hook_run (scm_t_c_hook *hook, void *data) ¶Run the C hook hook will call closure data data. Subject to
the variations for hook types SCM_C_HOOK_OR and
SCM_C_HOOK_AND, scm_c_hook_run calls hook’s
registered functions in turn, passing them the hook’s closure data, each
function’s closure data, and the call closure data.
scm_c_hook_run’s return value is the return value of the last
function to be called.