2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2011
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
7 @node Utility Functions
8 @section General Utility Functions
10 @c FIXME::martin: Review me!
12 This chapter contains information about procedures which are not cleanly
13 tied to a specific data type. Because of their wide range of
14 applications, they are collected in a @dfn{utility} chapter.
17 * Equality:: When are two values `the same'?
18 * Object Properties:: A modern interface to object properties.
19 * Sorting:: Sort utility procedures.
20 * Copying:: Copying deep structures.
21 * General Conversion:: Converting objects to strings.
22 * Hooks:: User-customizable event lists.
31 There are three kinds of core equality predicates in Scheme, described
32 below. The same kinds of comparisons arise in other functions, like
33 @code{memq} and friends (@pxref{List Searching}).
35 For all three tests, objects of different types are never equal. So
36 for instance a list and a vector are not @code{equal?}, even if their
37 contents are the same. Exact and inexact numbers are considered
38 different types too, and are hence not equal even if their values are
41 @code{eq?} tests just for the same object (essentially a pointer
42 comparison). This is fast, and can be used when searching for a
43 particular object, or when working with symbols or keywords (which are
44 always unique objects).
46 @code{eqv?} extends @code{eq?} to look at the value of numbers and
47 characters. It can for instance be used somewhat like @code{=}
48 (@pxref{Comparison}) but without an error if one operand isn't a
51 @code{equal?} goes further, it looks (recursively) into the contents
52 of lists, vectors, etc. This is good for instance on lists that have
53 been read or calculated in various places and are the same, just not
54 made up of the same pairs. Such lists look the same (when printed),
55 and @code{equal?} will consider them the same.
58 @deffn {Scheme Procedure} eq? x y
59 @deffnx {C Function} scm_eq_p (x, y)
61 Return @code{#t} if @var{x} and @var{y} are the same object, except
62 for numbers and characters. For example,
65 (define x (vector 1 2 3))
66 (define y (vector 1 2 3))
68 (eq? x x) @result{} #t
69 (eq? x y) @result{} #f
72 Numbers and characters are not equal to any other object, but the
73 problem is they're not necessarily @code{eq?} to themselves either.
74 This is even so when the number comes directly from a variable,
78 (eq? n n)) @result{} *unspecified*
81 Generally @code{eqv?} below should be used when comparing numbers or
82 characters. @code{=} (@pxref{Comparison}) or @code{char=?}
83 (@pxref{Characters}) can be used too.
85 It's worth noting that end-of-list @code{()}, @code{#t}, @code{#f}, a
86 symbol of a given name, and a keyword of a given name, are unique
87 objects. There's just one of each, so for instance no matter how
88 @code{()} arises in a program, it's the same object and can be
89 compared with @code{eq?},
92 (define x (cdr '(123)))
93 (define y (cdr '(456)))
94 (eq? x y) @result{} #t
96 (define x (string->symbol "foo"))
97 (eq? x 'foo) @result{} #t
101 @deftypefn {C Function} int scm_is_eq (SCM x, SCM y)
102 Return @code{1} when @var{x} and @var{y} are equal in the sense of
103 @code{eq?}, otherwise return @code{0}.
106 The @code{==} operator should not be used on @code{SCM} values, an
107 @code{SCM} is a C type which cannot necessarily be compared using
108 @code{==} (@pxref{The SCM Type}).
112 @deffn {Scheme Procedure} eqv? x y
113 @deffnx {C Function} scm_eqv_p (x, y)
115 Return @code{#t} if @var{x} and @var{y} are the same object, or for
116 characters and numbers the same value.
118 On objects except characters and numbers, @code{eqv?} is the same as
119 @code{eq?} above, it's true if @var{x} and @var{y} are the same
122 If @var{x} and @var{y} are numbers or characters, @code{eqv?} compares
123 their type and value. An exact number is not @code{eqv?} to an
124 inexact number (even if their value is the same).
127 (eqv? 3 (+ 1 2)) @result{} #t
128 (eqv? 1 1.0) @result{} #f
133 @deffn {Scheme Procedure} equal? x y
134 @deffnx {C Function} scm_equal_p (x, y)
136 Return @code{#t} if @var{x} and @var{y} are the same type, and their
137 contents or value are equal.
139 For a pair, string, vector, array or structure, @code{equal?} compares the
140 contents, and does so using the same @code{equal?} recursively,
141 so a deep structure can be traversed.
144 (equal? (list 1 2 3) (list 1 2 3)) @result{} #t
145 (equal? (list 1 2 3) (vector 1 2 3)) @result{} #f
148 For other objects, @code{equal?} compares as per @code{eqv?} above,
149 which means characters and numbers are compared by type and value (and
150 like @code{eqv?}, exact and inexact numbers are not @code{equal?},
151 even if their value is the same).
154 (equal? 3 (+ 1 2)) @result{} #t
155 (equal? 1 1.0) @result{} #f
158 Hash tables are currently only compared as per @code{eq?}, so two
159 different tables are not @code{equal?}, even if their contents are the
162 @code{equal?} does not support circular data structures, it may go
163 into an infinite loop if asked to compare two circular lists or
166 New application-defined object types (@pxref{Defining New Types
167 (Smobs)}) have an @code{equalp} handler which is called by
168 @code{equal?}. This lets an application traverse the contents or
169 control what is considered @code{equal?} for two objects of such a
170 type. If there's no such handler, the default is to just compare as
175 @node Object Properties
176 @subsection Object Properties
178 It's often useful to associate a piece of additional information with a
179 Scheme object even though that object does not have a dedicated slot
180 available in which the additional information could be stored. Object
181 properties allow you to do just that.
183 Guile's representation of an object property is a procedure-with-setter
184 (@pxref{Procedures with Setters}) that can be used with the generalized
185 form of @code{set!} (REFFIXME) to set and retrieve that property for any
186 Scheme object. So, setting a property looks like this:
189 (set! (my-property obj1) value-for-obj1)
190 (set! (my-property obj2) value-for-obj2)
194 And retrieving values of the same property looks like this:
206 To create an object property in the first place, use the
207 @code{make-object-property} procedure:
210 (define my-property (make-object-property))
213 @deffn {Scheme Procedure} make-object-property
214 Create and return an object property. An object property is a
215 procedure-with-setter that can be called in two ways. @code{(set!
216 (@var{property} @var{obj}) @var{val})} sets @var{obj}'s @var{property}
217 to @var{val}. @code{(@var{property} @var{obj})} returns the current
218 setting of @var{obj}'s @var{property}.
221 A single object property created by @code{make-object-property} can
222 associate distinct property values with all Scheme values that are
223 distinguishable by @code{eq?} (including, for example, integers).
225 Internally, object properties are implemented using a weak key hash
226 table. This means that, as long as a Scheme value with property values
227 is protected from garbage collection, its property values are also
228 protected. When the Scheme value is collected, its entry in the
229 property table is removed and so the (ex-) property values are no longer
230 protected by the table.
232 Guile also implements a more traditional Lispy interface to properties,
233 in which each object has an list of key-value pairs associated with it.
234 Properties in that list are keyed by symbols. This is a legacy
235 interface; you should use weak hash tables or object properties instead.
237 @deffn {Scheme Procedure} object-properties obj
238 @deffnx {C Function} scm_object_properties (obj)
239 Return @var{obj}'s property list.
242 @deffn {Scheme Procedure} set-object-properties! obj alist
243 @deffnx {C Function} scm_set_object_properties_x (obj, alist)
244 Set @var{obj}'s property list to @var{alist}.
247 @deffn {Scheme Procedure} object-property obj key
248 @deffnx {C Function} scm_object_property (obj, key)
249 Return the property of @var{obj} with name @var{key}.
252 @deffn {Scheme Procedure} set-object-property! obj key value
253 @deffnx {C Function} scm_set_object_property_x (obj, key, value)
254 In @var{obj}'s property list, set the property named @var{key}
262 @c FIXME::martin: Review me!
265 @cindex sorting lists
266 @cindex sorting vectors
268 Sorting is very important in computer programs. Therefore, Guile comes
269 with several sorting procedures built-in. As always, procedures with
270 names ending in @code{!} are side-effecting, that means that they may
271 modify their parameters in order to produce their results.
273 The first group of procedures can be used to merge two lists (which must
274 be already sorted on their own) and produce sorted lists containing
275 all elements of the input lists.
277 @deffn {Scheme Procedure} merge alist blist less
278 @deffnx {C Function} scm_merge (alist, blist, less)
279 Merge two already sorted lists into one.
280 Given two lists @var{alist} and @var{blist}, such that
281 @code{(sorted? alist less?)} and @code{(sorted? blist less?)},
282 return a new list in which the elements of @var{alist} and
283 @var{blist} have been stably interleaved so that
284 @code{(sorted? (merge alist blist less?) less?)}.
285 Note: this does _not_ accept vectors.
288 @deffn {Scheme Procedure} merge! alist blist less
289 @deffnx {C Function} scm_merge_x (alist, blist, less)
290 Takes two lists @var{alist} and @var{blist} such that
291 @code{(sorted? alist less?)} and @code{(sorted? blist less?)} and
292 returns a new list in which the elements of @var{alist} and
293 @var{blist} have been stably interleaved so that
294 @code{(sorted? (merge alist blist less?) less?)}.
295 This is the destructive variant of @code{merge}
296 Note: this does _not_ accept vectors.
299 The following procedures can operate on sequences which are either
300 vectors or list. According to the given arguments, they return sorted
301 vectors or lists, respectively. The first of the following procedures
302 determines whether a sequence is already sorted, the other sort a given
303 sequence. The variants with names starting with @code{stable-} are
304 special in that they maintain a special property of the input sequences:
305 If two or more elements are the same according to the comparison
306 predicate, they are left in the same order as they appeared in the
309 @deffn {Scheme Procedure} sorted? items less
310 @deffnx {C Function} scm_sorted_p (items, less)
311 Return @code{#t} iff @var{items} is a list or a vector such that
312 for all 1 <= i <= m, the predicate @var{less} returns true when
313 applied to all elements i - 1 and i
316 @deffn {Scheme Procedure} sort items less
317 @deffnx {C Function} scm_sort (items, less)
318 Sort the sequence @var{items}, which may be a list or a
319 vector. @var{less} is used for comparing the sequence
320 elements. This is not a stable sort.
323 @deffn {Scheme Procedure} sort! items less
324 @deffnx {C Function} scm_sort_x (items, less)
325 Sort the sequence @var{items}, which may be a list or a
326 vector. @var{less} is used for comparing the sequence
327 elements. The sorting is destructive, that means that the
328 input sequence is modified to produce the sorted result.
329 This is not a stable sort.
332 @deffn {Scheme Procedure} stable-sort items less
333 @deffnx {C Function} scm_stable_sort (items, less)
334 Sort the sequence @var{items}, which may be a list or a
335 vector. @var{less} is used for comparing the sequence elements.
336 This is a stable sort.
339 @deffn {Scheme Procedure} stable-sort! items less
340 @deffnx {C Function} scm_stable_sort_x (items, less)
341 Sort the sequence @var{items}, which may be a list or a
342 vector. @var{less} is used for comparing the sequence elements.
343 The sorting is destructive, that means that the input sequence
344 is modified to produce the sorted result.
345 This is a stable sort.
348 The procedures in the last group only accept lists or vectors as input,
349 as their names indicate.
351 @deffn {Scheme Procedure} sort-list items less
352 @deffnx {C Function} scm_sort_list (items, less)
353 Sort the list @var{items}, using @var{less} for comparing the
354 list elements. This is a stable sort.
357 @deffn {Scheme Procedure} sort-list! items less
358 @deffnx {C Function} scm_sort_list_x (items, less)
359 Sort the list @var{items}, using @var{less} for comparing the
360 list elements. The sorting is destructive, that means that the
361 input list is modified to produce the sorted result.
362 This is a stable sort.
365 @deffn {Scheme Procedure} restricted-vector-sort! vec less startpos endpos
366 @deffnx {C Function} scm_restricted_vector_sort_x (vec, less, startpos, endpos)
367 Sort the vector @var{vec}, using @var{less} for comparing
368 the vector elements. @var{startpos} (inclusively) and
369 @var{endpos} (exclusively) delimit
370 the range of the vector which gets sorted. The return value
376 @subsection Copying Deep Structures
378 @c FIXME::martin: Review me!
380 The procedures for copying lists (@pxref{Lists}) only produce a flat
381 copy of the input list, and currently Guile does not even contain
382 procedures for copying vectors. @code{copy-tree} can be used for these
383 application, as it does not only copy the spine of a list, but also
384 copies any pairs in the cars of the input lists.
386 @deffn {Scheme Procedure} copy-tree obj
387 @deffnx {C Function} scm_copy_tree (obj)
388 Recursively copy the data tree that is bound to @var{obj}, and return
389 the new data structure. @code{copy-tree} recurses down the
390 contents of both pairs and vectors (since both cons cells and vector
391 cells may point to arbitrary objects), and stops recursing when it hits
396 @node General Conversion
397 @subsection General String Conversion
399 @c FIXME::martin: Review me!
401 When debugging Scheme programs, but also for providing a human-friendly
402 interface, a procedure for converting any Scheme object into string
403 format is very useful. Conversion from/to strings can of course be done
404 with specialized procedures when the data type of the object to convert
405 is known, but with this procedure, it is often more comfortable.
407 @code{object->string} converts an object by using a print procedure for
408 writing to a string port, and then returning the resulting string.
409 Converting an object back from the string is only possible if the object
410 type has a read syntax and the read syntax is preserved by the printing
413 @deffn {Scheme Procedure} object->string obj [printer]
414 @deffnx {C Function} scm_object_to_string (obj, printer)
415 Return a Scheme string obtained by printing @var{obj}.
416 Printing function can be specified by the optional second
417 argument @var{printer} (default: @code{write}).
425 A hook is a list of procedures to be called at well defined points in
426 time. Typically, an application provides a hook @var{h} and promises
427 its users that it will call all of the procedures in @var{h} at a
428 defined point in the application's processing. By adding its own
429 procedure to @var{h}, an application user can tap into or even influence
430 the progress of the application.
432 Guile itself provides several such hooks for debugging and customization
433 purposes: these are listed in a subsection below.
435 When an application first creates a hook, it needs to know how many
436 arguments will be passed to the hook's procedures when the hook is run.
437 The chosen number of arguments (which may be none) is declared when the
438 hook is created, and all the procedures that are added to that hook must
439 be capable of accepting that number of arguments.
441 A hook is created using @code{make-hook}. A procedure can be added to
442 or removed from a hook using @code{add-hook!} or @code{remove-hook!},
443 and all of a hook's procedures can be removed together using
444 @code{reset-hook!}. When an application wants to run a hook, it does so
445 using @code{run-hook}.
448 * Hook Example:: Hook usage by example.
449 * Hook Reference:: Reference of all hook procedures.
450 * C Hooks:: Hooks for use from C code.
451 * GC Hooks:: Garbage collection hooks.
452 * REPL Hooks:: Hooks into the Guile REPL.
457 @subsubsection Hook Usage by Example
459 Hook usage is shown by some examples in this section. First, we will
460 define a hook of arity 2 --- that is, the procedures stored in the hook
461 will have to accept two arguments.
464 (define hook (make-hook 2))
466 @result{} #<hook 2 40286c90>
469 Now we are ready to add some procedures to the newly created hook with
470 @code{add-hook!}. In the following example, two procedures are added,
471 which print different messages and do different things with their
475 (add-hook! hook (lambda (x y)
479 (add-hook! hook (lambda (x y)
485 Once the procedures have been added, we can invoke the hook using
494 Note that the procedures are called in the reverse of the order with
495 which they were added. This is because the default behaviour of
496 @code{add-hook!} is to add its procedure to the @emph{front} of the
497 hook's procedure list. You can force @code{add-hook!} to add its
498 procedure to the @emph{end} of the list instead by providing a third
499 @code{#t} argument on the second call to @code{add-hook!}.
502 (add-hook! hook (lambda (x y)
506 (add-hook! hook (lambda (x y)
510 #t) ; @r{<- Change here!}
519 @subsubsection Hook Reference
521 When you create a hook with @code{make-hook}, you must specify the arity
522 of the procedures which can be added to the hook. If the arity is not
523 given explicitly as an argument to @code{make-hook}, it defaults to
524 zero. All procedures of a given hook must have the same arity, and when
525 the procedures are invoked using @code{run-hook}, the number of
526 arguments passed must match the arity specified at hook creation time.
528 The order in which procedures are added to a hook matters. If the third
529 parameter to @code{add-hook!} is omitted or is equal to @code{#f}, the
530 procedure is added in front of the procedures which might already be on
531 that hook, otherwise the procedure is added at the end. The procedures
532 are always called from the front to the end of the list when they are
533 invoked via @code{run-hook}.
535 The ordering of the list of procedures returned by @code{hook->list}
536 matches the order in which those procedures would be called if the hook
537 was run using @code{run-hook}.
539 Note that the C functions in the following entries are for handling
540 @dfn{Scheme-level} hooks in C. There are also @dfn{C-level} hooks which
541 have their own interface (@pxref{C Hooks}).
543 @deffn {Scheme Procedure} make-hook [n_args]
544 @deffnx {C Function} scm_make_hook (n_args)
545 Create a hook for storing procedure of arity @var{n_args}.
546 @var{n_args} defaults to zero. The returned value is a hook
547 object to be used with the other hook procedures.
550 @deffn {Scheme Procedure} hook? x
551 @deffnx {C Function} scm_hook_p (x)
552 Return @code{#t} if @var{x} is a hook, @code{#f} otherwise.
555 @deffn {Scheme Procedure} hook-empty? hook
556 @deffnx {C Function} scm_hook_empty_p (hook)
557 Return @code{#t} if @var{hook} is an empty hook, @code{#f}
561 @deffn {Scheme Procedure} add-hook! hook proc [append_p]
562 @deffnx {C Function} scm_add_hook_x (hook, proc, append_p)
563 Add the procedure @var{proc} to the hook @var{hook}. The
564 procedure is added to the end if @var{append_p} is true,
565 otherwise it is added to the front. The return value of this
566 procedure is not specified.
569 @deffn {Scheme Procedure} remove-hook! hook proc
570 @deffnx {C Function} scm_remove_hook_x (hook, proc)
571 Remove the procedure @var{proc} from the hook @var{hook}. The
572 return value of this procedure is not specified.
575 @deffn {Scheme Procedure} reset-hook! hook
576 @deffnx {C Function} scm_reset_hook_x (hook)
577 Remove all procedures from the hook @var{hook}. The return
578 value of this procedure is not specified.
581 @deffn {Scheme Procedure} hook->list hook
582 @deffnx {C Function} scm_hook_to_list (hook)
583 Convert the procedure list of @var{hook} to a list.
586 @deffn {Scheme Procedure} run-hook hook arg @dots{}
587 @deffnx {C Function} scm_run_hook (hook, args)
588 Apply all procedures from the hook @var{hook} to the arguments @var{arg}
589 @enddots{}. The order of the procedure application is first to last.
590 The return value of this procedure is not specified.
593 If, in C code, you are certain that you have a hook object and well
594 formed argument list for that hook, you can also use
595 @code{scm_c_run_hook}, which is identical to @code{scm_run_hook} but
596 does no type checking.
598 @deftypefn {C Function} void scm_c_run_hook (SCM hook, SCM args)
599 The same as @code{scm_run_hook} but without any type checking to confirm
600 that @var{hook} is actually a hook object and that @var{args} is a
601 well-formed list matching the arity of the hook.
604 For C code, @code{SCM_HOOKP} is a faster alternative to
607 @deftypefn {C Macro} int SCM_HOOKP (x)
608 Return 1 if @var{x} is a Scheme-level hook, 0 otherwise.
612 @subsubsection Handling Scheme-level hooks from C code
614 Here is an example of how to handle Scheme-level hooks from C code using
618 if (scm_is_true (scm_hook_p (obj)))
619 /* handle Scheme-level hook using C functions */
620 scm_reset_hook_x (obj);
622 /* do something else (obj is not a hook) */
627 @subsubsection Hooks For C Code.
629 The hooks already described are intended to be populated by Scheme-level
630 procedures. In addition to this, the Guile library provides an
631 independent set of interfaces for the creation and manipulation of hooks
632 that are designed to be populated by functions implemented in C.
634 The original motivation here was to provide a kind of hook that could
635 safely be invoked at various points during garbage collection.
636 Scheme-level hooks are unsuitable for this purpose as running them could
637 itself require memory allocation, which would then invoke garbage
638 collection recursively @dots{} However, it is also the case that these
639 hooks are easier to work with than the Scheme-level ones if you only
640 want to register C functions with them. So if that is mainly what your
641 code needs to do, you may prefer to use this interface.
643 To create a C hook, you should allocate storage for a structure of type
644 @code{scm_t_c_hook} and then initialize it using @code{scm_c_hook_init}.
646 @deftp {C Type} scm_t_c_hook
647 Data type for a C hook. The internals of this type should be treated as
651 @deftp {C Enum} scm_t_c_hook_type
652 Enumeration of possible hook types, which are:
655 @item SCM_C_HOOK_NORMAL
656 @vindex SCM_C_HOOK_NORMAL
657 Type of hook for which all the registered functions will always be called.
659 @vindex SCM_C_HOOK_OR
660 Type of hook for which the sequence of registered functions will be
661 called only until one of them returns C true (a non-NULL pointer).
663 @vindex SCM_C_HOOK_AND
664 Type of hook for which the sequence of registered functions will be
665 called only until one of them returns C false (a NULL pointer).
669 @deftypefn {C Function} void scm_c_hook_init (scm_t_c_hook *hook, void *hook_data, scm_t_c_hook_type type)
670 Initialize the C hook at memory pointed to by @var{hook}. @var{type}
671 should be one of the values of the @code{scm_t_c_hook_type} enumeration,
672 and controls how the hook functions will be called. @var{hook_data} is
673 a closure parameter that will be passed to all registered hook functions
674 when they are called.
677 To add or remove a C function from a C hook, use @code{scm_c_hook_add}
678 or @code{scm_c_hook_remove}. A hook function must expect three
679 @code{void *} parameters which are, respectively:
683 The hook closure data that was specified at the time the hook was
684 initialized by @code{scm_c_hook_init}.
687 The function closure data that was specified at the time that that
688 function was registered with the hook by @code{scm_c_hook_add}.
691 The call closure data specified by the @code{scm_c_hook_run} call that
695 @deftp {C Type} scm_t_c_hook_function
696 Function type for a C hook function: takes three @code{void *}
697 parameters and returns a @code{void *} result.
700 @deftypefn {C Function} void scm_c_hook_add (scm_t_c_hook *hook, scm_t_c_hook_function func, void *func_data, int appendp)
701 Add function @var{func}, with function closure data @var{func_data}, to
702 the C hook @var{hook}. The new function is appended to the hook's list
703 of functions if @var{appendp} is non-zero, otherwise prepended.
706 @deftypefn {C Function} void scm_c_hook_remove (scm_t_c_hook *hook, scm_t_c_hook_function func, void *func_data)
707 Remove function @var{func}, with function closure data @var{func_data},
708 from the C hook @var{hook}. @code{scm_c_hook_remove} checks both
709 @var{func} and @var{func_data} so as to allow for the same @var{func}
710 being registered multiple times with different closure data.
713 Finally, to invoke a C hook, call the @code{scm_c_hook_run} function
714 specifying the hook and the call closure data for this run:
716 @deftypefn {C Function} {void *} scm_c_hook_run (scm_t_c_hook *hook, void *data)
717 Run the C hook @var{hook} will call closure data @var{data}. Subject to
718 the variations for hook types @code{SCM_C_HOOK_OR} and
719 @code{SCM_C_HOOK_AND}, @code{scm_c_hook_run} calls @var{hook}'s
720 registered functions in turn, passing them the hook's closure data, each
721 function's closure data, and the call closure data.
723 @code{scm_c_hook_run}'s return value is the return value of the last
724 function to be called.
729 @subsubsection Hooks for Garbage Collection
731 Whenever Guile performs a garbage collection, it calls the following
732 hooks in the order shown.
734 @defvr {C Hook} scm_before_gc_c_hook
735 C hook called at the very start of a garbage collection, after setting
736 @code{scm_gc_running_p} to 1, but before entering the GC critical
739 If garbage collection is blocked because @code{scm_block_gc} is
740 non-zero, GC exits early soon after calling this hook, and no further
741 hooks will be called.
744 @defvr {C Hook} scm_before_mark_c_hook
745 C hook called before beginning the mark phase of garbage collection,
746 after the GC thread has entered a critical section.
749 @defvr {C Hook} scm_before_sweep_c_hook
750 C hook called before beginning the sweep phase of garbage collection.
751 This is the same as at the end of the mark phase, since nothing else
752 happens between marking and sweeping.
755 @defvr {C Hook} scm_after_sweep_c_hook
756 C hook called after the end of the sweep phase of garbage collection,
757 but while the GC thread is still inside its critical section.
760 @defvr {C Hook} scm_after_gc_c_hook
761 C hook called at the very end of a garbage collection, after the GC
762 thread has left its critical section.
765 @defvr {Scheme Hook} after-gc-hook
766 @vindex scm_after_gc_hook
767 Scheme hook with arity 0. This hook is run asynchronously
768 (@pxref{Asyncs}) soon after the GC has completed and any other events
769 that were deferred during garbage collection have been processed. (Also
770 accessible from C with the name @code{scm_after_gc_hook}.)
773 All the C hooks listed here have type @code{SCM_C_HOOK_NORMAL}, are
774 initialized with hook closure data NULL, are invoked by
775 @code{scm_c_hook_run} with call closure data NULL.
777 @cindex guardians, testing for GC'd objects
778 The Scheme hook @code{after-gc-hook} is particularly useful in
779 conjunction with guardians (@pxref{Guardians}). Typically, if you are
780 using a guardian, you want to call the guardian after garbage collection
781 to see if any of the objects added to the guardian have been collected.
782 By adding a thunk that performs this call to @code{after-gc-hook}, you
783 can ensure that your guardian is tested after every garbage collection
788 @subsubsection Hooks into the Guile REPL
792 @c TeX-master: "guile.texi"