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.
32 There are three kinds of core equality predicates in Scheme, described
33 below. The same kinds of comparisons arise in other functions, like
34 @code{memq} and friends (@pxref{List Searching}).
36 For all three tests, objects of different types are never equal. So
37 for instance a list and a vector are not @code{equal?}, even if their
38 contents are the same. Exact and inexact numbers are considered
39 different types too, and are hence not equal even if their values are
42 @code{eq?} tests just for the same object (essentially a pointer
43 comparison). This is fast, and can be used when searching for a
44 particular object, or when working with symbols or keywords (which are
45 always unique objects).
47 @code{eqv?} extends @code{eq?} to look at the value of numbers and
48 characters. It can for instance be used somewhat like @code{=}
49 (@pxref{Comparison}) but without an error if one operand isn't a
52 @code{equal?} goes further, it looks (recursively) into the contents
53 of lists, vectors, etc. This is good for instance on lists that have
54 been read or calculated in various places and are the same, just not
55 made up of the same pairs. Such lists look the same (when printed),
56 and @code{equal?} will consider them the same.
59 @deffn {Scheme Procedure} eq? x y
60 @deffnx {C Function} scm_eq_p (x, y)
62 Return @code{#t} if @var{x} and @var{y} are the same object, except
63 for numbers and characters. For example,
66 (define x (vector 1 2 3))
67 (define y (vector 1 2 3))
69 (eq? x x) @result{} #t
70 (eq? x y) @result{} #f
73 Numbers and characters are not equal to any other object, but the
74 problem is they're not necessarily @code{eq?} to themselves either.
75 This is even so when the number comes directly from a variable,
79 (eq? n n)) @result{} *unspecified*
82 Generally @code{eqv?} below should be used when comparing numbers or
83 characters. @code{=} (@pxref{Comparison}) or @code{char=?}
84 (@pxref{Characters}) can be used too.
86 It's worth noting that end-of-list @code{()}, @code{#t}, @code{#f}, a
87 symbol of a given name, and a keyword of a given name, are unique
88 objects. There's just one of each, so for instance no matter how
89 @code{()} arises in a program, it's the same object and can be
90 compared with @code{eq?},
93 (define x (cdr '(123)))
94 (define y (cdr '(456)))
95 (eq? x y) @result{} #t
97 (define x (string->symbol "foo"))
98 (eq? x 'foo) @result{} #t
102 @deftypefn {C Function} int scm_is_eq (SCM x, SCM y)
103 Return @code{1} when @var{x} and @var{y} are equal in the sense of
104 @code{eq?}, otherwise return @code{0}.
107 The @code{==} operator should not be used on @code{SCM} values, an
108 @code{SCM} is a C type which cannot necessarily be compared using
109 @code{==} (@pxref{The SCM Type}).
113 @deffn {Scheme Procedure} eqv? x y
114 @deffnx {C Function} scm_eqv_p (x, y)
116 Return @code{#t} if @var{x} and @var{y} are the same object, or for
117 characters and numbers the same value.
119 On objects except characters and numbers, @code{eqv?} is the same as
120 @code{eq?} above, it's true if @var{x} and @var{y} are the same
123 If @var{x} and @var{y} are numbers or characters, @code{eqv?} compares
124 their type and value. An exact number is not @code{eqv?} to an
125 inexact number (even if their value is the same).
128 (eqv? 3 (+ 1 2)) @result{} #t
129 (eqv? 1 1.0) @result{} #f
134 @deffn {Scheme Procedure} equal? x y
135 @deffnx {C Function} scm_equal_p (x, y)
137 Return @code{#t} if @var{x} and @var{y} are the same type, and their
138 contents or value are equal.
140 For a pair, string, vector, array or structure, @code{equal?} compares the
141 contents, and does so using using the same @code{equal?} recursively,
142 so a deep structure can be traversed.
145 (equal? (list 1 2 3) (list 1 2 3)) @result{} #t
146 (equal? (list 1 2 3) (vector 1 2 3)) @result{} #f
149 For other objects, @code{equal?} compares as per @code{eqv?} above,
150 which means characters and numbers are compared by type and value (and
151 like @code{eqv?}, exact and inexact numbers are not @code{equal?},
152 even if their value is the same).
155 (equal? 3 (+ 1 2)) @result{} #t
156 (equal? 1 1.0) @result{} #f
159 Hash tables are currently only compared as per @code{eq?}, so two
160 different tables are not @code{equal?}, even if their contents are the
163 @code{equal?} does not support circular data structures, it may go
164 into an infinite loop if asked to compare two circular lists or
167 New application-defined object types (@pxref{Defining New Types
168 (Smobs)}) have an @code{equalp} handler which is called by
169 @code{equal?}. This lets an application traverse the contents or
170 control what is considered @code{equal?} for two objects of such a
171 type. If there's no such handler, the default is to just compare as
176 @node Object Properties
177 @subsection Object Properties
179 It's often useful to associate a piece of additional information with a
180 Scheme object even though that object does not have a dedicated slot
181 available in which the additional information could be stored. Object
182 properties allow you to do just that.
184 Guile's representation of an object property is a procedure-with-setter
185 (@pxref{Procedures with Setters}) that can be used with the generalized
186 form of @code{set!} (REFFIXME) to set and retrieve that property for any
187 Scheme object. So, setting a property looks like this:
190 (set! (my-property obj1) value-for-obj1)
191 (set! (my-property obj2) value-for-obj2)
195 And retrieving values of the same property looks like this:
207 To create an object property in the first place, use the
208 @code{make-object-property} procedure:
211 (define my-property (make-object-property))
214 @deffn {Scheme Procedure} make-object-property
215 Create and return an object property. An object property is a
216 procedure-with-setter that can be called in two ways. @code{(set!
217 (@var{property} @var{obj}) @var{val})} sets @var{obj}'s @var{property}
218 to @var{val}. @code{(@var{property} @var{obj})} returns the current
219 setting of @var{obj}'s @var{property}.
222 A single object property created by @code{make-object-property} can
223 associate distinct property values with all Scheme values that are
224 distinguishable by @code{eq?} (including, for example, integers).
226 Internally, object properties are implemented using a weak key hash
227 table. This means that, as long as a Scheme value with property values
228 is protected from garbage collection, its property values are also
229 protected. When the Scheme value is collected, its entry in the
230 property table is removed and so the (ex-) property values are no longer
231 protected by the table.
234 * Property Primitives:: Low level property implementation.
235 * Old-fashioned Properties:: An older approach to properties.
239 @node Property Primitives
240 @subsubsection Low Level Property Implementation.
242 @deffn {Scheme Procedure} primitive-make-property not-found-proc
243 @deffnx {C Function} scm_primitive_make_property (not_found_proc)
244 Create a @dfn{property token} that can be used with
245 @code{primitive-property-ref} and @code{primitive-property-set!}.
246 See @code{primitive-property-ref} for the significance of
247 @var{not-found-proc}.
250 @deffn {Scheme Procedure} primitive-property-ref prop obj
251 @deffnx {C Function} scm_primitive_property_ref (prop, obj)
252 Return the property @var{prop} of @var{obj}.
254 When no value has yet been associated with @var{prop} and @var{obj},
255 the @var{not-found-proc} from @var{prop} is used. A call
256 @code{(@var{not-found-proc} @var{prop} @var{obj})} is made and the
257 result set as the property value. If @var{not-found-proc} is
258 @code{#f} then @code{#f} is the property value.
261 @deffn {Scheme Procedure} primitive-property-set! prop obj val
262 @deffnx {C Function} scm_primitive_property_set_x (prop, obj, val)
263 Set the property @var{prop} of @var{obj} to @var{val}.
266 @deffn {Scheme Procedure} primitive-property-del! prop obj
267 @deffnx {C Function} scm_primitive_property_del_x (prop, obj)
268 Remove any value associated with @var{prop} and @var{obj}.
272 @node Old-fashioned Properties
273 @subsubsection An Older Approach to Properties
275 Traditionally, Lisp systems provide a different object property
276 interface to that provided by @code{make-object-property}, in which the
277 object property that is being set or retrieved is indicated by a symbol.
279 Guile includes this older kind of interface as well, but it may well be
280 removed in a future release, as it is less powerful than
281 @code{make-object-property} and so increases the size of the Guile
282 library for no benefit. (And it is trivial to write a compatibility
285 @deffn {Scheme Procedure} object-properties obj
286 @deffnx {C Function} scm_object_properties (obj)
287 Return @var{obj}'s property list.
290 @deffn {Scheme Procedure} set-object-properties! obj alist
291 @deffnx {C Function} scm_set_object_properties_x (obj, alist)
292 Set @var{obj}'s property list to @var{alist}.
295 @deffn {Scheme Procedure} object-property obj key
296 @deffnx {C Function} scm_object_property (obj, key)
297 Return the property of @var{obj} with name @var{key}.
300 @deffn {Scheme Procedure} set-object-property! obj key value
301 @deffnx {C Function} scm_set_object_property_x (obj, key, value)
302 In @var{obj}'s property list, set the property named @var{key}
310 @c FIXME::martin: Review me!
313 @cindex sorting lists
314 @cindex sorting vectors
316 Sorting is very important in computer programs. Therefore, Guile comes
317 with several sorting procedures built-in. As always, procedures with
318 names ending in @code{!} are side-effecting, that means that they may
319 modify their parameters in order to produce their results.
321 The first group of procedures can be used to merge two lists (which must
322 be already sorted on their own) and produce sorted lists containing
323 all elements of the input lists.
325 @deffn {Scheme Procedure} merge alist blist less
326 @deffnx {C Function} scm_merge (alist, blist, less)
327 Merge two already sorted lists into one.
328 Given two lists @var{alist} and @var{blist}, such that
329 @code{(sorted? alist less?)} and @code{(sorted? blist less?)},
330 return a new list in which the elements of @var{alist} and
331 @var{blist} have been stably interleaved so that
332 @code{(sorted? (merge alist blist less?) less?)}.
333 Note: this does _not_ accept vectors.
336 @deffn {Scheme Procedure} merge! alist blist less
337 @deffnx {C Function} scm_merge_x (alist, blist, less)
338 Takes two lists @var{alist} and @var{blist} such that
339 @code{(sorted? alist less?)} and @code{(sorted? blist less?)} and
340 returns a new list in which the elements of @var{alist} and
341 @var{blist} have been stably interleaved so that
342 @code{(sorted? (merge alist blist less?) less?)}.
343 This is the destructive variant of @code{merge}
344 Note: this does _not_ accept vectors.
347 The following procedures can operate on sequences which are either
348 vectors or list. According to the given arguments, they return sorted
349 vectors or lists, respectively. The first of the following procedures
350 determines whether a sequence is already sorted, the other sort a given
351 sequence. The variants with names starting with @code{stable-} are
352 special in that they maintain a special property of the input sequences:
353 If two or more elements are the same according to the comparison
354 predicate, they are left in the same order as they appeared in the
357 @deffn {Scheme Procedure} sorted? items less
358 @deffnx {C Function} scm_sorted_p (items, less)
359 Return @code{#t} iff @var{items} is a list or a vector such that
360 for all 1 <= i <= m, the predicate @var{less} returns true when
361 applied to all elements i - 1 and i
364 @deffn {Scheme Procedure} sort items less
365 @deffnx {C Function} scm_sort (items, less)
366 Sort the sequence @var{items}, which may be a list or a
367 vector. @var{less} is used for comparing the sequence
368 elements. This is not a stable sort.
371 @deffn {Scheme Procedure} sort! items less
372 @deffnx {C Function} scm_sort_x (items, less)
373 Sort the sequence @var{items}, which may be a list or a
374 vector. @var{less} is used for comparing the sequence
375 elements. The sorting is destructive, that means that the
376 input sequence is modified to produce the sorted result.
377 This is not a stable sort.
380 @deffn {Scheme Procedure} stable-sort items less
381 @deffnx {C Function} scm_stable_sort (items, less)
382 Sort the sequence @var{items}, which may be a list or a
383 vector. @var{less} is used for comparing the sequence elements.
384 This is a stable sort.
387 @deffn {Scheme Procedure} stable-sort! items less
388 @deffnx {C Function} scm_stable_sort_x (items, less)
389 Sort the sequence @var{items}, which may be a list or a
390 vector. @var{less} is used for comparing the sequence elements.
391 The sorting is destructive, that means that the input sequence
392 is modified to produce the sorted result.
393 This is a stable sort.
396 The procedures in the last group only accept lists or vectors as input,
397 as their names indicate.
399 @deffn {Scheme Procedure} sort-list items less
400 @deffnx {C Function} scm_sort_list (items, less)
401 Sort the list @var{items}, using @var{less} for comparing the
402 list elements. This is a stable sort.
405 @deffn {Scheme Procedure} sort-list! items less
406 @deffnx {C Function} scm_sort_list_x (items, less)
407 Sort the list @var{items}, using @var{less} for comparing the
408 list elements. The sorting is destructive, that means that the
409 input list is modified to produce the sorted result.
410 This is a stable sort.
413 @deffn {Scheme Procedure} restricted-vector-sort! vec less startpos endpos
414 @deffnx {C Function} scm_restricted_vector_sort_x (vec, less, startpos, endpos)
415 Sort the vector @var{vec}, using @var{less} for comparing
416 the vector elements. @var{startpos} (inclusively) and
417 @var{endpos} (exclusively) delimit
418 the range of the vector which gets sorted. The return value
424 @subsection Copying Deep Structures
426 @c FIXME::martin: Review me!
428 The procedures for copying lists (@pxref{Lists}) only produce a flat
429 copy of the input list, and currently Guile does not even contain
430 procedures for copying vectors. @code{copy-tree} can be used for these
431 application, as it does not only copy the spine of a list, but also
432 copies any pairs in the cars of the input lists.
434 @deffn {Scheme Procedure} copy-tree obj
435 @deffnx {C Function} scm_copy_tree (obj)
436 Recursively copy the data tree that is bound to @var{obj}, and return a
437 the new data structure. @code{copy-tree} recurses down the
438 contents of both pairs and vectors (since both cons cells and vector
439 cells may point to arbitrary objects), and stops recursing when it hits
444 @node General Conversion
445 @subsection General String Conversion
447 @c FIXME::martin: Review me!
449 When debugging Scheme programs, but also for providing a human-friendly
450 interface, a procedure for converting any Scheme object into string
451 format is very useful. Conversion from/to strings can of course be done
452 with specialized procedures when the data type of the object to convert
453 is known, but with this procedure, it is often more comfortable.
455 @code{object->string} converts an object by using a print procedure for
456 writing to a string port, and then returning the resulting string.
457 Converting an object back from the string is only possible if the object
458 type has a read syntax and the read syntax is preserved by the printing
461 @deffn {Scheme Procedure} object->string obj [printer]
462 @deffnx {C Function} scm_object_to_string (obj, printer)
463 Return a Scheme string obtained by printing @var{obj}.
464 Printing function can be specified by the optional second
465 argument @var{printer} (default: @code{write}).
473 A hook is a list of procedures to be called at well defined points in
474 time. Typically, an application provides a hook @var{h} and promises
475 its users that it will call all of the procedures in @var{h} at a
476 defined point in the application's processing. By adding its own
477 procedure to @var{h}, an application user can tap into or even influence
478 the progress of the application.
480 Guile itself provides several such hooks for debugging and customization
481 purposes: these are listed in a subsection below.
483 When an application first creates a hook, it needs to know how many
484 arguments will be passed to the hook's procedures when the hook is run.
485 The chosen number of arguments (which may be none) is declared when the
486 hook is created, and all the procedures that are added to that hook must
487 be capable of accepting that number of arguments.
489 A hook is created using @code{make-hook}. A procedure can be added to
490 or removed from a hook using @code{add-hook!} or @code{remove-hook!},
491 and all of a hook's procedures can be removed together using
492 @code{reset-hook!}. When an application wants to run a hook, it does so
493 using @code{run-hook}.
496 * Hook Example:: Hook usage by example.
497 * Hook Reference:: Reference of all hook procedures.
498 * C Hooks:: Hooks for use from C code.
499 * GC Hooks:: Garbage collection hooks.
500 * REPL Hooks:: Hooks into the Guile REPL.
505 @subsubsection Hook Usage by Example
507 Hook usage is shown by some examples in this section. First, we will
508 define a hook of arity 2 --- that is, the procedures stored in the hook
509 will have to accept two arguments.
512 (define hook (make-hook 2))
514 @result{} #<hook 2 40286c90>
517 Now we are ready to add some procedures to the newly created hook with
518 @code{add-hook!}. In the following example, two procedures are added,
519 which print different messages and do different things with their
523 (add-hook! hook (lambda (x y)
527 (add-hook! hook (lambda (x y)
533 Once the procedures have been added, we can invoke the hook using
542 Note that the procedures are called in the reverse of the order with
543 which they were added. This is because the default behaviour of
544 @code{add-hook!} is to add its procedure to the @emph{front} of the
545 hook's procedure list. You can force @code{add-hook!} to add its
546 procedure to the @emph{end} of the list instead by providing a third
547 @code{#t} argument on the second call to @code{add-hook!}.
550 (add-hook! hook (lambda (x y)
554 (add-hook! hook (lambda (x y)
558 #t) ; @r{<- Change here!}
567 @subsubsection Hook Reference
569 When you create a hook with @code{make-hook}, you must specify the arity
570 of the procedures which can be added to the hook. If the arity is not
571 given explicitly as an argument to @code{make-hook}, it defaults to
572 zero. All procedures of a given hook must have the same arity, and when
573 the procedures are invoked using @code{run-hook}, the number of
574 arguments passed must match the arity specified at hook creation time.
576 The order in which procedures are added to a hook matters. If the third
577 parameter to @code{add-hook!} is omitted or is equal to @code{#f}, the
578 procedure is added in front of the procedures which might already be on
579 that hook, otherwise the procedure is added at the end. The procedures
580 are always called from the front to the end of the list when they are
581 invoked via @code{run-hook}.
583 The ordering of the list of procedures returned by @code{hook->list}
584 matches the order in which those procedures would be called if the hook
585 was run using @code{run-hook}.
587 Note that the C functions in the following entries are for handling
588 @dfn{Scheme-level} hooks in C. There are also @dfn{C-level} hooks which
589 have their own interface (@pxref{C Hooks}).
591 @deffn {Scheme Procedure} make-hook [n_args]
592 @deffnx {C Function} scm_make_hook (n_args)
593 Create a hook for storing procedure of arity @var{n_args}.
594 @var{n_args} defaults to zero. The returned value is a hook
595 object to be used with the other hook procedures.
598 @deffn {Scheme Procedure} hook? x
599 @deffnx {C Function} scm_hook_p (x)
600 Return @code{#t} if @var{x} is a hook, @code{#f} otherwise.
603 @deffn {Scheme Procedure} hook-empty? hook
604 @deffnx {C Function} scm_hook_empty_p (hook)
605 Return @code{#t} if @var{hook} is an empty hook, @code{#f}
609 @deffn {Scheme Procedure} add-hook! hook proc [append_p]
610 @deffnx {C Function} scm_add_hook_x (hook, proc, append_p)
611 Add the procedure @var{proc} to the hook @var{hook}. The
612 procedure is added to the end if @var{append_p} is true,
613 otherwise it is added to the front. The return value of this
614 procedure is not specified.
617 @deffn {Scheme Procedure} remove-hook! hook proc
618 @deffnx {C Function} scm_remove_hook_x (hook, proc)
619 Remove the procedure @var{proc} from the hook @var{hook}. The
620 return value of this procedure is not specified.
623 @deffn {Scheme Procedure} reset-hook! hook
624 @deffnx {C Function} scm_reset_hook_x (hook)
625 Remove all procedures from the hook @var{hook}. The return
626 value of this procedure is not specified.
629 @deffn {Scheme Procedure} hook->list hook
630 @deffnx {C Function} scm_hook_to_list (hook)
631 Convert the procedure list of @var{hook} to a list.
634 @deffn {Scheme Procedure} run-hook hook . args
635 @deffnx {C Function} scm_run_hook (hook, args)
636 Apply all procedures from the hook @var{hook} to the arguments
637 @var{args}. The order of the procedure application is first to
638 last. The return value of this procedure is not specified.
641 If, in C code, you are certain that you have a hook object and well
642 formed argument list for that hook, you can also use
643 @code{scm_c_run_hook}, which is identical to @code{scm_run_hook} but
644 does no type checking.
646 @deftypefn {C Function} void scm_c_run_hook (SCM hook, SCM args)
647 The same as @code{scm_run_hook} but without any type checking to confirm
648 that @var{hook} is actually a hook object and that @var{args} is a
649 well-formed list matching the arity of the hook.
652 For C code, @code{SCM_HOOKP} is a faster alternative to
655 @deftypefn {C Macro} int SCM_HOOKP (x)
656 Return 1 if @var{x} is a Scheme-level hook, 0 otherwise.
660 @subsubsection Handling Scheme-level hooks from C code
662 Here is an example of how to handle Scheme-level hooks from C code using
666 if (scm_is_true (scm_hook_p (obj)))
667 /* handle Scheme-level hook using C functions */
668 scm_reset_hook_x (obj);
670 /* do something else (obj is not a hook) */
675 @subsubsection Hooks For C Code.
677 The hooks already described are intended to be populated by Scheme-level
678 procedures. In addition to this, the Guile library provides an
679 independent set of interfaces for the creation and manipulation of hooks
680 that are designed to be populated by functions implemented in C.
682 The original motivation here was to provide a kind of hook that could
683 safely be invoked at various points during garbage collection.
684 Scheme-level hooks are unsuitable for this purpose as running them could
685 itself require memory allocation, which would then invoke garbage
686 collection recursively @dots{} However, it is also the case that these
687 hooks are easier to work with than the Scheme-level ones if you only
688 want to register C functions with them. So if that is mainly what your
689 code needs to do, you may prefer to use this interface.
691 To create a C hook, you should allocate storage for a structure of type
692 @code{scm_t_c_hook} and then initialize it using @code{scm_c_hook_init}.
694 @deftp {C Type} scm_t_c_hook
695 Data type for a C hook. The internals of this type should be treated as
699 @deftp {C Enum} scm_t_c_hook_type
700 Enumeration of possible hook types, which are:
703 @item SCM_C_HOOK_NORMAL
704 @vindex SCM_C_HOOK_NORMAL
705 Type of hook for which all the registered functions will always be called.
707 @vindex SCM_C_HOOK_OR
708 Type of hook for which the sequence of registered functions will be
709 called only until one of them returns C true (a non-NULL pointer).
711 @vindex SCM_C_HOOK_AND
712 Type of hook for which the sequence of registered functions will be
713 called only until one of them returns C false (a NULL pointer).
717 @deftypefn {C Function} void scm_c_hook_init (scm_t_c_hook *hook, void *hook_data, scm_t_c_hook_type type)
718 Initialize the C hook at memory pointed to by @var{hook}. @var{type}
719 should be one of the values of the @code{scm_t_c_hook_type} enumeration,
720 and controls how the hook functions will be called. @var{hook_data} is
721 a closure parameter that will be passed to all registered hook functions
722 when they are called.
725 To add or remove a C function from a C hook, use @code{scm_c_hook_add}
726 or @code{scm_c_hook_remove}. A hook function must expect three
727 @code{void *} parameters which are, respectively:
731 The hook closure data that was specified at the time the hook was
732 initialized by @code{scm_c_hook_init}.
735 The function closure data that was specified at the time that that
736 function was registered with the hook by @code{scm_c_hook_add}.
739 The call closure data specified by the @code{scm_c_hook_run} call that
743 @deftp {C Type} scm_t_c_hook_function
744 Function type for a C hook function: takes three @code{void *}
745 parameters and returns a @code{void *} result.
748 @deftypefn {C Function} void scm_c_hook_add (scm_t_c_hook *hook, scm_t_c_hook_function func, void *func_data, int appendp)
749 Add function @var{func}, with function closure data @var{func_data}, to
750 the C hook @var{hook}. The new function is appended to the hook's list
751 of functions if @var{appendp} is non-zero, otherwise prepended.
754 @deftypefn {C Function} void scm_c_hook_remove (scm_t_c_hook *hook, scm_t_c_hook_function func, void *func_data)
755 Remove function @var{func}, with function closure data @var{func_data},
756 from the C hook @var{hook}. @code{scm_c_hook_remove} checks both
757 @var{func} and @var{func_data} so as to allow for the same @var{func}
758 being registered multiple times with different closure data.
761 Finally, to invoke a C hook, call the @code{scm_c_hook_run} function
762 specifying the hook and the call closure data for this run:
764 @deftypefn {C Function} {void *} scm_c_hook_run (scm_t_c_hook *hook, void *data)
765 Run the C hook @var{hook} will call closure data @var{data}. Subject to
766 the variations for hook types @code{SCM_C_HOOK_OR} and
767 @code{SCM_C_HOOK_AND}, @code{scm_c_hook_run} calls @var{hook}'s
768 registered functions in turn, passing them the hook's closure data, each
769 function's closure data, and the call closure data.
771 @code{scm_c_hook_run}'s return value is the return value of the last
772 function to be called.
777 @subsubsection Hooks for Garbage Collection
779 Whenever Guile performs a garbage collection, it calls the following
780 hooks in the order shown.
782 @defvr {C Hook} scm_before_gc_c_hook
783 C hook called at the very start of a garbage collection, after setting
784 @code{scm_gc_running_p} to 1, but before entering the GC critical
787 If garbage collection is blocked because @code{scm_block_gc} is
788 non-zero, GC exits early soon after calling this hook, and no further
789 hooks will be called.
792 @defvr {C Hook} scm_before_mark_c_hook
793 C hook called before beginning the mark phase of garbage collection,
794 after the GC thread has entered a critical section.
797 @defvr {C Hook} scm_before_sweep_c_hook
798 C hook called before beginning the sweep phase of garbage collection.
799 This is the same as at the end of the mark phase, since nothing else
800 happens between marking and sweeping.
803 @defvr {C Hook} scm_after_sweep_c_hook
804 C hook called after the end of the sweep phase of garbage collection,
805 but while the GC thread is still inside its critical section.
808 @defvr {C Hook} scm_after_gc_c_hook
809 C hook called at the very end of a garbage collection, after the GC
810 thread has left its critical section.
813 @defvr {Scheme Hook} after-gc-hook
814 @vindex scm_after_gc_hook
815 Scheme hook with arity 0. This hook is run asynchronously
816 (@pxref{Asyncs}) soon after the GC has completed and any other events
817 that were deferred during garbage collection have been processed. (Also
818 accessible from C with the name @code{scm_after_gc_hook}.)
821 All the C hooks listed here have type @code{SCM_C_HOOK_NORMAL}, are
822 initialized with hook closure data NULL, are are invoked by
823 @code{scm_c_hook_run} with call closure data NULL.
825 @cindex guardians, testing for GC'd objects
826 The Scheme hook @code{after-gc-hook} is particularly useful in
827 conjunction with guardians (@pxref{Guardians}). Typically, if you are
828 using a guardian, you want to call the guardian after garbage collection
829 to see if any of the objects added to the guardian have been collected.
830 By adding a thunk that performs this call to @code{after-gc-hook}, you
831 can ensure that your guardian is tested after every garbage collection
836 @subsubsection Hooks into the Guile REPL
840 @c TeX-master: "guile.texi"