6.11.6.3 Hooks For C Code.

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.

C Type: scm_t_c_hook

Data type for a C hook. The internals of this type should be treated as opaque.

C Enum: scm_t_c_hook_type

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).

C Function: 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:

hook_data

The hook closure data that was specified at the time the hook was initialized by scm_c_hook_init.

func_data

The function closure data that was specified at the time that that function was registered with the hook by scm_c_hook_add.

data

The call closure data specified by the scm_c_hook_run call that runs the hook.

C Type: scm_t_c_hook_function

Function type for a C hook function: takes three void * parameters and returns a void * result.

C Function: 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.

C Function: 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:

C Function: 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.