(guile.info.gz) C Hooks

Info Catalog

(guile.info.gz) Hook Reference

(guile.info.gz) Hooks

(guile.info.gz) Guile Hooks

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

Info Catalog

(guile.info.gz) Hook Reference

(guile.info.gz) Hooks

(guile.info.gz) Guile Hooks