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 @section 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 @deffnx {C Function} scm_eq_p (x, y)
58 Return @code{#t} iff @var{x} references the same object as @var{y}.
59 @code{eq?} is similar to @code{eqv?} except that in some cases it is
60 capable of discerning distinctions finer than those detectable by
64 @deftypefn {C Function} int scm_is_eq (SCM x, SCM y)
65 Return @code{1} when @var{x} and @var{y} are equal in the sense of
66 @code{eq?}, else return @code{0}.
70 @deffn {Scheme Procedure} eqv? x y
71 @deffnx {C Function} scm_eqv_p (x, y)
72 The @code{eqv?} procedure defines a useful equivalence relation on objects.
73 Briefly, it returns @code{#t} if @var{x} and @var{y} should normally be
74 regarded as the same object. This relation is left slightly open to
75 interpretation, but works for comparing immediate integers, characters,
80 @deffn {Scheme Procedure} equal? x y
81 @deffnx {C Function} scm_equal_p (x, y)
82 Return @code{#t} iff @var{x} and @var{y} are recursively @code{eqv?}
83 equivalent. @code{equal?} recursively compares the contents of pairs,
84 vectors, and strings, applying @code{eqv?} on other objects such as
85 numbers and symbols. A rule of thumb is that objects are generally
86 @code{equal?} if they print the same. @code{equal?} may fail to
87 terminate if its arguments are circular data structures.
91 @node Object Properties
92 @subsection Object Properties
94 It's often useful to associate a piece of additional information with a
95 Scheme object even though that object does not have a dedicated slot
96 available in which the additional information could be stored. Object
97 properties allow you to do just that.
99 An object property is most commonly used to associate one kind of
100 additional information with each instance of a class of similar Scheme
101 objects. For example, all procedures have a `name' property, which
102 stores the name of the variable in which the procedure was stored by a
103 @code{define} expression, or @code{#f} if the procedure wasn't created
104 by that kind of expression.
106 Guile's representation of an object property is a procedure-with-setter
107 (@pxref{Procedures with Setters}) that can be used with the generalized
108 form of @code{set!} (REFFIXME) to set and retrieve that property for any
109 Scheme object. So, setting a property looks like this:
112 (set! (my-property obj1) value-for-obj1)
113 (set! (my-property obj2) value-for-obj2)
117 And retrieving values of the same property looks like this:
129 To create an object property in the first place, use the
130 @code{make-object-property} procedure:
133 (define my-property (make-object-property))
136 @deffn {Scheme Procedure} make-object-property
137 Create and return an object property. An object property is a
138 procedure-with-setter that can be called in two ways. @code{(set!
139 (@var{property} @var{obj}) @var{val})} sets @var{obj}'s @var{property}
140 to @var{val}. @code{(@var{property} @var{obj})} returns the current
141 setting of @var{obj}'s @var{property}.
144 A single object property created by @code{make-object-property} can
145 associate distinct property values with all Scheme values that are
146 distinguishable by @code{eq?} (including, for example, integers).
148 Internally, object properties are implemented using a weak key hash
149 table. This means that, as long as a Scheme value with property values
150 is protected from garbage collection, its property values are also
151 protected. When the Scheme value is collected, its entry in the
152 property table is removed and so the (ex-) property values are no longer
153 protected by the table.
156 * Property Primitives:: Low level property implementation.
157 * Old-fashioned Properties:: An older approach to properties.
161 @node Property Primitives
162 @subsubsection Low Level Property Implementation.
164 @deffn {Scheme Procedure} primitive-make-property not-found-proc
165 @deffnx {C Function} scm_primitive_make_property (not_found_proc)
166 Create a @dfn{property token} that can be used with
167 @code{primitive-property-ref} and @code{primitive-property-set!}.
168 See @code{primitive-property-ref} for the significance of
169 @var{not-found-proc}.
172 @deffn {Scheme Procedure} primitive-property-ref prop obj
173 @deffnx {C Function} scm_primitive_property_ref (prop, obj)
174 Return the property @var{prop} of @var{obj}.
176 When no value has yet been associated with @var{prop} and @var{obj},
177 the @var{not-found-proc} from @var{prop} is used. A call
178 @code{(@var{not-found-proc} @var{prop} @var{obj})} is made and the
179 result set as the property value. If @var{not-found-proc} is
180 @code{#f} then @code{#f} is the property value.
183 @deffn {Scheme Procedure} primitive-property-set! prop obj val
184 @deffnx {C Function} scm_primitive_property_set_x (prop, obj, val)
185 Set the property @var{prop} of @var{obj} to @var{val}.
188 @deffn {Scheme Procedure} primitive-property-del! prop obj
189 @deffnx {C Function} scm_primitive_property_del_x (prop, obj)
190 Remove any value associated with @var{prop} and @var{obj}.
194 @node Old-fashioned Properties
195 @subsubsection An Older Approach to Properties
197 Traditionally, Lisp systems provide a different object property
198 interface to that provided by @code{make-object-property}, in which the
199 object property that is being set or retrieved is indicated by a symbol.
201 Guile includes this older kind of interface as well, but it may well be
202 removed in a future release, as it is less powerful than
203 @code{make-object-property} and so increases the size of the Guile
204 library for no benefit. (And it is trivial to write a compatibility
207 @deffn {Scheme Procedure} object-properties obj
208 @deffnx {C Function} scm_object_properties (obj)
209 Return @var{obj}'s property list.
212 @deffn {Scheme Procedure} set-object-properties! obj alist
213 @deffnx {C Function} scm_set_object_properties_x (obj, alist)
214 Set @var{obj}'s property list to @var{alist}.
217 @deffn {Scheme Procedure} object-property obj key
218 @deffnx {C Function} scm_object_property (obj, key)
219 Return the property of @var{obj} with name @var{key}.
222 @deffn {Scheme Procedure} set-object-property! obj key value
223 @deffnx {C Function} scm_set_object_property_x (obj, key, value)
224 In @var{obj}'s property list, set the property named @var{key}
232 @c FIXME::martin: Review me!
235 @cindex sorting lists
236 @cindex sorting vectors
238 Sorting is very important in computer programs. Therefore, Guile comes
239 with several sorting procedures built-in. As always, procedures with
240 names ending in @code{!} are side-effecting, that means that they may
241 modify their parameters in order to produce their results.
243 The first group of procedures can be used to merge two lists (which must
244 be already sorted on their own) and produce sorted lists containing
245 all elements of the input lists.
247 @deffn {Scheme Procedure} merge alist blist less
248 @deffnx {C Function} scm_merge (alist, blist, less)
249 Merge two already sorted lists into one.
250 Given two lists @var{alist} and @var{blist}, such that
251 @code{(sorted? alist less?)} and @code{(sorted? blist less?)},
252 return a new list in which the elements of @var{alist} and
253 @var{blist} have been stably interleaved so that
254 @code{(sorted? (merge alist blist less?) less?)}.
255 Note: this does _not_ accept vectors.
258 @deffn {Scheme Procedure} merge! alist blist less
259 @deffnx {C Function} scm_merge_x (alist, blist, less)
260 Takes two lists @var{alist} and @var{blist} such that
261 @code{(sorted? alist less?)} and @code{(sorted? blist less?)} and
262 returns a new list in which the elements of @var{alist} and
263 @var{blist} have been stably interleaved so that
264 @code{(sorted? (merge alist blist less?) less?)}.
265 This is the destructive variant of @code{merge}
266 Note: this does _not_ accept vectors.
269 The following procedures can operate on sequences which are either
270 vectors or list. According to the given arguments, they return sorted
271 vectors or lists, respectively. The first of the following procedures
272 determines whether a sequence is already sorted, the other sort a given
273 sequence. The variants with names starting with @code{stable-} are
274 special in that they maintain a special property of the input sequences:
275 If two or more elements are the same according to the comparison
276 predicate, they are left in the same order as they appeared in the
279 @deffn {Scheme Procedure} sorted? items less
280 @deffnx {C Function} scm_sorted_p (items, less)
281 Return @code{#t} iff @var{items} is a list or a vector such that
282 for all 1 <= i <= m, the predicate @var{less} returns true when
283 applied to all elements i - 1 and i
286 @deffn {Scheme Procedure} sort items less
287 @deffnx {C Function} scm_sort (items, less)
288 Sort the sequence @var{items}, which may be a list or a
289 vector. @var{less} is used for comparing the sequence
290 elements. This is not a stable sort.
293 @deffn {Scheme Procedure} sort! items less
294 @deffnx {C Function} scm_sort_x (items, less)
295 Sort the sequence @var{items}, which may be a list or a
296 vector. @var{less} is used for comparing the sequence
297 elements. The sorting is destructive, that means that the
298 input sequence is modified to produce the sorted result.
299 This is not a stable sort.
302 @deffn {Scheme Procedure} stable-sort items less
303 @deffnx {C Function} scm_stable_sort (items, less)
304 Sort the sequence @var{items}, which may be a list or a
305 vector. @var{less} is used for comparing the sequence elements.
306 This is a stable sort.
309 @deffn {Scheme Procedure} stable-sort! items less
310 @deffnx {C Function} scm_stable_sort_x (items, less)
311 Sort the sequence @var{items}, which may be a list or a
312 vector. @var{less} is used for comparing the sequence elements.
313 The sorting is destructive, that means that the input sequence
314 is modified to produce the sorted result.
315 This is a stable sort.
318 The procedures in the last group only accept lists or vectors as input,
319 as their names indicate.
321 @deffn {Scheme Procedure} sort-list items less
322 @deffnx {C Function} scm_sort_list (items, less)
323 Sort the list @var{items}, using @var{less} for comparing the
324 list elements. This is a stable sort.
327 @deffn {Scheme Procedure} sort-list! items less
328 @deffnx {C Function} scm_sort_list_x (items, less)
329 Sort the list @var{items}, using @var{less} for comparing the
330 list elements. The sorting is destructive, that means that the
331 input list is modified to produce the sorted result.
332 This is a stable sort.
335 @deffn {Scheme Procedure} restricted-vector-sort! vec less startpos endpos
336 @deffnx {C Function} scm_restricted_vector_sort_x (vec, less, startpos, endpos)
337 Sort the vector @var{vec}, using @var{less} for comparing
338 the vector elements. @var{startpos} and @var{endpos} delimit
339 the range of the vector which gets sorted. The return value
345 @subsection Copying Deep Structures
347 @c FIXME::martin: Review me!
349 The procedures for copying lists (@pxref{Lists}) only produce a flat
350 copy of the input list, and currently Guile does not even contain
351 procedures for copying vectors. @code{copy-tree} can be used for these
352 application, as it does not only copy the spine of a list, but also
353 copies any pairs in the cars of the input lists.
355 @deffn {Scheme Procedure} copy-tree obj
356 @deffnx {C Function} scm_copy_tree (obj)
357 Recursively copy the data tree that is bound to @var{obj}, and return a
358 the new data structure. @code{copy-tree} recurses down the
359 contents of both pairs and vectors (since both cons cells and vector
360 cells may point to arbitrary objects), and stops recursing when it hits
365 @node General Conversion
366 @subsection General String Conversion
368 @c FIXME::martin: Review me!
370 When debugging Scheme programs, but also for providing a human-friendly
371 interface, a procedure for converting any Scheme object into string
372 format is very useful. Conversion from/to strings can of course be done
373 with specialized procedures when the data type of the object to convert
374 is known, but with this procedure, it is often more comfortable.
376 @code{object->string} converts an object by using a print procedure for
377 writing to a string port, and then returning the resulting string.
378 Converting an object back from the string is only possible if the object
379 type has a read syntax and the read syntax is preserved by the printing
382 @deffn {Scheme Procedure} object->string obj [printer]
383 @deffnx {C Function} scm_object_to_string (obj, printer)
384 Return a Scheme string obtained by printing @var{obj}.
385 Printing function can be specified by the optional second
386 argument @var{printer} (default: @code{write}).
394 A hook is a list of procedures to be called at well defined points in
395 time. Typically, an application provides a hook @var{h} and promises
396 its users that it will call all of the procedures in @var{h} at a
397 defined point in the application's processing. By adding its own
398 procedure to @var{h}, an application user can tap into or even influence
399 the progress of the application.
401 Guile itself provides several such hooks for debugging and customization
402 purposes: these are listed in a subsection below.
404 When an application first creates a hook, it needs to know how many
405 arguments will be passed to the hook's procedures when the hook is run.
406 The chosen number of arguments (which may be none) is declared when the
407 hook is created, and all the procedures that are added to that hook must
408 be capable of accepting that number of arguments.
410 A hook is created using @code{make-hook}. A procedure can be added to
411 or removed from a hook using @code{add-hook!} or @code{remove-hook!},
412 and all of a hook's procedures can be removed together using
413 @code{reset-hook!}. When an application wants to run a hook, it does so
414 using @code{run-hook}.
417 * Hook Example:: Hook usage by example.
418 * Hook Reference:: Reference of all hook procedures.
419 * C Hooks:: Hooks for use from C code.
420 * GC Hooks:: Garbage collection hooks.
421 * REPL Hooks:: Hooks into the Guile REPL.
426 @subsubsection Hook Usage by Example
428 Hook usage is shown by some examples in this section. First, we will
429 define a hook of arity 2 --- that is, the procedures stored in the hook
430 will have to accept two arguments.
433 (define hook (make-hook 2))
435 @result{} #<hook 2 40286c90>
438 Now we are ready to add some procedures to the newly created hook with
439 @code{add-hook!}. In the following example, two procedures are added,
440 which print different messages and do different things with their
444 (add-hook! hook (lambda (x y)
448 (add-hook! hook (lambda (x y)
454 Once the procedures have been added, we can invoke the hook using
463 Note that the procedures are called in the reverse of the order with
464 which they were added. This is because the default behaviour of
465 @code{add-hook!} is to add its procedure to the @emph{front} of the
466 hook's procedure list. You can force @code{add-hook!} to add its
467 procedure to the @emph{end} of the list instead by providing a third
468 @code{#t} argument on the second call to @code{add-hook!}.
471 (add-hook! hook (lambda (x y)
475 (add-hook! hook (lambda (x y)
479 #t) ; @r{<- Change here!}
488 @subsubsection Hook Reference
490 When you create a hook with @code{make-hook}, you must specify the arity
491 of the procedures which can be added to the hook. If the arity is not
492 given explicitly as an argument to @code{make-hook}, it defaults to
493 zero. All procedures of a given hook must have the same arity, and when
494 the procedures are invoked using @code{run-hook}, the number of
495 arguments passed must match the arity specified at hook creation time.
497 The order in which procedures are added to a hook matters. If the third
498 parameter to @code{add-hook!} is omitted or is equal to @code{#f}, the
499 procedure is added in front of the procedures which might already be on
500 that hook, otherwise the procedure is added at the end. The procedures
501 are always called from the front to the end of the list when they are
502 invoked via @code{run-hook}.
504 The ordering of the list of procedures returned by @code{hook->list}
505 matches the order in which those procedures would be called if the hook
506 was run using @code{run-hook}.
508 Note that the C functions in the following entries are for handling
509 @dfn{Scheme-level} hooks in C. There are also @dfn{C-level} hooks which
510 have their own interface (@pxref{C Hooks}).
512 @deffn {Scheme Procedure} make-hook [n_args]
513 @deffnx {C Function} scm_make_hook (n_args)
514 Create a hook for storing procedure of arity @var{n_args}.
515 @var{n_args} defaults to zero. The returned value is a hook
516 object to be used with the other hook procedures.
519 @deffn {Scheme Procedure} hook? x
520 @deffnx {C Function} scm_hook_p (x)
521 Return @code{#t} if @var{x} is a hook, @code{#f} otherwise.
524 @deffn {Scheme Procedure} hook-empty? hook
525 @deffnx {C Function} scm_hook_empty_p (hook)
526 Return @code{#t} if @var{hook} is an empty hook, @code{#f}
530 @deffn {Scheme Procedure} add-hook! hook proc [append_p]
531 @deffnx {C Function} scm_add_hook_x (hook, proc, append_p)
532 Add the procedure @var{proc} to the hook @var{hook}. The
533 procedure is added to the end if @var{append_p} is true,
534 otherwise it is added to the front. The return value of this
535 procedure is not specified.
538 @deffn {Scheme Procedure} remove-hook! hook proc
539 @deffnx {C Function} scm_remove_hook_x (hook, proc)
540 Remove the procedure @var{proc} from the hook @var{hook}. The
541 return value of this procedure is not specified.
544 @deffn {Scheme Procedure} reset-hook! hook
545 @deffnx {C Function} scm_reset_hook_x (hook)
546 Remove all procedures from the hook @var{hook}. The return
547 value of this procedure is not specified.
550 @deffn {Scheme Procedure} hook->list hook
551 @deffnx {C Function} scm_hook_to_list (hook)
552 Convert the procedure list of @var{hook} to a list.
555 @deffn {Scheme Procedure} run-hook hook . args
556 @deffnx {C Function} scm_run_hook (hook, args)
557 Apply all procedures from the hook @var{hook} to the arguments
558 @var{args}. The order of the procedure application is first to
559 last. The return value of this procedure is not specified.
562 If, in C code, you are certain that you have a hook object and well
563 formed argument list for that hook, you can also use
564 @code{scm_c_run_hook}, which is identical to @code{scm_run_hook} but
565 does no type checking.
567 @deftypefn {C Function} void scm_c_run_hook (SCM hook, SCM args)
568 The same as @code{scm_run_hook} but without any type checking to confirm
569 that @var{hook} is actually a hook object and that @var{args} is a
570 well-formed list matching the arity of the hook.
573 For C code, @code{SCM_HOOKP} is a faster alternative to
576 @deftypefn {C Macro} int SCM_HOOKP (x)
577 Return 1 if @var{x} is a Scheme-level hook, 0 otherwise.
581 @subsubsection Handling Scheme-level hooks from C code
583 Here is an example of how to handle Scheme-level hooks from C code using
587 if (scm_is_true (scm_hook_p (obj)))
588 /* handle Scheme-level hook using C functions */
589 scm_reset_hook_x (obj);
591 /* do something else (obj is not a hook) */
596 @subsubsection Hooks For C Code.
598 The hooks already described are intended to be populated by Scheme-level
599 procedures. In addition to this, the Guile library provides an
600 independent set of interfaces for the creation and manipulation of hooks
601 that are designed to be populated by functions implemented in C.
603 The original motivation here was to provide a kind of hook that could
604 safely be invoked at various points during garbage collection.
605 Scheme-level hooks are unsuitable for this purpose as running them could
606 itself require memory allocation, which would then invoke garbage
607 collection recursively @dots{} However, it is also the case that these
608 hooks are easier to work with than the Scheme-level ones if you only
609 want to register C functions with them. So if that is mainly what your
610 code needs to do, you may prefer to use this interface.
612 To create a C hook, you should allocate storage for a structure of type
613 @code{scm_t_c_hook} and then initialize it using @code{scm_c_hook_init}.
615 @deftp {C Type} scm_t_c_hook
616 Data type for a C hook. The internals of this type should be treated as
620 @deftp {C Enum} scm_t_c_hook_type
621 Enumeration of possible hook types, which are:
624 @item SCM_C_HOOK_NORMAL
625 @vindex SCM_C_HOOK_NORMAL
626 Type of hook for which all the registered functions will always be called.
628 @vindex SCM_C_HOOK_OR
629 Type of hook for which the sequence of registered functions will be
630 called only until one of them returns C true (a non-NULL pointer).
632 @vindex SCM_C_HOOK_AND
633 Type of hook for which the sequence of registered functions will be
634 called only until one of them returns C false (a NULL pointer).
638 @deftypefn {C Function} void scm_c_hook_init (scm_t_c_hook *hook, void *hook_data, scm_t_c_hook_type type)
639 Initialize the C hook at memory pointed to by @var{hook}. @var{type}
640 should be one of the values of the @code{scm_t_c_hook_type} enumeration,
641 and controls how the hook functions will be called. @var{hook_data} is
642 a closure parameter that will be passed to all registered hook functions
643 when they are called.
646 To add or remove a C function from a C hook, use @code{scm_c_hook_add}
647 or @code{scm_c_hook_remove}. A hook function must expect three
648 @code{void *} parameters which are, respectively:
652 The hook closure data that was specified at the time the hook was
653 initialized by @code{scm_c_hook_init}.
656 The function closure data that was specified at the time that that
657 function was registered with the hook by @code{scm_c_hook_add}.
660 The call closure data specified by the @code{scm_c_hook_run} call that
664 @deftp {C Type} scm_t_c_hook_function
665 Function type for a C hook function: takes three @code{void *}
666 parameters and returns a @code{void *} result.
669 @deftypefn {C Function} void scm_c_hook_add (scm_t_c_hook *hook, scm_t_c_hook_function func, void *func_data, int appendp)
670 Add function @var{func}, with function closure data @var{func_data}, to
671 the C hook @var{hook}. The new function is appended to the hook's list
672 of functions if @var{appendp} is non-zero, otherwise prepended.
675 @deftypefn {C Function} void scm_c_hook_remove (scm_t_c_hook *hook, scm_t_c_hook_function func, void *func_data)
676 Remove function @var{func}, with function closure data @var{func_data},
677 from the C hook @var{hook}. @code{scm_c_hook_remove} checks both
678 @var{func} and @var{func_data} so as to allow for the same @var{func}
679 being registered multiple times with different closure data.
682 Finally, to invoke a C hook, call the @code{scm_c_hook_run} function
683 specifying the hook and the call closure data for this run:
685 @deftypefn {C Function} {void *} scm_c_hook_run (scm_t_c_hook *hook, void *data)
686 Run the C hook @var{hook} will call closure data @var{data}. Subject to
687 the variations for hook types @code{SCM_C_HOOK_OR} and
688 @code{SCM_C_HOOK_AND}, @code{scm_c_hook_run} calls @var{hook}'s
689 registered functions in turn, passing them the hook's closure data, each
690 function's closure data, and the call closure data.
692 @code{scm_c_hook_run}'s return value is the return value of the last
693 function to be called.
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"