/[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.5 by ossau, Fri Mar 15 14:03:53 2002 UTC revision 1.6 by ossau, Sat Mar 16 00:27:25 2002 UTC
# Line 377  argument @var{printer} (default: @code{w Line 377  argument @var{printer} (default: @code{w
377  @section Hooks  @section Hooks
378  @tpindex Hooks  @tpindex Hooks
379    
380  @c FIXME::martin: Review me!  A hook is a list of procedures to be called at well defined points in
381    time.  Typically, an application provides a hook @var{h} and promises
382  A hook is basically a list of procedures to be called at well defined  its users that it will call all of the procedures in @var{h} at a
383  points in time.  Hooks are used internally for several debugging  defined point in the application's processing.  By adding its own
384  facilities, but they can be used in user code, too.  procedure to @var{h}, an application user can tap into or even influence
385    the progress of the application.
386  Hooks are created with @code{make-hook}, then procedures can be added to  
387  a hook with @code{add-hook!} or removed with @code{remove-hook!} or  Guile itself provides several such hooks for debugging and customization
388  @code{reset-hook!}.  The procedures stored in a hook can be invoked with  purposes: these are listed in a subsection below.
389  @code{run-hook}.  
390    When an application first creates a hook, it needs to know how many
391    arguments will be passed to the hook's procedures when the hook is run.
392    The chosen number of arguments (which may be none) is declared when the
393    hook is created, and all the procedures that are added to that hook must
394    be capable of accepting that number of arguments.
395    
396    A hook is created using @code{make-hook}.  A procedure can be added to
397    or removed from a hook using @code{add-hook!} or @code{remove-hook!},
398    and all of a hook's procedures can be removed together using
399    @code{reset-hook!}.  When an application wants to run a hook, it does so
400    using @code{run-hook}.
401    
402  @menu  @menu
403  * Hook Examples::               Hook usage by example.  * Hook Example::                Hook usage by example.
404  * Hook Reference::              Reference of all hook procedures.  * Hook Reference::              Reference of all hook procedures.
405    * C Hooks::                     Hooks for use from C code.
406    * Guile Hooks::                 Hooks provided by Guile.
407  @end menu  @end menu
408    
409  @node Hook Examples  
410  @subsection Hook Examples  @node Hook Example
411    @subsection Hook Usage by Example
412    
413  Hook usage is shown by some examples in this section.  First, we will  Hook usage is shown by some examples in this section.  First, we will
414  define a hook of arity 2 --- that is, the procedures stored in the hook  define a hook of arity 2 --- that is, the procedures stored in the hook
# Line 409  hook Line 423  hook
423  Now we are ready to add some procedures to the newly created hook with  Now we are ready to add some procedures to the newly created hook with
424  @code{add-hook!}.  In the following example, two procedures are added,  @code{add-hook!}.  In the following example, two procedures are added,
425  which print different messages and do different things with their  which print different messages and do different things with their
426  arguments.  When the procedures have been added, we can invoke them  arguments.
 using @code{run-hook}.  
427    
428  @lisp  @lisp
429  (add-hook! hook (lambda (x y)  (add-hook! hook (lambda (x y)
# Line 421  using @code{run-hook}. Line 434  using @code{run-hook}.
434                      (display "Bar: ")                      (display "Bar: ")
435                      (display (* x y))                      (display (* x y))
436                      (newline)))                      (newline)))
437    @end lisp
438    
439    Once the procedures have been added, we can invoke the hook using
440    @code{run-hook}.
441    
442    @lisp
443  (run-hook hook 3 4)  (run-hook hook 3 4)
444  @print{} Bar: 12  @print{} Bar: 12
445  @print{} Foo: 7  @print{} Foo: 7
446  @end lisp  @end lisp
447    
448  Note that the procedures are called in reverse order than they were  Note that the procedures are called in the reverse of the order with
449  added.  This can be changed by providing the optional third argument  which they were added.  This is because the default behaviour of
450  on the second call to @code{add-hook!}.  @code{add-hook!} is to add its procedure to the @emph{front} of the
451    hook's procedure list.  You can force @code{add-hook!} to add its
452    procedure to the @emph{end} of the list instead by providing a third
453    @code{#t} argument on the second call to @code{add-hook!}.
454    
455  @lisp  @lisp
456  (add-hook! hook (lambda (x y)  (add-hook! hook (lambda (x y)
# Line 439  on the second call to @code{add-hook!}. Line 461  on the second call to @code{add-hook!}.
461                      (display "Bar: ")                      (display "Bar: ")
462                      (display (* x y))                      (display (* x y))
463                      (newline))                      (newline))
464                      #t)   ; @r{<- Change here!}                      #t)             ; @r{<- Change here!}
465    
466  (run-hook hook 3 4)  (run-hook hook 3 4)
467  @print{} Foo: 7  @print{} Foo: 7
468  @print{} Bar: 12  @print{} Bar: 12
469  @end lisp  @end lisp
470    
471    
472  @node Hook Reference  @node Hook Reference
473  @subsection Hook Reference  @subsection Hook Reference
474    
475  When a hook is created with @code{make-hook}, you can supply the arity  When you create a hook with @code{make-hook}, you must specify the arity
476  of the procedures which can be added to the hook.  The arity defaults to  of the procedures which can be added to the hook.  If the arity is not
477  zero.  All procedures of a hook must have the same arity, and when the  given explicitly as an argument to @code{make-hook}, it defaults to
478  procedures are invoked using @code{run-hook}, the number of arguments  zero.  All procedures of a given hook must have the same arity, and when
479  must match the arity of the procedures.  the procedures are invoked using @code{run-hook}, the number of
480    arguments passed must match the arity specified at hook creation time.
481    
482  The order in which procedures are added to a hook matters.  If the third  The order in which procedures are added to a hook matters.  If the third
483  parameter to @var{add-hook!} is omitted or is equal to @code{#f}, the  parameter to @code{add-hook!} is omitted or is equal to @code{#f}, the
484  procedure is added in front of the procedures which might already be on  procedure is added in front of the procedures which might already be on
485  that hook, otherwise the procedure is added at the end.  The procedures  that hook, otherwise the procedure is added at the end.  The procedures
486  are always called from first to last when they are invoked via  are always called from the front to the end of the list when they are
487  @code{run-hook}.  invoked via @code{run-hook}.
488    
489  When calling @code{hook->list}, the procedures in the resulting list are  The ordering of the list of procedures returned by @code{hook->list}
490  in the same order as they would have been called by @code{run-hook}.  matches the order in which those procedures would be called if the hook
491    was run using @code{run-hook}.
492    
493  @deffn {Scheme Procedure} make-hook [n_args]  @deffn {Scheme Procedure} make-hook [n_args]
494  @deffnx {C Function} scm_make_hook (n_args)  @deffnx {C Function} scm_make_hook (n_args)
# Line 502  Remove all procedures from the hook @var Line 528  Remove all procedures from the hook @var
528  value of this procedure is not specified.  value of this procedure is not specified.
529  @end deffn  @end deffn
530    
531    @deffn {Scheme Procedure} hook->list hook
532    @deffnx {C Function} scm_hook_to_list (hook)
533    Convert the procedure list of @var{hook} to a list.
534    @end deffn
535    
536  @deffn {Scheme Procedure} run-hook hook . args  @deffn {Scheme Procedure} run-hook hook . args
537  @deffnx {C Function} scm_run_hook (hook, args)  @deffnx {C Function} scm_run_hook (hook, args)
538  Apply all procedures from the hook @var{hook} to the arguments  Apply all procedures from the hook @var{hook} to the arguments
# Line 509  Apply all procedures from the hook @var{ Line 540  Apply all procedures from the hook @var{
540  last.  The return value of this procedure is not specified.  last.  The return value of this procedure is not specified.
541  @end deffn  @end deffn
542    
543  @deffn {Scheme Procedure} hook->list hook  If, in C code, you are certain that you have a hook object and well
544  @deffnx {C Function} scm_hook_to_list (hook)  formed argument list for that hook, you can also use
545  Convert the procedure list of @var{hook} to a list.  @code{scm_c_run_hook}, which is identical to @code{scm_run_hook} but
546    does no type checking.
547    
548    @deftypefn {C Function} void scm_c_run_hook (SCM hook, SCM args)
549    The same as @code{scm_run_hook} but without any type checking to confirm
550    that @var{hook} is actually a hook object and that @var{args} is a
551    well-formed list matching the arity of the hook.
552    @end deftypefn
553    
554    
555    @node C Hooks
556    @subsection Hooks For C Code.
557    
558    The hooks already described are intended to be populated by Scheme-level
559    procedures.  In addition to this, the Guile library provides an
560    independent set of interfaces for the creation and manipulation of hooks
561    that are designed to be populated by functions implemented in C.
562    
563    The original motivation here was to provide a kind of hook that could
564    safely be invoked at various points during garbage collection.
565    Scheme-level hooks are unsuitable for this purpose as running them could
566    itself require memory allocation, which would then invoke garbage
567    collection recursively @dots{}  However, it is also the case that these
568    hooks are easier to work with than the Scheme-level ones if you only
569    want to register C functions with them.  So if that is mainly what your
570    code needs to do, you may prefer to use this interface.
571    
572    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}.
574    
575    @deffn {C Type} scm_t_c_hook
576    Data type for a C hook.  The internals of this type should be treated as
577    opaque.
578  @end deffn  @end deffn
579    
580    @deffn {C Enum} scm_t_c_hook_type
581    Enumeration of possible hook types, which are:
582    
583    @table @code
584    @item SCM_C_HOOK_NORMAL
585    Type of hook for which all the registered functions will always be called.
586    @item SCM_C_HOOK_OR
587    Type of hook for which the sequence of registered functions will be
588    called only until one of them returns C true (a non-NULL pointer).
589    @item SCM_C_HOOK_AND
590    Type of hook for which the sequence of registered functions will be
591    called only until one of them returns C false (a NULL pointer).
592    @end table
593    @end deffn
594    
595    @deftypefn {C Function} void scm_c_hook_init (scm_t_c_hook *hook, void *hook_data, scm_t_c_hook_type type)
596    Initialize the C hook at memory pointed to by @var{hook}.  @var{type}
597    should be one of the values of the @code{scm_t_c_hook_type} enumeration,
598    and controls how the hook functions will be called.  @var{hook_data} is
599    a closure parameter that will be passed to all registered hook functions
600    when they are called.
601    @end deftypefn
602    
603    To add or remove a C function from a C hook, use @code{scm_c_hook_add}
604    or @code{scm_c_hook_remove}.  A hook function must expect three
605    @code{void *} parameters which are, respectively:
606    
607    @table @var
608    @item hook_data
609    The hook closure data that was specified at the time the hook was
610    initialized by @code{scm_c_hook_init}.
611    
612    @item func_data
613    The function closure data that was specified at the time that that
614    function was registered with the hook by @code{scm_c_hook_add}.
615    
616    @item data
617    The call closure data specified by the @code{scm_c_hook_run} call that
618    runs the hook.
619    @end table
620    
621    @deffn {C Type} scm_t_c_hook_function
622    Function type for a C hook function: takes three @code{void *}
623    parameters and returns a @code{void *} result.
624    @end deffn
625    
626    @deftypefn {C Function} void scm_c_hook_add (scm_t_c_hook *hook, scm_t_c_hook_function func, void *func_data, int appendp)
627    Add function @var{func}, with function closure data @var{func_data}, to
628    the C hook @var{hook}.  The new function is appended to the hook's list
629    of functions if @var{appendp} is non-zero, otherwise prepended.
630    @end deftypefn
631    
632    @deftypefn {C Function} void scm_c_hook_remove (scm_t_c_hook *hook, scm_t_c_hook_function func, void *func_data)
633    Remove function @var{func}, with function closure data @var{func_data},
634    from the C hook @var{hook}.  @code{scm_c_hook_remove} checks both
635    @var{func} and @var{func_data} so as to allow for the same @var{func}
636    being registered multiple times with different closure data.
637    @end deftypefn
638    
639    Finally, to invoke a C hook, call the @code{scm_c_hook_run} function
640    specifying the hook and the call closure data for this run:
641    
642    @deftypefn {C Function} void * scm_c_hook_run (scm_t_c_hook *hook, void *data)
643    Run the C hook @var{hook} will call closure data @var{data}.  Subject to
644    the variations for hook types @code{SCM_C_HOOK_OR} and
645    @code{SCM_C_HOOK_AND}, @code{scm_c_hook_run} calls @var{hook}'s
646    registered functions in turn, passing them the hook's closure data, each
647    function's closure data, and the call closure data.
648    
649    @code{scm_c_hook_run}'s return value is the return value of the last
650    function to be called.
651    @end deftypefn
652    
653    
654    @node Guile Hooks
655    @subsection Hooks Provided by Guile
656    
657    @table @code
658    @item scm_before_gc_c_hook
659    @item scm_before_mark_c_hook
660    @item scm_before_sweep_c_hook
661    @item scm_after_sweep_c_hook
662    @item scm_after_gc_c_hook
663    @end table
664    
665    
666  @c Local Variables:  @c Local Variables:
667  @c TeX-master: "guile.texi"  @c TeX-master: "guile.texi"

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

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