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} |
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 |
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: |