/[guile]/guile/guile-core/doc/ref/scheme-utility.texi
ViewVC logotype

Diff of /guile/guile-core/doc/ref/scheme-utility.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.6 by ossau, Sat Mar 16 00:27:25 2002 UTC revision 1.7 by ossau, Sat Mar 16 13:51:03 2002 UTC
# Line 572  code needs to do, you may prefer to use Line 572  code needs to do, you may prefer to use
572  To create a C hook, you should allocate storage for a structure of type  To create a C hook, you should allocate storage for a structure of type
573  @code{scm_t_c_hook} and then initialize it using @code{scm_c_hook_init}.  @code{scm_t_c_hook} and then initialize it using @code{scm_c_hook_init}.
574    
575  @deffn {C Type} scm_t_c_hook  @deftp {C Type} scm_t_c_hook
576  Data type for a C hook.  The internals of this type should be treated as  Data type for a C hook.  The internals of this type should be treated as
577  opaque.  opaque.
578  @end deffn  @end deftp
579    
580  @deffn {C Enum} scm_t_c_hook_type  @deftp {C Enum} scm_t_c_hook_type
581  Enumeration of possible hook types, which are:  Enumeration of possible hook types, which are:
582    
583  @table @code  @table @code
584  @item SCM_C_HOOK_NORMAL  @item SCM_C_HOOK_NORMAL
585    @vindex SCM_C_HOOK_NORMAL
586  Type of hook for which all the registered functions will always be called.  Type of hook for which all the registered functions will always be called.
587  @item SCM_C_HOOK_OR  @item SCM_C_HOOK_OR
588    @vindex SCM_C_HOOK_OR
589  Type of hook for which the sequence of registered functions will be  Type of hook for which the sequence of registered functions will be
590  called only until one of them returns C true (a non-NULL pointer).  called only until one of them returns C true (a non-NULL pointer).
591  @item SCM_C_HOOK_AND  @item SCM_C_HOOK_AND
592    @vindex SCM_C_HOOK_AND
593  Type of hook for which the sequence of registered functions will be  Type of hook for which the sequence of registered functions will be
594  called only until one of them returns C false (a NULL pointer).  called only until one of them returns C false (a NULL pointer).
595  @end table  @end table
596  @end deffn  @end deftp
597    
598  @deftypefn {C Function} void scm_c_hook_init (scm_t_c_hook *hook, void *hook_data, scm_t_c_hook_type type)  @deftypefn {C Function} void scm_c_hook_init (scm_t_c_hook *hook, void *hook_data, scm_t_c_hook_type type)
599  Initialize the C hook at memory pointed to by @var{hook}.  @var{type}  Initialize the C hook at memory pointed to by @var{hook}.  @var{type}
# Line 618  The call closure data specified by the @ Line 621  The call closure data specified by the @
621  runs the hook.  runs the hook.
622  @end table  @end table
623    
624  @deffn {C Type} scm_t_c_hook_function  @deftp {C Type} scm_t_c_hook_function
625  Function type for a C hook function: takes three @code{void *}  Function type for a C hook function: takes three @code{void *}
626  parameters and returns a @code{void *} result.  parameters and returns a @code{void *} result.
627  @end deffn  @end deftp
628    
629  @deftypefn {C Function} void scm_c_hook_add (scm_t_c_hook *hook, scm_t_c_hook_function func, void *func_data, int appendp)  @deftypefn {C Function} void scm_c_hook_add (scm_t_c_hook *hook, scm_t_c_hook_function func, void *func_data, int appendp)
630  Add function @var{func}, with function closure data @var{func_data}, to  Add function @var{func}, with function closure data @var{func_data}, to
# Line 654  function to be called. Line 657  function to be called.
657  @node Guile Hooks  @node Guile Hooks
658  @subsection Hooks Provided by Guile  @subsection Hooks Provided by Guile
659    
660  @table @code  @menu
661  @item scm_before_gc_c_hook  * GC Hooks::                    Garbage collection hooks.
662  @item scm_before_mark_c_hook  * REPL Hooks::                  Hooks into the Guile REPL.
663  @item scm_before_sweep_c_hook  @end menu
664  @item scm_after_sweep_c_hook  
665  @item scm_after_gc_c_hook  
666  @end table  @node GC Hooks
667    @subsubsection Hooks for Garbage Collection
668    
669    Whenever Guile performs a garbage collection, it calls the following
670    hooks in the order shown.
671    
672    @defvr {C Hook} scm_before_gc_c_hook
673    C hook called at the very start of a garbage collection, after setting
674    @code{scm_gc_running_p} to 1, but before entering the GC critical
675    section.
676    
677    If garbage collection is blocked because @code{scm_block_gc} is
678    non-zero, GC exits early soon after calling this hook, and no further
679    hooks will be called.
680    @end defvr
681    
682    @defvr {C Hook} scm_before_mark_c_hook
683    C hook called before beginning the mark phase of garbage collection,
684    after the GC thread has entered a critical section.
685    @end defvr
686    
687    @defvr {C Hook} scm_before_sweep_c_hook
688    C hook called before beginning the sweep phase of garbage collection.
689    This is the same as at the end of the mark phase, since nothing else
690    happens between marking and sweeping.
691    @end defvr
692    
693    @defvr {C Hook} scm_after_sweep_c_hook
694    C hook called after the end of the sweep phase of garbage collection,
695    but while the GC thread is still inside its critical section.
696    @end defvr
697    
698    @defvr {C Hook} scm_after_gc_c_hook
699    C hook called at the very end of a garbage collection, after the GC
700    thread has left its critical section.
701    @end defvr
702    
703    @defvr {Scheme Hook} after-gc-hook
704    @vindex scm_after_gc_hook
705    Scheme hook with arity 0.  This hook is run asynchronously
706    (@pxref{Asyncs}) soon after the GC has completed and any other events
707    that were deferred during garbage collection have been processed.  (Also
708    accessible from C with the name @code{scm_after_gc_hook}.)
709    @end defvr
710    
711    All the C hooks listed here have type @code{SCM_C_HOOK_NORMAL}, are
712    initialized with hook closure data NULL, are are invoked by
713    @code{scm_c_hook_run} with call closure data NULL.
714    
715    @cindex guardians, testing for GC'd objects
716    The Scheme hook @code{after-gc-hook} is particularly useful in
717    conjunction with guardians (@pxref{Guardians}).  Typically, if you are
718    using a guardian, you want to call the guardian after garbage collection
719    to see if any of the objects added to the guardian have been collected.
720    By adding a thunk that performs this call to @code{after-gc-hook}, you
721    can ensure that your guardian is tested after every garbage collection
722    cycle.
723    
724    
725    @node REPL Hooks
726    @subsubsection Hooks into the Guile REPL
727    
728    
729  @c Local Variables:  @c Local Variables:

Legend:
Removed from v.1.6  
changed lines
  Added in v.1.7

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26