6.11.6.4 Hooks for Garbage Collection

Whenever Guile performs a garbage collection, it calls the following hooks in the order shown.

C Hook: scm_before_gc_c_hook

C hook called at the very start of a garbage collection, after setting scm_gc_running_p to 1, but before entering the GC critical section.

If garbage collection is blocked because scm_block_gc is non-zero, GC exits early soon after calling this hook, and no further hooks will be called.

C Hook: scm_before_mark_c_hook

C hook called before beginning the mark phase of garbage collection, after the GC thread has entered a critical section.

C Hook: scm_before_sweep_c_hook

C hook called before beginning the sweep phase of garbage collection. This is the same as at the end of the mark phase, since nothing else happens between marking and sweeping.

C Hook: scm_after_sweep_c_hook

C hook called after the end of the sweep phase of garbage collection, but while the GC thread is still inside its critical section.

C Hook: scm_after_gc_c_hook

C hook called at the very end of a garbage collection, after the GC thread has left its critical section.

Scheme Hook: after-gc-hook

Scheme hook with arity 0. This hook is run asynchronously (see Asyncs) soon after the GC has completed and any other events that were deferred during garbage collection have been processed. (Also accessible from C with the name scm_after_gc_hook.)

All the C hooks listed here have type SCM_C_HOOK_NORMAL, are initialized with hook closure data NULL, are invoked by scm_c_hook_run with call closure data NULL.

The Scheme hook after-gc-hook is particularly useful in conjunction with guardians (see Guardians). Typically, if you are using a guardian, you want to call the guardian after garbage collection to see if any of the objects added to the guardian have been collected. By adding a thunk that performs this call to after-gc-hook, you can ensure that your guardian is tested after every garbage collection cycle.