2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
8 @node Utility Functions
9 @chapter General Utility Functions
11 @c FIXME::martin: Review me!
13 This chapter contains information about procedures which are not cleanly
14 tied to a specific data type. Because of their wide range of
15 applications, they are collected in a @dfn{utility} chapter.
18 * Equality:: When are two values `the same'?
19 * Object Properties:: A modern interface to object properties.
20 * Sorting:: Sort utility procedures.
21 * Copying:: Copying deep structures.
22 * General Conversion:: Converting objects to strings.
23 * Hooks:: User-customizable event lists.
30 @c FIXME::martin: Review me!
35 Three different kinds of @dfn{sameness} are defined in Scheme.
39 Two values can refer to exactly the same object.
42 Two objects can have the same @dfn{value}.
45 Two objects can be structurally equivalent.
48 The differentiation between these three kinds is important, because
49 determining whether two values are the same objects is very efficient,
50 while determining structural equivalence can be quite expensive
51 (consider comparing two very long lists). Therefore, three different
52 procedures for testing for equality are provided, which correspond to
53 the three kinds of @dfn{sameness} defined above.
56 @deffn {Scheme Procedure} eq? x y
57 Return @code{#t} iff @var{x} references the same object as @var{y}.
58 @code{eq?} is similar to @code{eqv?} except that in some cases it is
59 capable of discerning distinctions finer than those detectable by
64 @deffn {Scheme Procedure} eqv? x y
65 The @code{eqv?} procedure defines a useful equivalence relation on objects.
66 Briefly, it returns @code{#t} if @var{x} and @var{y} should normally be
67 regarded as the same object. This relation is left slightly open to
68 interpretation, but works for comparing immediate integers, characters,
73 @deffn {Scheme Procedure} equal? x y
74 Return @code{#t} iff @var{x} and @var{y} are recursively @code{eqv?} equivalent.
75 @code{equal?} recursively compares the contents of pairs,
76 vectors, and strings, applying @code{eqv?} on other objects such as
77 numbers and symbols. A rule of thumb is that objects are generally
78 @code{equal?} if they print the same. @code{equal?} may fail to
79 terminate if its arguments are circular data structures.
83 @node Object Properties
84 @section Object Properties
86 It's often useful to associate a piece of additional information with a
87 Scheme object even though that object does not have a dedicated slot
88 available in which the additional information could be stored. Object
89 properties allow you to do just that.
91 An object property is most commonly used to associate one kind of
92 additional information with each instance of a class of similar Scheme
93 objects. For example, all procedures have a `name' property, which
94 stores the name of the variable in which the procedure was stored by a
95 @code{define} expression, or @code{#f} if the procedure wasn't created
96 by that kind of expression.
98 Guile's representation of an object property is a procedure-with-setter
99 (@pxref{Procedures with Setters}) that can be used with the generalized
100 form of @code{set!} (REFFIXME) to set and retrieve that property for any
101 Scheme object. So, setting a property looks like this:
104 (set! (my-property obj1) value-for-obj1)
105 (set! (my-property obj2) value-for-obj2)
109 And retrieving values of the same property looks like this:
121 To create an object property in the first place, use the
122 @code{make-object-property} procedure:
125 (define my-property (make-object-property))
128 @deffn {Scheme Procedure} make-object-property
129 Create and return an object property. An object property is a
130 procedure-with-setter that can be called in two ways. @code{(set!
131 (@var{property} @var{obj}) @var{val})} sets @var{obj}'s @var{property}
132 to @var{val}. @code{(@var{property} @var{obj})} returns the current
133 setting of @var{obj}'s @var{property}.
136 A single object property created by @code{make-object-property} can
137 associate distinct property values with all Scheme values that are
138 distinguishable by @code{eq?} (including, for example, integers).
140 Internally, object properties are implemented using a weak key hash
141 table. This means that, as long as a Scheme value with property values
142 is protected from garbage collection, its property values are also
143 protected. When the Scheme value is collected, its entry in the
144 property table is removed and so the (ex-) property values are no longer
145 protected by the table.
148 * Property Primitives:: Low level property implementation.
149 * Old-fashioned Properties:: An older approach to properties.
153 @node Property Primitives
154 @subsection Low Level Property Implementation.
156 @deffn {Scheme Procedure} primitive-make-property not-found-proc
157 @deffnx {C Function} scm_primitive_make_property (not_found_proc)
158 Create a @dfn{property token} that can be used with
159 @code{primitive-property-ref} and @code{primitive-property-set!}.
160 See @code{primitive-property-ref} for the significance of
161 @var{not-found-proc}.
164 @deffn {Scheme Procedure} primitive-property-ref prop obj
165 @deffnx {C Function} scm_primitive_property_ref (prop, obj)
166 Return the property @var{prop} of @var{obj}.
168 When no value has yet been associated with @var{prop} and @var{obj},
169 the @var{not-found-proc} from @var{prop} is used. A call
170 @code{(@var{not-found-proc} @var{prop} @var{obj})} is made and the
171 result set as the property value. If @var{not-found-proc} is
172 @code{#f} then @code{#f} is the property value.
175 @deffn {Scheme Procedure} primitive-property-set! prop obj val
176 @deffnx {C Function} scm_primitive_property_set_x (prop, obj, val)
177 Set the property @var{prop} of @var{obj} to @var{val}.
180 @deffn {Scheme Procedure} primitive-property-del! prop obj
181 @deffnx {C Function} scm_primitive_property_del_x (prop, obj)
182 Remove any value associated with @var{prop} and @var{obj}.
186 @node Old-fashioned Properties
187 @subsection An Older Approach to Properties
189 Traditionally, Lisp systems provide a different object property
190 interface to that provided by @code{make-object-property}, in which the
191 object property that is being set or retrieved is indicated by a symbol.
193 Guile includes this older kind of interface as well, but it may well be
194 removed in a future release, as it is less powerful than
195 @code{make-object-property} and so increases the size of the Guile
196 library for no benefit. (And it is trivial to write a compatibility
199 @deffn {Scheme Procedure} object-properties obj
200 @deffnx {C Function} scm_object_properties (obj)
201 Return @var{obj}'s property list.
204 @deffn {Scheme Procedure} set-object-properties! obj alist
205 @deffnx {C Function} scm_set_object_properties_x (obj, alist)
206 Set @var{obj}'s property list to @var{alist}.
209 @deffn {Scheme Procedure} object-property obj key
210 @deffnx {C Function} scm_object_property (obj, key)
211 Return the property of @var{obj} with name @var{key}.
214 @deffn {Scheme Procedure} set-object-property! obj key value
215 @deffnx {C Function} scm_set_object_property_x (obj, key, value)
216 In @var{obj}'s property list, set the property named @var{key}
224 @c FIXME::martin: Review me!
227 @cindex sorting lists
228 @cindex sorting vectors
230 Sorting is very important in computer programs. Therefore, Guile comes
231 with several sorting procedures built-in. As always, procedures with
232 names ending in @code{!} are side-effecting, that means that they may
233 modify their parameters in order to produce their results.
235 The first group of procedures can be used to merge two lists (which must
236 be already sorted on their own) and produce sorted lists containing
237 all elements of the input lists.
239 @deffn {Scheme Procedure} merge alist blist less
240 @deffnx {C Function} scm_merge (alist, blist, less)
241 Merge two already sorted lists into one.
242 Given two lists @var{alist} and @var{blist}, such that
243 @code{(sorted? alist less?)} and @code{(sorted? blist less?)},
244 return a new list in which the elements of @var{alist} and
245 @var{blist} have been stably interleaved so that
246 @code{(sorted? (merge alist blist less?) less?)}.
247 Note: this does _not_ accept vectors.
250 @deffn {Scheme Procedure} merge! alist blist less
251 @deffnx {C Function} scm_merge_x (alist, blist, less)
252 Takes two lists @var{alist} and @var{blist} such that
253 @code{(sorted? alist less?)} and @code{(sorted? blist less?)} and
254 returns a new list in which the elements of @var{alist} and
255 @var{blist} have been stably interleaved so that
256 @code{(sorted? (merge alist blist less?) less?)}.
257 This is the destructive variant of @code{merge}
258 Note: this does _not_ accept vectors.
261 The following procedures can operate on sequences which are either
262 vectors or list. According to the given arguments, they return sorted
263 vectors or lists, respectively. The first of the following procedures
264 determines whether a sequence is already sorted, the other sort a given
265 sequence. The variants with names starting with @code{stable-} are
266 special in that they maintain a special property of the input sequences:
267 If two or more elements are the same according to the comparison
268 predicate, they are left in the same order as they appeared in the
271 @deffn {Scheme Procedure} sorted? items less
272 @deffnx {C Function} scm_sorted_p (items, less)
273 Return @code{#t} iff @var{items} is a list or a vector such that
274 for all 1 <= i <= m, the predicate @var{less} returns true when
275 applied to all elements i - 1 and i
278 @deffn {Scheme Procedure} sort items less
279 @deffnx {C Function} scm_sort (items, less)
280 Sort the sequence @var{items}, which may be a list or a
281 vector. @var{less} is used for comparing the sequence
282 elements. This is not a stable sort.
285 @deffn {Scheme Procedure} sort! items less
286 @deffnx {C Function} scm_sort_x (items, less)
287 Sort the sequence @var{items}, which may be a list or a
288 vector. @var{less} is used for comparing the sequence
289 elements. The sorting is destructive, that means that the
290 input sequence is modified to produce the sorted result.
291 This is not a stable sort.
294 @deffn {Scheme Procedure} stable-sort items less
295 @deffnx {C Function} scm_stable_sort (items, less)
296 Sort the sequence @var{items}, which may be a list or a
297 vector. @var{less} is used for comparing the sequence elements.
298 This is a stable sort.
301 @deffn {Scheme Procedure} stable-sort! items less
302 @deffnx {C Function} scm_stable_sort_x (items, less)
303 Sort the sequence @var{items}, which may be a list or a
304 vector. @var{less} is used for comparing the sequence elements.
305 The sorting is destructive, that means that the input sequence
306 is modified to produce the sorted result.
307 This is a stable sort.
310 The procedures in the last group only accept lists or vectors as input,
311 as their names indicate.
313 @deffn {Scheme Procedure} sort-list items less
314 @deffnx {C Function} scm_sort_list (items, less)
315 Sort the list @var{items}, using @var{less} for comparing the
316 list elements. This is a stable sort.
319 @deffn {Scheme Procedure} sort-list! items less
320 @deffnx {C Function} scm_sort_list_x (items, less)
321 Sort the list @var{items}, using @var{less} for comparing the
322 list elements. The sorting is destructive, that means that the
323 input list is modified to produce the sorted result.
324 This is a stable sort.
327 @deffn {Scheme Procedure} restricted-vector-sort! vec less startpos endpos
328 @deffnx {C Function} scm_restricted_vector_sort_x (vec, less, startpos, endpos)
329 Sort the vector @var{vec}, using @var{less} for comparing
330 the vector elements. @var{startpos} and @var{endpos} delimit
331 the range of the vector which gets sorted. The return value
337 @section Copying Deep Structures
339 @c FIXME::martin: Review me!
341 The procedures for copying lists (@pxref{Lists}) only produce a flat
342 copy of the input list, and currently Guile does not even contain
343 procedures for copying vectors. @code{copy-tree} can be used for these
344 application, as it does not only copy the spine of a list, but also
345 copies any pairs in the cars of the input lists.
347 @deffn {Scheme Procedure} copy-tree obj
348 @deffnx {C Function} scm_copy_tree (obj)
349 Recursively copy the data tree that is bound to @var{obj}, and return a
350 pointer to the new data structure. @code{copy-tree} recurses down the
351 contents of both pairs and vectors (since both cons cells and vector
352 cells may point to arbitrary objects), and stops recursing when it hits
357 @node General Conversion
358 @section General String Conversion
360 @c FIXME::martin: Review me!
362 When debugging Scheme programs, but also for providing a human-friendly
363 interface, a procedure for converting any Scheme object into string
364 format is very useful. Conversion from/to strings can of course be done
365 with specialized procedures when the data type of the object to convert
366 is known, but with this procedure, it is often more comfortable.
368 @code{object->string} converts an object by using a print procedure for
369 writing to a string port, and then returning the resulting string.
370 Converting an object back from the string is only possible if the object
371 type has a read syntax and the read syntax is preserved by the printing
374 @deffn {Scheme Procedure} object->string obj [printer]
375 @deffnx {C Function} scm_object_to_string (obj, printer)
376 Return a Scheme string obtained by printing @var{obj}.
377 Printing function can be specified by the optional second
378 argument @var{printer} (default: @code{write}).
386 A hook is a list of procedures to be called at well defined points in
387 time. Typically, an application provides a hook @var{h} and promises
388 its users that it will call all of the procedures in @var{h} at a
389 defined point in the application's processing. By adding its own
390 procedure to @var{h}, an application user can tap into or even influence
391 the progress of the application.
393 Guile itself provides several such hooks for debugging and customization
394 purposes: these are listed in a subsection below.
396 When an application first creates a hook, it needs to know how many
397 arguments will be passed to the hook's procedures when the hook is run.
398 The chosen number of arguments (which may be none) is declared when the
399 hook is created, and all the procedures that are added to that hook must
400 be capable of accepting that number of arguments.
402 A hook is created using @code{make-hook}. A procedure can be added to
403 or removed from a hook using @code{add-hook!} or @code{remove-hook!},
404 and all of a hook's procedures can be removed together using
405 @code{reset-hook!}. When an application wants to run a hook, it does so
406 using @code{run-hook}.
409 * Hook Example:: Hook usage by example.
410 * Hook Reference:: Reference of all hook procedures.
411 * C Hooks:: Hooks for use from C code.
412 * Guile Hooks:: Hooks provided by Guile.
417 @subsection Hook Usage by Example
419 Hook usage is shown by some examples in this section. First, we will
420 define a hook of arity 2 --- that is, the procedures stored in the hook
421 will have to accept two arguments.
424 (define hook (make-hook 2))
426 @result{} #<hook 2 40286c90>
429 Now we are ready to add some procedures to the newly created hook with
430 @code{add-hook!}. In the following example, two procedures are added,
431 which print different messages and do different things with their
435 (add-hook! hook (lambda (x y)
439 (add-hook! hook (lambda (x y)
445 Once the procedures have been added, we can invoke the hook using
454 Note that the procedures are called in the reverse of the order with
455 which they were added. This is because the default behaviour of
456 @code{add-hook!} is to add its procedure to the @emph{front} of the
457 hook's procedure list. You can force @code{add-hook!} to add its
458 procedure to the @emph{end} of the list instead by providing a third
459 @code{#t} argument on the second call to @code{add-hook!}.
462 (add-hook! hook (lambda (x y)
466 (add-hook! hook (lambda (x y)
470 #t) ; @r{<- Change here!}
479 @subsection Hook Reference
481 When you create a hook with @code{make-hook}, you must specify the arity
482 of the procedures which can be added to the hook. If the arity is not
483 given explicitly as an argument to @code{make-hook}, it defaults to
484 zero. All procedures of a given hook must have the same arity, and when
485 the procedures are invoked using @code{run-hook}, the number of
486 arguments passed must match the arity specified at hook creation time.
488 The order in which procedures are added to a hook matters. If the third
489 parameter to @code{add-hook!} is omitted or is equal to @code{#f}, the
490 procedure is added in front of the procedures which might already be on
491 that hook, otherwise the procedure is added at the end. The procedures
492 are always called from the front to the end of the list when they are
493 invoked via @code{run-hook}.
495 The ordering of the list of procedures returned by @code{hook->list}
496 matches the order in which those procedures would be called if the hook
497 was run using @code{run-hook}.
499 Note that the C functions in the following entries are for handling
500 @dfn{Scheme-level} hooks in C. There are also @dfn{C-level} hooks which
501 have their own interface (@pxref{C Hooks}).
503 @deffn {Scheme Procedure} make-hook [n_args]
504 @deffnx {C Function} scm_make_hook (n_args)
505 Create a hook for storing procedure of arity @var{n_args}.
506 @var{n_args} defaults to zero. The returned value is a hook
507 object to be used with the other hook procedures.
510 @deffn {Scheme Procedure} hook? x
511 @deffnx {C Function} scm_hook_p (x)
512 Return @code{#t} if @var{x} is a hook, @code{#f} otherwise.
515 @deffn {Scheme Procedure} hook-empty? hook
516 @deffnx {C Function} scm_hook_empty_p (hook)
517 Return @code{#t} if @var{hook} is an empty hook, @code{#f}
521 @deffn {Scheme Procedure} add-hook! hook proc [append_p]
522 @deffnx {C Function} scm_add_hook_x (hook, proc, append_p)
523 Add the procedure @var{proc} to the hook @var{hook}. The
524 procedure is added to the end if @var{append_p} is true,
525 otherwise it is added to the front. The return value of this
526 procedure is not specified.
529 @deffn {Scheme Procedure} remove-hook! hook proc
530 @deffnx {C Function} scm_remove_hook_x (hook, proc)
531 Remove the procedure @var{proc} from the hook @var{hook}. The
532 return value of this procedure is not specified.
535 @deffn {Scheme Procedure} reset-hook! hook
536 @deffnx {C Function} scm_reset_hook_x (hook)
537 Remove all procedures from the hook @var{hook}. The return
538 value of this procedure is not specified.
541 @deffn {Scheme Procedure} hook->list hook
542 @deffnx {C Function} scm_hook_to_list (hook)
543 Convert the procedure list of @var{hook} to a list.
546 @deffn {Scheme Procedure} run-hook hook . args
547 @deffnx {C Function} scm_run_hook (hook, args)
548 Apply all procedures from the hook @var{hook} to the arguments
549 @var{args}. The order of the procedure application is first to
550 last. The return value of this procedure is not specified.
553 If, in C code, you are certain that you have a hook object and well
554 formed argument list for that hook, you can also use
555 @code{scm_c_run_hook}, which is identical to @code{scm_run_hook} but
556 does no type checking.
558 @deftypefn {C Function} void scm_c_run_hook (SCM hook, SCM args)
559 The same as @code{scm_run_hook} but without any type checking to confirm
560 that @var{hook} is actually a hook object and that @var{args} is a
561 well-formed list matching the arity of the hook.
564 For C code, @code{SCM_HOOKP} is a faster alternative to
567 @deftypefn {C Macro} int SCM_HOOKP (x)
568 Return 1 if @var{x} is a Scheme-level hook, 0 otherwise.
572 @subsection Handling Scheme-level hooks from C code
574 Here is an example of how to handle Scheme-level hooks from C code using
578 if (SCM_NFALSEP (scm_hook_p (obj)))
579 /* handle Scheme-level hook using C functions */
580 scm_reset_hook_x (obj);
582 /* do something else (obj is not a hook) */
587 @subsection Hooks For C Code.
589 The hooks already described are intended to be populated by Scheme-level
590 procedures. In addition to this, the Guile library provides an
591 independent set of interfaces for the creation and manipulation of hooks
592 that are designed to be populated by functions implemented in C.
594 The original motivation here was to provide a kind of hook that could
595 safely be invoked at various points during garbage collection.
596 Scheme-level hooks are unsuitable for this purpose as running them could
597 itself require memory allocation, which would then invoke garbage
598 collection recursively @dots{} However, it is also the case that these
599 hooks are easier to work with than the Scheme-level ones if you only
600 want to register C functions with them. So if that is mainly what your
601 code needs to do, you may prefer to use this interface.
603 To create a C hook, you should allocate storage for a structure of type
604 @code{scm_t_c_hook} and then initialize it using @code{scm_c_hook_init}.
606 @deftp {C Type} scm_t_c_hook
607 Data type for a C hook. The internals of this type should be treated as
611 @deftp {C Enum} scm_t_c_hook_type
612 Enumeration of possible hook types, which are:
615 @item SCM_C_HOOK_NORMAL
616 @vindex SCM_C_HOOK_NORMAL
617 Type of hook for which all the registered functions will always be called.
619 @vindex SCM_C_HOOK_OR
620 Type of hook for which the sequence of registered functions will be
621 called only until one of them returns C true (a non-NULL pointer).
623 @vindex SCM_C_HOOK_AND
624 Type of hook for which the sequence of registered functions will be
625 called only until one of them returns C false (a NULL pointer).
629 @deftypefn {C Function} void scm_c_hook_init (scm_t_c_hook *hook, void *hook_data, scm_t_c_hook_type type)
630 Initialize the C hook at memory pointed to by @var{hook}. @var{type}
631 should be one of the values of the @code{scm_t_c_hook_type} enumeration,
632 and controls how the hook functions will be called. @var{hook_data} is
633 a closure parameter that will be passed to all registered hook functions
634 when they are called.
637 To add or remove a C function from a C hook, use @code{scm_c_hook_add}
638 or @code{scm_c_hook_remove}. A hook function must expect three
639 @code{void *} parameters which are, respectively:
643 The hook closure data that was specified at the time the hook was
644 initialized by @code{scm_c_hook_init}.
647 The function closure data that was specified at the time that that
648 function was registered with the hook by @code{scm_c_hook_add}.
651 The call closure data specified by the @code{scm_c_hook_run} call that
655 @deftp {C Type} scm_t_c_hook_function
656 Function type for a C hook function: takes three @code{void *}
657 parameters and returns a @code{void *} result.
660 @deftypefn {C Function} void scm_c_hook_add (scm_t_c_hook *hook, scm_t_c_hook_function func, void *func_data, int appendp)
661 Add function @var{func}, with function closure data @var{func_data}, to
662 the C hook @var{hook}. The new function is appended to the hook's list
663 of functions if @var{appendp} is non-zero, otherwise prepended.
666 @deftypefn {C Function} void scm_c_hook_remove (scm_t_c_hook *hook, scm_t_c_hook_function func, void *func_data)
667 Remove function @var{func}, with function closure data @var{func_data},
668 from the C hook @var{hook}. @code{scm_c_hook_remove} checks both
669 @var{func} and @var{func_data} so as to allow for the same @var{func}
670 being registered multiple times with different closure data.
673 Finally, to invoke a C hook, call the @code{scm_c_hook_run} function
674 specifying the hook and the call closure data for this run:
676 @deftypefn {C Function} {void *} scm_c_hook_run (scm_t_c_hook *hook, void *data)
677 Run the C hook @var{hook} will call closure data @var{data}. Subject to
678 the variations for hook types @code{SCM_C_HOOK_OR} and
679 @code{SCM_C_HOOK_AND}, @code{scm_c_hook_run} calls @var{hook}'s
680 registered functions in turn, passing them the hook's closure data, each
681 function's closure data, and the call closure data.
683 @code{scm_c_hook_run}'s return value is the return value of the last
684 function to be called.
689 @subsection Hooks Provided by Guile
692 * GC Hooks:: Garbage collection hooks.
693 * REPL Hooks:: Hooks into the Guile REPL.
698 @subsubsection Hooks for Garbage Collection
700 Whenever Guile performs a garbage collection, it calls the following
701 hooks in the order shown.
703 @defvr {C Hook} scm_before_gc_c_hook
704 C hook called at the very start of a garbage collection, after setting
705 @code{scm_gc_running_p} to 1, but before entering the GC critical
708 If garbage collection is blocked because @code{scm_block_gc} is
709 non-zero, GC exits early soon after calling this hook, and no further
710 hooks will be called.
713 @defvr {C Hook} scm_before_mark_c_hook
714 C hook called before beginning the mark phase of garbage collection,
715 after the GC thread has entered a critical section.
718 @defvr {C Hook} scm_before_sweep_c_hook
719 C hook called before beginning the sweep phase of garbage collection.
720 This is the same as at the end of the mark phase, since nothing else
721 happens between marking and sweeping.
724 @defvr {C Hook} scm_after_sweep_c_hook
725 C hook called after the end of the sweep phase of garbage collection,
726 but while the GC thread is still inside its critical section.
729 @defvr {C Hook} scm_after_gc_c_hook
730 C hook called at the very end of a garbage collection, after the GC
731 thread has left its critical section.
734 @defvr {Scheme Hook} after-gc-hook
735 @vindex scm_after_gc_hook
736 Scheme hook with arity 0. This hook is run asynchronously
737 (@pxref{Asyncs}) soon after the GC has completed and any other events
738 that were deferred during garbage collection have been processed. (Also
739 accessible from C with the name @code{scm_after_gc_hook}.)
742 All the C hooks listed here have type @code{SCM_C_HOOK_NORMAL}, are
743 initialized with hook closure data NULL, are are invoked by
744 @code{scm_c_hook_run} with call closure data NULL.
746 @cindex guardians, testing for GC'd objects
747 The Scheme hook @code{after-gc-hook} is particularly useful in
748 conjunction with guardians (@pxref{Guardians}). Typically, if you are
749 using a guardian, you want to call the guardian after garbage collection
750 to see if any of the objects added to the guardian have been collected.
751 By adding a thunk that performs this call to @code{after-gc-hook}, you
752 can ensure that your guardian is tested after every garbage collection
757 @subsubsection Hooks into the Guile REPL
761 @c TeX-master: "guile.texi"