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
Data type for a C hook. The internals of this type should be treated as opaque.
Enumeration of possible hook types, which are:
- Type of hook for which all the registered functions will always be called.
- 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).
- Type of hook for which the sequence of registered functions will be called only until one of them returns C false (a NULL pointer).
Initialize the C hook at memory pointed to by hook. type should be one of the values of the
scm_t_c_hook_typeenumeration, 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_remove. A hook function must expect three
void * parameters which are, respectively:
scm_c_hook_runcall that runs the hook.
Function type for a C hook function: takes three
void *parameters and returns a
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.
Remove function func, with function closure data func_data, from the C hook hook.
scm_c_hook_removechecks 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
specifying the hook and the call closure data for this run:
Run the C hook hook will call closure data data. Subject to the variations for hook types
scm_c_hook_runcalls 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.