2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2011, 2012, 2013, 2014
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 GOOPS object types (@pxref{GOOPS}), including foreign object types
167 (@pxref{Defining New Foreign Object Types}), can have an @code{equal?}
168 implementation specialized on two values of the same type. If
169 @code{equal?} is called on two GOOPS objects of the same type,
170 @code{equal?} will dispatch out to a generic function. This lets an
171 application traverse the contents or control what is considered
172 @code{equal?} for two objects of such a type. If there's no such
173 handler, the default is to just compare as per @code{eq?}.
177 @node Object Properties
178 @subsection Object Properties
180 It's often useful to associate a piece of additional information with a
181 Scheme object even though that object does not have a dedicated slot
182 available in which the additional information could be stored. Object
183 properties allow you to do just that.
185 Guile's representation of an object property is a procedure-with-setter
186 (@pxref{Procedures with Setters}) that can be used with the generalized
187 form of @code{set!} (REFFIXME) to set and retrieve that property for any
188 Scheme object. So, setting a property looks like this:
191 (set! (my-property obj1) value-for-obj1)
192 (set! (my-property obj2) value-for-obj2)
196 And retrieving values of the same property looks like this:
208 To create an object property in the first place, use the
209 @code{make-object-property} procedure:
212 (define my-property (make-object-property))
215 @deffn {Scheme Procedure} make-object-property
216 Create and return an object property. An object property is a
217 procedure-with-setter that can be called in two ways. @code{(set!
218 (@var{property} @var{obj}) @var{val})} sets @var{obj}'s @var{property}
219 to @var{val}. @code{(@var{property} @var{obj})} returns the current
220 setting of @var{obj}'s @var{property}.
223 A single object property created by @code{make-object-property} can
224 associate distinct property values with all Scheme values that are
225 distinguishable by @code{eq?} (ruling out numeric values).
227 Internally, object properties are implemented using a weak key hash
228 table. This means that, as long as a Scheme value with property values
229 is protected from garbage collection, its property values are also
230 protected. When the Scheme value is collected, its entry in the
231 property table is removed and so the (ex-) property values are no longer
232 protected by the table.
234 Guile also implements a more traditional Lispy interface to properties,
235 in which each object has an list of key-value pairs associated with it.
236 Properties in that list are keyed by symbols. This is a legacy
237 interface; you should use weak hash tables or object properties instead.
239 @deffn {Scheme Procedure} object-properties obj
240 @deffnx {C Function} scm_object_properties (obj)
241 Return @var{obj}'s property list.
244 @deffn {Scheme Procedure} set-object-properties! obj alist
245 @deffnx {C Function} scm_set_object_properties_x (obj, alist)
246 Set @var{obj}'s property list to @var{alist}.
249 @deffn {Scheme Procedure} object-property obj key
250 @deffnx {C Function} scm_object_property (obj, key)
251 Return the property of @var{obj} with name @var{key}.
254 @deffn {Scheme Procedure} set-object-property! obj key value
255 @deffnx {C Function} scm_set_object_property_x (obj, key, value)
256 In @var{obj}'s property list, set the property named @var{key}
264 @c FIXME::martin: Review me!
267 @cindex sorting lists
268 @cindex sorting vectors
270 Sorting is very important in computer programs. Therefore, Guile comes
271 with several sorting procedures built-in. As always, procedures with
272 names ending in @code{!} are side-effecting, that means that they may
273 modify their parameters in order to produce their results.
275 The first group of procedures can be used to merge two lists (which must
276 be already sorted on their own) and produce sorted lists containing
277 all elements of the input lists.
279 @deffn {Scheme Procedure} merge alist blist less
280 @deffnx {C Function} scm_merge (alist, blist, less)
281 Merge two already sorted lists into one.
282 Given two lists @var{alist} and @var{blist}, such that
283 @code{(sorted? alist less?)} and @code{(sorted? blist less?)},
284 return a new list in which the elements of @var{alist} and
285 @var{blist} have been stably interleaved so that
286 @code{(sorted? (merge alist blist less?) less?)}.
287 Note: this does _not_ accept vectors.
290 @deffn {Scheme Procedure} merge! alist blist less
291 @deffnx {C Function} scm_merge_x (alist, blist, less)
292 Takes two lists @var{alist} and @var{blist} such that
293 @code{(sorted? alist less?)} and @code{(sorted? blist less?)} and
294 returns a new list in which the elements of @var{alist} and
295 @var{blist} have been stably interleaved so that
296 @code{(sorted? (merge alist blist less?) less?)}.
297 This is the destructive variant of @code{merge}
298 Note: this does _not_ accept vectors.
301 The following procedures can operate on sequences which are either
302 vectors or list. According to the given arguments, they return sorted
303 vectors or lists, respectively. The first of the following procedures
304 determines whether a sequence is already sorted, the other sort a given
305 sequence. The variants with names starting with @code{stable-} are
306 special in that they maintain a special property of the input sequences:
307 If two or more elements are the same according to the comparison
308 predicate, they are left in the same order as they appeared in the
311 @deffn {Scheme Procedure} sorted? items less
312 @deffnx {C Function} scm_sorted_p (items, less)
313 Return @code{#t} if @var{items} is a list or vector such that,
314 for each element @var{x} and the next element @var{y} of
315 @var{items}, @code{(@var{less} @var{y} @var{x})} returns
316 @code{#f}. Otherwise return @code{#f}.
319 @deffn {Scheme Procedure} sort items less
320 @deffnx {C Function} scm_sort (items, less)
321 Sort the sequence @var{items}, which may be a list or a
322 vector. @var{less} is used for comparing the sequence
323 elements. This is not a stable sort.
326 @deffn {Scheme Procedure} sort! items less
327 @deffnx {C Function} scm_sort_x (items, less)
328 Sort the sequence @var{items}, which may be a list or a
329 vector. @var{less} is used for comparing the sequence
330 elements. The sorting is destructive, that means that the
331 input sequence is modified to produce the sorted result.
332 This is not a stable sort.
335 @deffn {Scheme Procedure} stable-sort items less
336 @deffnx {C Function} scm_stable_sort (items, less)
337 Sort the sequence @var{items}, which may be a list or a
338 vector. @var{less} is used for comparing the sequence elements.
339 This is a stable sort.
342 @deffn {Scheme Procedure} stable-sort! items less
343 @deffnx {C Function} scm_stable_sort_x (items, less)
344 Sort the sequence @var{items}, which may be a list or a
345 vector. @var{less} is used for comparing the sequence elements.
346 The sorting is destructive, that means that the input sequence
347 is modified to produce the sorted result.
348 This is a stable sort.
351 The procedures in the last group only accept lists or vectors as input,
352 as their names indicate.
354 @deffn {Scheme Procedure} sort-list items less
355 @deffnx {C Function} scm_sort_list (items, less)
356 Sort the list @var{items}, using @var{less} for comparing the
357 list elements. This is a stable sort.
360 @deffn {Scheme Procedure} sort-list! items less
361 @deffnx {C Function} scm_sort_list_x (items, less)
362 Sort the list @var{items}, using @var{less} for comparing the
363 list elements. The sorting is destructive, that means that the
364 input list is modified to produce the sorted result.
365 This is a stable sort.
368 @deffn {Scheme Procedure} restricted-vector-sort! vec less startpos endpos
369 @deffnx {C Function} scm_restricted_vector_sort_x (vec, less, startpos, endpos)
370 Sort the vector @var{vec}, using @var{less} for comparing
371 the vector elements. @var{startpos} (inclusively) and
372 @var{endpos} (exclusively) delimit
373 the range of the vector which gets sorted. The return value
379 @subsection Copying Deep Structures
381 @c FIXME::martin: Review me!
383 The procedures for copying lists (@pxref{Lists}) only produce a flat
384 copy of the input list, and currently Guile does not even contain
385 procedures for copying vectors. @code{copy-tree} can be used for these
386 application, as it does not only copy the spine of a list, but also
387 copies any pairs in the cars of the input lists.
389 @deffn {Scheme Procedure} copy-tree obj
390 @deffnx {C Function} scm_copy_tree (obj)
391 Recursively copy the data tree that is bound to @var{obj}, and return
392 the new data structure. @code{copy-tree} recurses down the
393 contents of both pairs and vectors (since both cons cells and vector
394 cells may point to arbitrary objects), and stops recursing when it hits
399 @node General Conversion
400 @subsection General String Conversion
402 @c FIXME::martin: Review me!
404 When debugging Scheme programs, but also for providing a human-friendly
405 interface, a procedure for converting any Scheme object into string
406 format is very useful. Conversion from/to strings can of course be done
407 with specialized procedures when the data type of the object to convert
408 is known, but with this procedure, it is often more comfortable.
410 @code{object->string} converts an object by using a print procedure for
411 writing to a string port, and then returning the resulting string.
412 Converting an object back from the string is only possible if the object
413 type has a read syntax and the read syntax is preserved by the printing
416 @deffn {Scheme Procedure} object->string obj [printer]
417 @deffnx {C Function} scm_object_to_string (obj, printer)
418 Return a Scheme string obtained by printing @var{obj}.
419 Printing function can be specified by the optional second
420 argument @var{printer} (default: @code{write}).
428 A hook is a list of procedures to be called at well defined points in
429 time. Typically, an application provides a hook @var{h} and promises
430 its users that it will call all of the procedures in @var{h} at a
431 defined point in the application's processing. By adding its own
432 procedure to @var{h}, an application user can tap into or even influence
433 the progress of the application.
435 Guile itself provides several such hooks for debugging and customization
436 purposes: these are listed in a subsection below.
438 When an application first creates a hook, it needs to know how many
439 arguments will be passed to the hook's procedures when the hook is run.
440 The chosen number of arguments (which may be none) is declared when the
441 hook is created, and all the procedures that are added to that hook must
442 be capable of accepting that number of arguments.
444 A hook is created using @code{make-hook}. A procedure can be added to
445 or removed from a hook using @code{add-hook!} or @code{remove-hook!},
446 and all of a hook's procedures can be removed together using
447 @code{reset-hook!}. When an application wants to run a hook, it does so
448 using @code{run-hook}.
451 * Hook Example:: Hook usage by example.
452 * Hook Reference:: Reference of all hook procedures.
453 * C Hooks:: Hooks for use from C code.
454 * GC Hooks:: Garbage collection hooks.
455 * REPL Hooks:: Hooks into the Guile REPL.
460 @subsubsection Hook Usage by Example
462 Hook usage is shown by some examples in this section. First, we will
463 define a hook of arity 2 --- that is, the procedures stored in the hook
464 will have to accept two arguments.
467 (define hook (make-hook 2))
469 @result{} #<hook 2 40286c90>
472 Now we are ready to add some procedures to the newly created hook with
473 @code{add-hook!}. In the following example, two procedures are added,
474 which print different messages and do different things with their
478 (add-hook! hook (lambda (x y)
482 (add-hook! hook (lambda (x y)
488 Once the procedures have been added, we can invoke the hook using
497 Note that the procedures are called in the reverse of the order with
498 which they were added. This is because the default behaviour of
499 @code{add-hook!} is to add its procedure to the @emph{front} of the
500 hook's procedure list. You can force @code{add-hook!} to add its
501 procedure to the @emph{end} of the list instead by providing a third
502 @code{#t} argument on the second call to @code{add-hook!}.
505 (add-hook! hook (lambda (x y)
509 (add-hook! hook (lambda (x y)
513 #t) ; @r{<- Change here!}
522 @subsubsection Hook Reference
524 When you create a hook with @code{make-hook}, you must specify the arity
525 of the procedures which can be added to the hook. If the arity is not
526 given explicitly as an argument to @code{make-hook}, it defaults to
527 zero. All procedures of a given hook must have the same arity, and when
528 the procedures are invoked using @code{run-hook}, the number of
529 arguments passed must match the arity specified at hook creation time.
531 The order in which procedures are added to a hook matters. If the third
532 parameter to @code{add-hook!} is omitted or is equal to @code{#f}, the
533 procedure is added in front of the procedures which might already be on
534 that hook, otherwise the procedure is added at the end. The procedures
535 are always called from the front to the end of the list when they are
536 invoked via @code{run-hook}.
538 The ordering of the list of procedures returned by @code{hook->list}
539 matches the order in which those procedures would be called if the hook
540 was run using @code{run-hook}.
542 Note that the C functions in the following entries are for handling
543 @dfn{Scheme-level} hooks in C. There are also @dfn{C-level} hooks which
544 have their own interface (@pxref{C Hooks}).
546 @deffn {Scheme Procedure} make-hook [n_args]
547 @deffnx {C Function} scm_make_hook (n_args)
548 Create a hook for storing procedure of arity @var{n_args}.
549 @var{n_args} defaults to zero. The returned value is a hook
550 object to be used with the other hook procedures.
553 @deffn {Scheme Procedure} hook? x
554 @deffnx {C Function} scm_hook_p (x)
555 Return @code{#t} if @var{x} is a hook, @code{#f} otherwise.
558 @deffn {Scheme Procedure} hook-empty? hook
559 @deffnx {C Function} scm_hook_empty_p (hook)
560 Return @code{#t} if @var{hook} is an empty hook, @code{#f}
564 @deffn {Scheme Procedure} add-hook! hook proc [append_p]
565 @deffnx {C Function} scm_add_hook_x (hook, proc, append_p)
566 Add the procedure @var{proc} to the hook @var{hook}. The
567 procedure is added to the end if @var{append_p} is true,
568 otherwise it is added to the front. The return value of this
569 procedure is not specified.
572 @deffn {Scheme Procedure} remove-hook! hook proc
573 @deffnx {C Function} scm_remove_hook_x (hook, proc)
574 Remove the procedure @var{proc} from the hook @var{hook}. The
575 return value of this procedure is not specified.
578 @deffn {Scheme Procedure} reset-hook! hook
579 @deffnx {C Function} scm_reset_hook_x (hook)
580 Remove all procedures from the hook @var{hook}. The return
581 value of this procedure is not specified.
584 @deffn {Scheme Procedure} hook->list hook
585 @deffnx {C Function} scm_hook_to_list (hook)
586 Convert the procedure list of @var{hook} to a list.
589 @deffn {Scheme Procedure} run-hook hook arg @dots{}
590 @deffnx {C Function} scm_run_hook (hook, args)
591 Apply all procedures from the hook @var{hook} to the arguments @var{arg}
592 @enddots{}. The order of the procedure application is first to last.
593 The return value of this procedure is not specified.
596 If, in C code, you are certain that you have a hook object and well
597 formed argument list for that hook, you can also use
598 @code{scm_c_run_hook}, which is identical to @code{scm_run_hook} but
599 does no type checking.
601 @deftypefn {C Function} void scm_c_run_hook (SCM hook, SCM args)
602 The same as @code{scm_run_hook} but without any type checking to confirm
603 that @var{hook} is actually a hook object and that @var{args} is a
604 well-formed list matching the arity of the hook.
607 For C code, @code{SCM_HOOKP} is a faster alternative to
610 @deftypefn {C Macro} int SCM_HOOKP (x)
611 Return 1 if @var{x} is a Scheme-level hook, 0 otherwise.
615 @subsubsection Handling Scheme-level hooks from C code
617 Here is an example of how to handle Scheme-level hooks from C code using
621 if (scm_is_true (scm_hook_p (obj)))
622 /* handle Scheme-level hook using C functions */
623 scm_reset_hook_x (obj);
625 /* do something else (obj is not a hook) */
630 @subsubsection Hooks For C Code.
632 The hooks already described are intended to be populated by Scheme-level
633 procedures. In addition to this, the Guile library provides an
634 independent set of interfaces for the creation and manipulation of hooks
635 that are designed to be populated by functions implemented in C.
637 The original motivation here was to provide a kind of hook that could
638 safely be invoked at various points during garbage collection.
639 Scheme-level hooks are unsuitable for this purpose as running them could
640 itself require memory allocation, which would then invoke garbage
641 collection recursively @dots{} However, it is also the case that these
642 hooks are easier to work with than the Scheme-level ones if you only
643 want to register C functions with them. So if that is mainly what your
644 code needs to do, you may prefer to use this interface.
646 To create a C hook, you should allocate storage for a structure of type
647 @code{scm_t_c_hook} and then initialize it using @code{scm_c_hook_init}.
649 @deftp {C Type} scm_t_c_hook
650 Data type for a C hook. The internals of this type should be treated as
654 @deftp {C Enum} scm_t_c_hook_type
655 Enumeration of possible hook types, which are:
658 @item SCM_C_HOOK_NORMAL
659 @vindex SCM_C_HOOK_NORMAL
660 Type of hook for which all the registered functions will always be called.
662 @vindex SCM_C_HOOK_OR
663 Type of hook for which the sequence of registered functions will be
664 called only until one of them returns C true (a non-NULL pointer).
666 @vindex SCM_C_HOOK_AND
667 Type of hook for which the sequence of registered functions will be
668 called only until one of them returns C false (a NULL pointer).
672 @deftypefn {C Function} void scm_c_hook_init (scm_t_c_hook *hook, void *hook_data, scm_t_c_hook_type type)
673 Initialize the C hook at memory pointed to by @var{hook}. @var{type}
674 should be one of the values of the @code{scm_t_c_hook_type} enumeration,
675 and controls how the hook functions will be called. @var{hook_data} is
676 a closure parameter that will be passed to all registered hook functions
677 when they are called.
680 To add or remove a C function from a C hook, use @code{scm_c_hook_add}
681 or @code{scm_c_hook_remove}. A hook function must expect three
682 @code{void *} parameters which are, respectively:
686 The hook closure data that was specified at the time the hook was
687 initialized by @code{scm_c_hook_init}.
690 The function closure data that was specified at the time that that
691 function was registered with the hook by @code{scm_c_hook_add}.
694 The call closure data specified by the @code{scm_c_hook_run} call that
698 @deftp {C Type} scm_t_c_hook_function
699 Function type for a C hook function: takes three @code{void *}
700 parameters and returns a @code{void *} result.
703 @deftypefn {C Function} void scm_c_hook_add (scm_t_c_hook *hook, scm_t_c_hook_function func, void *func_data, int appendp)
704 Add function @var{func}, with function closure data @var{func_data}, to
705 the C hook @var{hook}. The new function is appended to the hook's list
706 of functions if @var{appendp} is non-zero, otherwise prepended.
709 @deftypefn {C Function} void scm_c_hook_remove (scm_t_c_hook *hook, scm_t_c_hook_function func, void *func_data)
710 Remove function @var{func}, with function closure data @var{func_data},
711 from the C hook @var{hook}. @code{scm_c_hook_remove} checks both
712 @var{func} and @var{func_data} so as to allow for the same @var{func}
713 being registered multiple times with different closure data.
716 Finally, to invoke a C hook, call the @code{scm_c_hook_run} function
717 specifying the hook and the call closure data for this run:
719 @deftypefn {C Function} {void *} scm_c_hook_run (scm_t_c_hook *hook, void *data)
720 Run the C hook @var{hook} will call closure data @var{data}. Subject to
721 the variations for hook types @code{SCM_C_HOOK_OR} and
722 @code{SCM_C_HOOK_AND}, @code{scm_c_hook_run} calls @var{hook}'s
723 registered functions in turn, passing them the hook's closure data, each
724 function's closure data, and the call closure data.
726 @code{scm_c_hook_run}'s return value is the return value of the last
727 function to be called.
732 @subsubsection Hooks for Garbage Collection
734 Whenever Guile performs a garbage collection, it calls the following
735 hooks in the order shown.
737 @defvr {C Hook} scm_before_gc_c_hook
738 C hook called at the very start of a garbage collection, after setting
739 @code{scm_gc_running_p} to 1, but before entering the GC critical
742 If garbage collection is blocked because @code{scm_block_gc} is
743 non-zero, GC exits early soon after calling this hook, and no further
744 hooks will be called.
747 @defvr {C Hook} scm_before_mark_c_hook
748 C hook called before beginning the mark phase of garbage collection,
749 after the GC thread has entered a critical section.
752 @defvr {C Hook} scm_before_sweep_c_hook
753 C hook called before beginning the sweep phase of garbage collection.
754 This is the same as at the end of the mark phase, since nothing else
755 happens between marking and sweeping.
758 @defvr {C Hook} scm_after_sweep_c_hook
759 C hook called after the end of the sweep phase of garbage collection,
760 but while the GC thread is still inside its critical section.
763 @defvr {C Hook} scm_after_gc_c_hook
764 C hook called at the very end of a garbage collection, after the GC
765 thread has left its critical section.
768 @defvr {Scheme Hook} after-gc-hook
769 @vindex scm_after_gc_hook
770 Scheme hook with arity 0. This hook is run asynchronously
771 (@pxref{Asyncs}) soon after the GC has completed and any other events
772 that were deferred during garbage collection have been processed. (Also
773 accessible from C with the name @code{scm_after_gc_hook}.)
776 All the C hooks listed here have type @code{SCM_C_HOOK_NORMAL}, are
777 initialized with hook closure data NULL, are invoked by
778 @code{scm_c_hook_run} with call closure data NULL.
780 @cindex guardians, testing for GC'd objects
781 The Scheme hook @code{after-gc-hook} is particularly useful in
782 conjunction with guardians (@pxref{Guardians}). Typically, if you are
783 using a guardian, you want to call the guardian after garbage collection
784 to see if any of the objects added to the guardian have been collected.
785 By adding a thunk that performs this call to @code{after-gc-hook}, you
786 can ensure that your guardian is tested after every garbage collection
791 @subsubsection Hooks into the Guile REPL
795 @c TeX-master: "guile.texi"