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