code:
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009
@c   Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.

@node Smobs
@section Smobs

@cindex smob

This chapter contains reference information related to defining and
working with smobs.  See @ref{Defining New Types (Smobs)} for a
tutorial-like introduction to smobs.

@deftypefun scm_t_bits scm_make_smob_type (const char *name, size_t size)
This function adds a new smob type, named @var{name}, with instance size
@var{size}, to the system.  The return value is a tag that is used in
creating instances of the type.

If @var{size} is 0, the default @emph{free} function will do nothing.

If @var{size} is not 0, the default @emph{free} function will
deallocate the memory block pointed to by @code{SCM_SMOB_DATA} with
@code{scm_gc_free}.  The @var{WHAT} parameter in the call to
@code{scm_gc_free} will be @var{NAME}.

Default values are provided for the @emph{mark}, @emph{free},
@emph{print}, and @emph{equalp} functions, as described in
@ref{Defining New Types (Smobs)}.  If you want to customize any of
these functions, the call to @code{scm_make_smob_type} should be
immediately followed by calls to one or several of
@code{scm_set_smob_mark}, @code{scm_set_smob_free},
@code{scm_set_smob_print}, and/or @code{scm_set_smob_equalp}.
@end deftypefun

@cindex finalizer
@cindex finalization

@deftypefn {C Function} void scm_set_smob_free (scm_t_bits tc, size_t (*free) (SCM obj))
This function sets the smob freeing procedure (sometimes referred to as
a @dfn{finalizer}) for the smob type specified by the tag
@var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.

The @var{free} procedure must deallocate all resources that are
directly associated with the smob instance @var{OBJ}.  It must assume
that all @code{SCM} values that it references have already been freed
and are thus invalid.

It must also not call any libguile function or macro except
@code{scm_gc_free}, @code{SCM_SMOB_FLAGS}, @code{SCM_SMOB_DATA},
@code{SCM_SMOB_DATA_2}, and @code{SCM_SMOB_DATA_3}.

The @var{free} procedure must return 0.

Note that defining a freeing procedure is not necessary if the resources
associated with @var{obj} consists only of memory allocated with
@code{scm_gc_malloc} or @code{scm_gc_malloc_pointerless} because this
memory is automatically reclaimed by the garbage collector when it is no
longer needed (@pxref{Memory Blocks, @code{scm_gc_malloc}}).
@end deftypefn

@cindex precise marking

@deftypefn {C Function} void scm_set_smob_mark (scm_t_bits tc, SCM (*mark) (SCM obj))
This function sets the smob marking procedure for the smob type specified by
the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.

Defining a marking procedure may sometimes be unnecessary because large
parts of the process' memory (with the exception of
@code{scm_gc_malloc_pointerless} regions, and @code{malloc}- or
@code{scm_malloc}-allocated memory) are scanned for live
pointers@footnote{Conversely, in Guile up to the 1.8 series, the marking
procedure was always required.  The reason is that Guile's GC would only
look for pointers in the memory area used for built-in types (the
@dfn{cell heap}), not in user-allocated or statically allocated memory.
This approach is often referred to as @dfn{precise marking}.}.

The @var{mark} procedure must cause @code{scm_gc_mark} to be called
for every @code{SCM} value that is directly referenced by the smob
instance @var{obj}.  One of these @code{SCM} values can be returned
from the procedure and Guile will call @code{scm_gc_mark} for it.
This can be used to avoid deep recursions for smob instances that form
a list.

It must not call any libguile function or macro except
@code{scm_gc_mark}, @code{SCM_SMOB_FLAGS}, @code{SCM_SMOB_DATA},
@code{SCM_SMOB_DATA_2}, and @code{SCM_SMOB_DATA_3}.
@end deftypefn

@deftypefn {C Function} void scm_set_smob_print (scm_t_bits tc, int (*print) (SCM obj, SCM port, scm_print_state* pstate))
This function sets the smob printing procedure for the smob type
specified by the tag @var{tc}. @var{tc} is the tag returned by
@code{scm_make_smob_type}.

The @var{print} procedure should output a textual representation of
the smob instance @var{obj} to @var{port}, using information in
@var{pstate}.

The textual representation should be of the form @code{#<name ...>}.
This ensures that @code{read} will not interpret it as some other
Scheme value.

It is often best to ignore @var{pstate} and just print to @var{port}
with @code{scm_display}, @code{scm_write}, @code{scm_simple_format},
and @code{scm_puts}.
@end deftypefn

@deftypefn {C Function} void scm_set_smob_equalp (scm_t_bits tc, SCM (*equalp) (SCM obj1, SCM obj1))
This function sets the smob equality-testing predicate for the smob
type specified by the tag @var{tc}. @var{tc} is the tag returned by
@code{scm_make_smob_type}.

The @var{equalp} procedure should return @code{SCM_BOOL_T} when
@var{obj1} is @code{equal?} to @var{obj2}.  Else it should return
@var{SCM_BOOL_F}.  Both @var{obj1} and @var{obj2} are instances of the
smob type @var{tc}.
@end deftypefn

@deftypefn {C Function} void scm_assert_smob_type (scm_t_bits tag, SCM val)
When @var{val} is a smob of the type indicated by @var{tag}, do nothing.
Else, signal an error.
@end deftypefn

@deftypefn {C Macro} int SCM_SMOB_PREDICATE (scm_t_bits tag, SCM exp)
Return true iff @var{exp} is a smob instance of the type indicated by
@var{tag}.  The expression @var{exp} can be evaluated more than once,
so it shouldn't contain any side effects.
@end deftypefn

@deftypefn {C Macro} void SCM_NEWSMOB (SCM value, scm_t_bits tag, void *data)
@deftypefnx {C Macro} void SCM_NEWSMOB2 (SCM value, scm_t_bits tag, void *data, void *data2)
@deftypefnx {C Macro} void SCM_NEWSMOB3 (SCM value, scm_t_bits tag, void *data, void *data2, void *data3)
Make @var{value} contain a smob instance of the type with tag
@var{tag} and smob data @var{data}, @var{data2}, and @var{data3}, as
appropriate.

The @var{tag} is what has been returned by @code{scm_make_smob_type}.
The initial values @var{data}, @var{data2}, and @var{data3} are of
type @code{scm_t_bits}; when you want to use them for @code{SCM}
values, these values need to be converted to a @code{scm_t_bits} first
by using @code{SCM_UNPACK}.

The flags of the smob instance start out as zero.
@end deftypefn

Since it is often the case (e.g., in smob constructors) that you will
create a smob instance and return it, there is also a slightly specialized
macro for this situation:

@deftypefn {C Macro} {} SCM_RETURN_NEWSMOB (scm_t_bits tag, void *data)
@deftypefnx {C Macro} {} SCM_RETURN_NEWSMOB2 (scm_t_bits tag, void *data1, void *data2)
@deftypefnx {C Macro} {} SCM_RETURN_NEWSMOB3 (scm_t_bits tag, void *data1, void *data2, void *data3)
This macro expands to a block of code that creates a smob instance of
the type with tag @var{tag} and smob data @var{data}, @var{data2}, and
@var{data3}, as with @code{SCM_NEWSMOB}, etc., and causes the
surrounding function to return that @code{SCM} value.  It should be
the last piece of code in a block.
@end deftypefn

@deftypefn {C Macro} scm_t_bits SCM_SMOB_FLAGS (SCM obj)
Return the 16 extra bits of the smob @var{obj}.  No meaning is
predefined for these bits, you can use them freely.
@end deftypefn

@deftypefn {C Macro} scm_t_bits SCM_SET_SMOB_FLAGS (SCM obj, scm_t_bits flags)
Set the 16 extra bits of the smob @var{obj} to @var{flags}.  No
meaning is predefined for these bits, you can use them freely.
@end deftypefn

@deftypefn {C Macro} scm_t_bits SCM_SMOB_DATA (SCM obj)
@deftypefnx {C Macro} scm_t_bits SCM_SMOB_DATA_2 (SCM obj)
@deftypefnx {C Macro} scm_t_bits SCM_SMOB_DATA_3 (SCM obj)
Return the first (second, third) immediate word of the smob @var{obj}
as a @code{scm_t_bits} value.  When the word contains a @code{SCM}
value, use @code{SCM_SMOB_OBJECT} (etc.) instead.
@end deftypefn

@deftypefn {C Macro} void SCM_SET_SMOB_DATA (SCM obj, scm_t_bits val)
@deftypefnx {C Macro} void SCM_SET_SMOB_DATA_2 (SCM obj, scm_t_bits val)
@deftypefnx {C Macro} void SCM_SET_SMOB_DATA_3 (SCM obj, scm_t_bits val)
Set the first (second, third) immediate word of the smob @var{obj} to
@var{val}.  When the word should be set to a @code{SCM} value, use
@code{SCM_SMOB_SET_OBJECT} (etc.) instead.
@end deftypefn

@deftypefn {C Macro} SCM SCM_SMOB_OBJECT (SCM obj)
@deftypefnx {C Macro} SCM SCM_SMOB_OBJECT_2 (SCM obj)
@deftypefnx {C Macro} SCM SCM_SMOB_OBJECT_3 (SCM obj)
Return the first (second, third) immediate word of the smob @var{obj}
as a @code{SCM} value.  When the word contains a @code{scm_t_bits}
value, use @code{SCM_SMOB_DATA} (etc.) instead.
@end deftypefn

@deftypefn {C Macro} void SCM_SET_SMOB_OBJECT (SCM obj, SCM val)
@deftypefnx {C Macro} void SCM_SET_SMOB_OBJECT_2 (SCM obj, SCM val)
@deftypefnx {C Macro} void SCM_SET_SMOB_OBJECT_3 (SCM obj, SCM val)
Set the first (second, third) immediate word of the smob @var{obj} to
@var{val}.  When the word should be set to a @code{scm_t_bits} value, use
@code{SCM_SMOB_SET_DATA} (etc.) instead.
@end deftypefn

@deftypefn {C Macro} {SCM *} SCM_SMOB_OBJECT_LOC (SCM obj)
@deftypefnx {C Macro} {SCM *} SCM_SMOB_OBJECT_2_LOC (SCM obj)
@deftypefnx {C Macro} {SCM *} SCM_SMOB_OBJECT_3_LOC (SCM obj)
Return a pointer to the first (second, third) immediate word of the
smob @var{obj}.  Note that this is a pointer to @code{SCM}.  If you
need to work with @code{scm_t_bits} values, use @code{SCM_PACK} and
@code{SCM_UNPACK}, as appropriate.
@end deftypefn

@deftypefun SCM scm_markcdr (SCM @var{x})
Mark the references in the smob @var{x}, assuming that @var{x}'s first
data word contains an ordinary Scheme object, and @var{x} refers to no
other objects.  This function simply returns @var{x}'s first data word.
@end deftypefun

@c Local Variables:
@c TeX-master: "guile.texi"
@c End:


code:
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
@c   Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.

@node Snarfing Macros
@section Snarfing Macros
@cindex guile-snarf recognized macros
@cindex guile-snarf deprecated macros

The following macros do two different things: when compiled normally,
they expand in one way; when processed during snarfing, they cause the
@code{guile-snarf} program to pick up some initialization code,
@xref{Function Snarfing}.

The descriptions below use the term `normally' to refer to the case
when the code is compiled normally, and `while snarfing' when the code
is processed by @code{guile-snarf}.

@deffn {C Macro} SCM_SNARF_INIT (code)

Normally, @code{SCM_SNARF_INIT} expands to nothing; while snarfing, it
causes @var{code} to be included in the initialization action file,
followed by a semicolon.

This is the fundamental macro for snarfing initialization actions.
The more specialized macros below use it internally.
@end deffn

@deffn {C Macro} SCM_DEFINE (c_name, scheme_name, req, opt, var, arglist, docstring)

Normally, this macro expands into

@smallexample
static const char s_@var{c_name}[] = @var{scheme_name};
SCM
@var{c_name} @var{arglist}
@end smallexample

While snarfing, it causes

@smallexample
scm_c_define_gsubr (s_@var{c_name}, @var{req}, @var{opt}, @var{var},
                    @var{c_name});
@end smallexample

to be added to the initialization actions.  Thus, you can use it to
declare a C function named @var{c_name} that will be made available to
Scheme with the name @var{scheme_name}.

Note that the @var{arglist} argument must have parentheses around it.
@end deffn

@deffn {C Macro} SCM_SYMBOL (c_name, scheme_name)
@deffnx {C Macro} SCM_GLOBAL_SYMBOL (c_name, scheme_name)
Normally, these macros expand into

@smallexample
static SCM @var{c_name}
@end smallexample

or

@smallexample
SCM @var{c_name}
@end smallexample

respectively.  While snarfing, they both expand into the
initialization code

@smallexample
@var{c_name} = scm_permanent_object (scm_from_locale_symbol (@var{scheme_name}));
@end smallexample

Thus, you can use them declare a static or global variable of type
@code{SCM} that will be initialized to the symbol named
@var{scheme_name}.
@end deffn

@deffn {C Macro} SCM_KEYWORD (c_name, scheme_name)
@deffnx {C Macro} SCM_GLOBAL_KEYWORD (c_name, scheme_name)
Normally, these macros expand into

@smallexample
static SCM @var{c_name}
@end smallexample

or

@smallexample
SCM @var{c_name}
@end smallexample

respectively.  While snarfing, they both expand into the
initialization code

@smallexample
@var{c_name} = scm_permanent_object (scm_c_make_keyword (@var{scheme_name}));
@end smallexample

Thus, you can use them declare a static or global variable of type
@code{SCM} that will be initialized to the keyword named
@var{scheme_name}.
@end deffn

@deffn {C Macro} SCM_VARIABLE (c_name, scheme_name)
@deffnx {C Macro} SCM_GLOBAL_VARIABLE (c_name, scheme_name)
These macros are equivalent to @code{SCM_VARIABLE_INIT} and
@code{SCM_GLOBAL_VARIABLE_INIT}, respectively, with a @var{value} of
@code{SCM_BOOL_F}.
@end deffn

@deffn {C Macro} SCM_VARIABLE_INIT (c_name, scheme_name, value)
@deffnx {C Macro} SCM_GLOBAL_VARIABLE_INIT (c_name, scheme_name, value)

Normally, these macros expand into

@smallexample
static SCM @var{c_name}
@end smallexample

or

@smallexample
SCM @var{c_name}
@end smallexample

respectively.  While snarfing, they both expand into the
initialization code

@smallexample
@var{c_name} = scm_permanent_object (scm_c_define (@var{scheme_name}, @var{value}));
@end smallexample

Thus, you can use them declare a static or global C variable of type
@code{SCM} that will be initialized to the object representing the
Scheme variable named @var{scheme_name} in the current module.  The
variable will be defined when it doesn't already exist.  It is always
set to @var{value}.
@end deffn

license: mit


code:
This file gathers entries that have been automatically generated from
docstrings in libguile.  They are not included in the manual, however,
for various reasons, mostly because they have been deprecated.  They
are here in this file to give docstring.el a chance to update them
automatically.

- The 'environments' are only in Guile by accident and are not used at
  all and we don't want to advertise them.

- GOOPS is documented in its own manual.

@deffn {Scheme Procedure} substring-move-right!
implemented by the C function "scm_substring_move_x"
@end deffn

@deffn {Scheme Procedure} substring-move-left!
implemented by the C function "scm_substring_move_x"
@end deffn

@deffn {Scheme Procedure} gentemp [prefix [obarray]]
@deffnx {C Function} scm_gentemp (prefix, obarray)
Create a new symbol with a name unique in an obarray.
The name is constructed from an optional string @var{prefix}
and a counter value.  The default prefix is @code{t}.  The
@var{obarray} is specified as a second optional argument.
Default is the system obarray where all normal symbols are
interned.  The counter is increased by 1 at each
call.  There is no provision for resetting the counter.
@end deffn

@deffn {Scheme Procedure} symbol-set! o s v
@deffnx {C Function} scm_symbol_set_x (o, s, v)
Find the symbol in @var{obarray} whose name is @var{string}, and rebind
it to @var{value}.  An error is signalled if @var{string} is not present
in @var{obarray}.
@end deffn

@deffn {Scheme Procedure} symbol-bound? o s
@deffnx {C Function} scm_symbol_bound_p (o, s)
Return @code{#t} if @var{obarray} contains a symbol with name
@var{string} bound to a defined value.  This differs from
@var{symbol-interned?} in that the mere mention of a symbol
usually causes it to be interned; @code{symbol-bound?}
determines whether a symbol has been given any meaningful
value.
@end deffn

@deffn {Scheme Procedure} symbol-binding o s
@deffnx {C Function} scm_symbol_binding (o, s)
Look up in @var{obarray} the symbol whose name is @var{string}, and
return the value to which it is bound.  If @var{obarray} is @code{#f},
use the global symbol table.  If @var{string} is not interned in
@var{obarray}, an error is signalled.
@end deffn

@deffn {Scheme Procedure} unintern-symbol o s
@deffnx {C Function} scm_unintern_symbol (o, s)
Remove the symbol with name @var{string} from @var{obarray}.  This
function returns @code{#t} if the symbol was present and @code{#f}
otherwise.
@end deffn

@deffn {Scheme Procedure} intern-symbol o s
@deffnx {C Function} scm_intern_symbol (o, s)
Add a new symbol to @var{obarray} with name @var{string}, bound to an
unspecified initial value.  The symbol table is not modified if a symbol
with this name is already present.
@end deffn

@deffn {Scheme Procedure} string->obarray-symbol o s [softp]
@deffnx {C Function} scm_string_to_obarray_symbol (o, s, softp)
Intern a new symbol in @var{obarray}, a symbol table, with name
@var{string}.

If @var{obarray} is @code{#f}, use the default system symbol table.  If
@var{obarray} is @code{#t}, the symbol should not be interned in any
symbol table; merely return the pair (@var{symbol}
. @var{#<undefined>}).

The @var{soft?} argument determines whether new symbol table entries
should be created when the specified symbol is not already present in
@var{obarray}.  If @var{soft?} is specified and is a true value, then
new entries should not be added for symbols not already present in the
table; instead, simply return @code{#f}.
@end deffn

@deffn {Scheme Procedure} read-and-eval! [port]
@deffnx {C Function} scm_read_and_eval_x (port)
Read a form from @var{port} (standard input by default), and evaluate it
(memoizing it in the process) in the top-level environment.  If no data
is left to be read from @var{port}, an @code{end-of-file} error is
signalled.
@end deffn

@deffn {Scheme Procedure} sloppy-member x lst
@deffnx {C Function} scm_sloppy_member (x, lst)
This procedure behaves like @code{member}, but does no type or error checking.
Its use is recommended only in writing Guile internals,
not for high-level Scheme programs.
@end deffn

@deffn {Scheme Procedure} sloppy-memv x lst
@deffnx {C Function} scm_sloppy_memv (x, lst)
This procedure behaves like @code{memv}, but does no type or error checking.
Its use is recommended only in writing Guile internals,
not for high-level Scheme programs.
@end deffn

@deffn {Scheme Procedure} sloppy-memq x lst
@deffnx {C Function} scm_sloppy_memq (x, lst)
This procedure behaves like @code{memq}, but does no type or error checking.
Its use is recommended only in writing Guile internals,
not for high-level Scheme programs.
@end deffn

@deffn {Scheme Procedure} builtin-variable name
@deffnx {C Function} scm_builtin_variable (name)
Do not use this function.
@end deffn

@deffn {Scheme Procedure} variable-set-name-hint! var hint
@deffnx {C Function} scm_variable_set_name_hint (var, hint)
Do not use this function.
@end deffn

@deffn {Scheme Procedure} close-all-ports-except . ports
@deffnx {C Function} scm_close_all_ports_except (ports)
[DEPRECATED] Close all open file ports used by the interpreter
except for those supplied as arguments.  This procedure
was intended to be used before an exec call to close file descriptors
which are not needed in the new process.  However it has the
undesirable side effect of flushing buffers, so it's deprecated.
Use port-for-each instead.
@end deffn

@deffn {Scheme Procedure} c-clear-registered-modules
@deffnx {C Function} scm_clear_registered_modules ()
Destroy the list of modules registered with the current Guile process.
The return value is unspecified.  @strong{Warning:} this function does
not actually unlink or deallocate these modules, but only destroys the
records of which modules have been loaded.  It should therefore be used
only by module bookkeeping operations.
@end deffn

@deffn {Scheme Procedure} c-registered-modules
@deffnx {C Function} scm_registered_modules ()
Return a list of the object code modules that have been imported into
the current Guile process.  Each element of the list is a pair whose
car is the name of the module, and whose cdr is the function handle
for that module's initializer function.  The name is the string that
has been passed to scm_register_module_xxx.
@end deffn

@deffn {Scheme Procedure} module-import-interface module sym
@deffnx {C Function} scm_module_import_interface (module, sym)
Return the module or interface from which @var{sym} is imported in @var{module}.  If @var{sym} is not imported (i.e., it is not defined in @var{module} or it is a module-local binding instead of an imported one), then @code{#f} is returned.
@end deffn

@deffn {Scheme Procedure} self-evaluating? obj
@deffnx {C Function} scm_self_evaluating_p (obj)
Return #t for objects which Guile considers self-evaluating
@end deffn

@deffn {Scheme Procedure} unmemoize-expr m
@deffnx {C Function} scm_i_unmemoize_expr (m)
Unmemoize the memoized expression @var{m},
@end deffn

@deffn {Scheme Procedure} weak-key-alist-vector? obj
@deffnx {Scheme Procedure} weak-value-alist-vector? obj
@deffnx {Scheme Procedure} doubly-weak-alist-vector? obj
@deffnx {C Function} scm_weak_key_alist_vector_p (obj)
Return @code{#t} if @var{obj} is the specified weak hash
table. Note that a doubly weak hash table is neither a weak key
nor a weak value hash table.
@end deffn

@deffn {Scheme Procedure} make-weak-key-alist-vector [size]
@deffnx {Scheme Procedure} make-weak-value-alist-vector size
@deffnx {Scheme Procedure} make-doubly-weak-alist-vector size
@deffnx {C Function} scm_make_weak_key_alist_vector (size)
Return a weak hash table with @var{size} buckets. As with any
hash table, choosing a good size for the table requires some
caution.

You can modify weak hash tables in exactly the same way you
would modify regular hash tables. (@pxref{Hash Tables})
@end deffn

@deffn {Scheme Procedure} include-deprecated-features
Return @code{#t} iff deprecated features should be included
in public interfaces.
@end deffn

@deffn {Scheme Procedure} issue-deprecation-warning . msgs
Output @var{msgs} to @code{(current-error-port)} when this
is the first call to @code{issue-deprecation-warning} with
this specific @var{msg}.  Do nothing otherwise.
The argument @var{msgs} should be a list of strings;
they are printed in turn, each one followed by a newline.
@end deffn

@deffn {Scheme Procedure} valid-object-procedure? proc
@deffnx {C Function} scm_valid_object_procedure_p (proc)
Return @code{#t} iff @var{proc} is a procedure that can be used with @code{set-object-procedure}.  It is always valid to use a closure constructed by @code{lambda}.
@end deffn

@deffn {Scheme Procedure} %get-pre-modules-obarray
@deffnx {C Function} scm_get_pre_modules_obarray ()
Return the obarray that is used for all new bindings before the module system is booted.  The first call to @code{set-current-module} will boot the module system.
@end deffn

@deffn {Scheme Procedure} standard-interface-eval-closure module
@deffnx {C Function} scm_standard_interface_eval_closure (module)
Return a interface eval closure for the module @var{module}. Such a closure does not allow new bindings to be added.
@end deffn

@deffn {Scheme Procedure} env-module env
@deffnx {C Function} scm_env_module (env)
Return the module of @var{ENV}, a lexical environment.
@end deffn

@deffn {Scheme Procedure} single-active-thread?
implemented by the C function "scm_single_thread_p"
@end deffn

@deffn {Scheme Procedure} set-debug-cell-accesses! flag
@deffnx {C Function} scm_set_debug_cell_accesses_x (flag)
This function is used to turn on checking for a debug version of GUILE. This version does not support this functionality

@end deffn

@deffn {Scheme Procedure} standard-eval-closure module
@deffnx {C Function} scm_standard_eval_closure (module)
Return an eval closure for the module @var{module}.
@end deffn

@deffn {Scheme Procedure} mask-signals
@deffnx {C Function} scm_mask_signals ()
Mask signals. The returned value is not specified.
@end deffn

@deffn {Scheme Procedure} unmask-signals
@deffnx {C Function} scm_unmask_signals ()
Unmask signals. The returned value is not specified.
@end deffn

@deffn {Scheme Procedure} noop . args
@deffnx {C Function} scm_noop (args)
Do nothing.  When called without arguments, return @code{#f},
otherwise return the first argument.
@end deffn

@deffn {Scheme Procedure} system-async thunk
@deffnx {C Function} scm_system_async (thunk)
This function is deprecated.  You can use @var{thunk} directly
instead of explicitly creating an async object.

@end deffn

@deffn {Scheme Procedure} object-address obj
@deffnx {C Function} scm_object_address (obj)
Return an integer that for the lifetime of @var{obj} is uniquely
returned by this function for @var{obj}
@end deffn

@deffn {Scheme Procedure} environment? obj
@deffnx {C Function} scm_environment_p (obj)
Return @code{#t} if @var{obj} is an environment, or @code{#f}
otherwise.
@end deffn

@deffn {Scheme Procedure} environment-bound? env sym
@deffnx {C Function} scm_environment_bound_p (env, sym)
Return @code{#t} if @var{sym} is bound in @var{env}, or
@code{#f} otherwise.
@end deffn

@deffn {Scheme Procedure} environment-ref env sym
@deffnx {C Function} scm_environment_ref (env, sym)
Return the value of the location bound to @var{sym} in
@var{env}. If @var{sym} is unbound in @var{env}, signal an
@code{environment:unbound} error.
@end deffn

@deffn {Scheme Procedure} environment-fold env proc init
@deffnx {C Function} scm_environment_fold (env, proc, init)
Iterate over all the bindings in @var{env}, accumulating some
value.
For each binding in @var{env}, apply @var{proc} to the symbol
bound, its value, and the result from the previous application
of @var{proc}.
Use @var{init} as @var{proc}'s third argument the first time
@var{proc} is applied.
If @var{env} contains no bindings, this function simply returns
@var{init}.
If @var{env} binds the symbol sym1 to the value val1, sym2 to
val2, and so on, then this procedure computes:
@lisp
  (proc sym1 val1
        (proc sym2 val2
              ...
              (proc symn valn
                    init)))
@end lisp
Each binding in @var{env} will be processed exactly once.
@code{environment-fold} makes no guarantees about the order in
which the bindings are processed.
Here is a function which, given an environment, constructs an
association list representing that environment's bindings,
using environment-fold:
@lisp
  (define (environment->alist env)
    (environment-fold env
                      (lambda (sym val tail)
                        (cons (cons sym val) tail))
                      '()))
@end lisp
@end deffn

@deffn {Scheme Procedure} environment-define env sym val
@deffnx {C Function} scm_environment_define (env, sym, val)
Bind @var{sym} to a new location containing @var{val} in
@var{env}. If @var{sym} is already bound to another location
in @var{env} and the binding is mutable, that binding is
replaced.  The new binding and location are both mutable. The
return value is unspecified.
If @var{sym} is already bound in @var{env}, and the binding is
immutable, signal an @code{environment:immutable-binding} error.
@end deffn

@deffn {Scheme Procedure} environment-undefine env sym
@deffnx {C Function} scm_environment_undefine (env, sym)
Remove any binding for @var{sym} from @var{env}. If @var{sym}
is unbound in @var{env}, do nothing.  The return value is
unspecified.
If @var{sym} is already bound in @var{env}, and the binding is
immutable, signal an @code{environment:immutable-binding} error.
@end deffn

@deffn {Scheme Procedure} environment-set! env sym val
@deffnx {C Function} scm_environment_set_x (env, sym, val)
If @var{env} binds @var{sym} to some location, change that
location's value to @var{val}.  The return value is
unspecified.
If @var{sym} is not bound in @var{env}, signal an
@code{environment:unbound} error.  If @var{env} binds @var{sym}
to an immutable location, signal an
@code{environment:immutable-location} error.
@end deffn

@deffn {Scheme Procedure} environment-cell env sym for_write
@deffnx {C Function} scm_environment_cell (env, sym, for_write)
Return the value cell which @var{env} binds to @var{sym}, or
@code{#f} if the binding does not live in a value cell.
The argument @var{for-write} indicates whether the caller
intends to modify the variable's value by mutating the value
cell.  If the variable is immutable, then
@code{environment-cell} signals an
@code{environment:immutable-location} error.
If @var{sym} is unbound in @var{env}, signal an
@code{environment:unbound} error.
If you use this function, you should consider using
@code{environment-observe}, to be notified when @var{sym} gets
re-bound to a new value cell, or becomes undefined.
@end deffn

@deffn {Scheme Procedure} environment-observe env proc
@deffnx {C Function} scm_environment_observe (env, proc)
Whenever @var{env}'s bindings change, apply @var{proc} to
@var{env}.
This function returns an object, token, which you can pass to
@code{environment-unobserve} to remove @var{proc} from the set
of procedures observing @var{env}.  The type and value of
token is unspecified.
@end deffn

@deffn {Scheme Procedure} environment-observe-weak env proc
@deffnx {C Function} scm_environment_observe_weak (env, proc)
This function is the same as environment-observe, except that
the reference @var{env} retains to @var{proc} is a weak
reference. This means that, if there are no other live,
non-weak references to @var{proc}, it will be
garbage-collected, and dropped from @var{env}'s
list of observing procedures.
@end deffn

@deffn {Scheme Procedure} environment-unobserve token
@deffnx {C Function} scm_environment_unobserve (token)
Cancel the observation request which returned the value
@var{token}.  The return value is unspecified.
If a call @code{(environment-observe env proc)} returns
@var{token}, then the call @code{(environment-unobserve token)}
will cause @var{proc} to no longer be called when @var{env}'s
bindings change.
@end deffn

@deffn {Scheme Procedure} make-leaf-environment
@deffnx {C Function} scm_make_leaf_environment ()
Create a new leaf environment, containing no bindings.
All bindings and locations created in the new environment
will be mutable.
@end deffn

@deffn {Scheme Procedure} leaf-environment? object
@deffnx {C Function} scm_leaf_environment_p (object)
Return @code{#t} if object is a leaf environment, or @code{#f}
otherwise.
@end deffn

@deffn {Scheme Procedure} make-eval-environment local imported
@deffnx {C Function} scm_make_eval_environment (local, imported)
Return a new environment object eval whose bindings are the
union of the bindings in the environments @var{local} and
@var{imported}, with bindings from @var{local} taking
precedence. Definitions made in eval are placed in @var{local}.
Applying @code{environment-define} or
@code{environment-undefine} to eval has the same effect as
applying the procedure to @var{local}.
Note that eval incorporates @var{local} and @var{imported} by
reference:
If, after creating eval, the program changes the bindings of
@var{local} or @var{imported}, those changes will be visible
in eval.
Since most Scheme evaluation takes place in eval environments,
they transparently cache the bindings received from @var{local}
and @var{imported}. Thus, the first time the program looks up
a symbol in eval, eval may make calls to @var{local} or
@var{imported} to find their bindings, but subsequent
references to that symbol will be as fast as references to
bindings in finite environments.
In typical use, @var{local} will be a finite environment, and
@var{imported} will be an import environment
@end deffn

@deffn {Scheme Procedure} eval-environment? object
@deffnx {C Function} scm_eval_environment_p (object)
Return @code{#t} if object is an eval environment, or @code{#f}
otherwise.
@end deffn

@deffn {Scheme Procedure} eval-environment-local env
@deffnx {C Function} scm_eval_environment_local (env)
Return the local environment of eval environment @var{env}.
@end deffn

@deffn {Scheme Procedure} eval-environment-set-local! env local
@deffnx {C Function} scm_eval_environment_set_local_x (env, local)
Change @var{env}'s local environment to @var{local}.
@end deffn

@deffn {Scheme Procedure} eval-environment-imported env
@deffnx {C Function} scm_eval_environment_imported (env)
Return the imported environment of eval environment @var{env}.
@end deffn

@deffn {Scheme Procedure} eval-environment-set-imported! env imported
@deffnx {C Function} scm_eval_environment_set_imported_x (env, imported)
Change @var{env}'s imported environment to @var{imported}.
@end deffn

@deffn {Scheme Procedure} make-import-environment imports conflict_proc
@deffnx {C Function} scm_make_import_environment (imports, conflict_proc)
Return a new environment @var{imp} whose bindings are the union
of the bindings from the environments in @var{imports};
@var{imports} must be a list of environments. That is,
@var{imp} binds a symbol to a location when some element of
@var{imports} does.
If two different elements of @var{imports} have a binding for
the same symbol, the @var{conflict-proc} is called with the
following parameters:  the import environment, the symbol and
the list of the imported environments that bind the symbol.
If the @var{conflict-proc} returns an environment @var{env},
the conflict is considered as resolved and the binding from
@var{env} is used.  If the @var{conflict-proc} returns some
non-environment object, the conflict is considered unresolved
and the symbol is treated as unspecified in the import
environment.
The checking for conflicts may be performed lazily, i. e. at
the moment when a value or binding for a certain symbol is
requested instead of the moment when the environment is
created or the bindings of the imports change.
All bindings in @var{imp} are immutable. If you apply
@code{environment-define} or @code{environment-undefine} to
@var{imp}, Guile will signal an
 @code{environment:immutable-binding} error. However,
notice that the set of bindings in @var{imp} may still change,
if one of its imported environments changes.
@end deffn

@deffn {Scheme Procedure} import-environment? object
@deffnx {C Function} scm_import_environment_p (object)
Return @code{#t} if object is an import environment, or
@code{#f} otherwise.
@end deffn

@deffn {Scheme Procedure} import-environment-imports env
@deffnx {C Function} scm_import_environment_imports (env)
Return the list of environments imported by the import
environment @var{env}.
@end deffn

@deffn {Scheme Procedure} import-environment-set-imports! env imports
@deffnx {C Function} scm_import_environment_set_imports_x (env, imports)
Change @var{env}'s list of imported environments to
@var{imports}, and check for conflicts.
@end deffn

@deffn {Scheme Procedure} make-export-environment private signature
@deffnx {C Function} scm_make_export_environment (private, signature)
Return a new environment @var{exp} containing only those
bindings in private whose symbols are present in
@var{signature}. The @var{private} argument must be an
environment.

The environment @var{exp} binds symbol to location when
@var{env} does, and symbol is exported by @var{signature}.

@var{signature} is a list specifying which of the bindings in
@var{private} should be visible in @var{exp}. Each element of
@var{signature} should be a list of the form:
  (symbol attribute ...)
where each attribute is one of the following:
@table @asis
@item the symbol @code{mutable-location}
  @var{exp} should treat the
  location bound to symbol as mutable. That is, @var{exp}
  will pass calls to @code{environment-set!} or
  @code{environment-cell} directly through to private.
@item the symbol @code{immutable-location}
  @var{exp} should treat
  the location bound to symbol as immutable. If the program
  applies @code{environment-set!} to @var{exp} and symbol, or
  calls @code{environment-cell} to obtain a writable value
  cell, @code{environment-set!} will signal an
  @code{environment:immutable-location} error. Note that, even
  if an export environment treats a location as immutable, the
  underlying environment may treat it as mutable, so its
  value may change.
@end table
It is an error for an element of signature to specify both
@code{mutable-location} and @code{immutable-location}. If
neither is specified, @code{immutable-location} is assumed.

As a special case, if an element of signature is a lone
symbol @var{sym}, it is equivalent to an element of the form
@code{(sym)}.

All bindings in @var{exp} are immutable. If you apply
@code{environment-define} or @code{environment-undefine} to
@var{exp}, Guile will signal an
@code{environment:immutable-binding} error. However,
notice that the set of bindings in @var{exp} may still change,
if the bindings in private change.
@end deffn

@deffn {Scheme Procedure} export-environment? object
@deffnx {C Function} scm_export_environment_p (object)
Return @code{#t} if object is an export environment, or
@code{#f} otherwise.
@end deffn

@deffn {Scheme Procedure} export-environment-private env
@deffnx {C Function} scm_export_environment_private (env)
Return the private environment of export environment @var{env}.
@end deffn

@deffn {Scheme Procedure} export-environment-set-private! env private
@deffnx {C Function} scm_export_environment_set_private_x (env, private)
Change the private environment of export environment @var{env}.
@end deffn

@deffn {Scheme Procedure} export-environment-signature env
@deffnx {C Function} scm_export_environment_signature (env)
Return the signature of export environment @var{env}.
@end deffn

@deffn {Scheme Procedure} export-environment-set-signature! env signature
@deffnx {C Function} scm_export_environment_set_signature_x (env, signature)
Change the signature of export environment @var{env}.
@end deffn

@deffn {Scheme Procedure} %compute-slots class
@deffnx {C Function} scm_sys_compute_slots (class)
Return a list consisting of the names of all slots belonging to
class @var{class}, i. e. the slots of @var{class} and of all of
its superclasses.
@end deffn

@deffn {Scheme Procedure} get-keyword key l default_value
@deffnx {C Function} scm_get_keyword (key, l, default_value)
Determine an associated value for the keyword @var{key} from
the list @var{l}.  The list @var{l} has to consist of an even
number of elements, where, starting with the first, every
second element is a keyword, followed by its associated value.
If @var{l} does not hold a value for @var{key}, the value
@var{default_value} is returned.
@end deffn

@deffn {Scheme Procedure} slot-ref-using-class class obj slot_name
@deffnx {C Function} scm_slot_ref_using_class (class, obj, slot_name)

@end deffn

@deffn {Scheme Procedure} slot-set-using-class! class obj slot_name value
@deffnx {C Function} scm_slot_set_using_class_x (class, obj, slot_name, value)

@end deffn

@deffn {Scheme Procedure} class-of x
@deffnx {C Function} scm_class_of (x)
Return the class of @var{x}.
@end deffn

@deffn {Scheme Procedure} %goops-loaded
@deffnx {C Function} scm_sys_goops_loaded ()
Announce that GOOPS is loaded and perform initialization
on the C level which depends on the loaded GOOPS modules.
@end deffn

@deffn {Scheme Procedure} %method-more-specific? m1 m2 targs
@deffnx {C Function} scm_sys_method_more_specific_p (m1, m2, targs)
Return true if method @var{m1} is more specific than @var{m2} given the argument types (classes) listed in @var{targs}.
@end deffn

@deffn {Scheme Procedure} find-method . l
@deffnx {C Function} scm_find_method (l)

@end deffn

@deffn {Scheme Procedure} primitive-generic-generic subr
@deffnx {C Function} scm_primitive_generic_generic (subr)

@end deffn

@deffn {Scheme Procedure} enable-primitive-generic! . subrs
@deffnx {C Function} scm_enable_primitive_generic_x (subrs)

@end deffn

@deffn {Scheme Procedure} generic-capability? proc
@deffnx {C Function} scm_generic_capability_p (proc)

@end deffn

@deffn {Scheme Procedure} %invalidate-method-cache! gf
@deffnx {C Function} scm_sys_invalidate_method_cache_x (gf)

@end deffn

@deffn {Scheme Procedure} %invalidate-class class
@deffnx {C Function} scm_sys_invalidate_class (class)

@end deffn

@deffn {Scheme Procedure} %modify-class old new
@deffnx {C Function} scm_sys_modify_class (old, new)

@end deffn

@deffn {Scheme Procedure} %modify-instance old new
@deffnx {C Function} scm_sys_modify_instance (old, new)

@end deffn

@deffn {Scheme Procedure} %set-object-setter! obj setter
@deffnx {C Function} scm_sys_set_object_setter_x (obj, setter)

@end deffn

@deffn {Scheme Procedure} %allocate-instance class initargs
@deffnx {C Function} scm_sys_allocate_instance (class, initargs)
Create a new instance of class @var{class} and initialize it
from the arguments @var{initargs}.
@end deffn

@deffn {Scheme Procedure} slot-exists? obj slot_name
@deffnx {C Function} scm_slot_exists_p (obj, slot_name)
Return @code{#t} if @var{obj} has a slot named @var{slot_name}.
@end deffn

@deffn {Scheme Procedure} slot-bound? obj slot_name
@deffnx {C Function} scm_slot_bound_p (obj, slot_name)
Return @code{#t} if the slot named @var{slot_name} of @var{obj}
is bound.
@end deffn

@deffn {Scheme Procedure} slot-set! obj slot_name value
@deffnx {C Function} scm_slot_set_x (obj, slot_name, value)
Set the slot named @var{slot_name} of @var{obj} to @var{value}.
@end deffn

@deffn {Scheme Procedure} slot-exists-using-class? class obj slot_name
@deffnx {C Function} scm_slot_exists_using_class_p (class, obj, slot_name)

@end deffn

@deffn {Scheme Procedure} slot-bound-using-class? class obj slot_name
@deffnx {C Function} scm_slot_bound_using_class_p (class, obj, slot_name)

@end deffn

@deffn {Scheme Procedure} %fast-slot-set! obj index value
@deffnx {C Function} scm_sys_fast_slot_set_x (obj, index, value)
Set the slot with index @var{index} in @var{obj} to
@var{value}.
@end deffn

@deffn {Scheme Procedure} %fast-slot-ref obj index
@deffnx {C Function} scm_sys_fast_slot_ref (obj, index)
Return the slot value with index @var{index} from @var{obj}.
@end deffn

@deffn {Scheme Procedure} @@assert-bound-ref obj index
@deffnx {C Function} scm_at_assert_bound_ref (obj, index)
Like @code{assert-bound}, but use @var{index} for accessing
the value from @var{obj}.
@end deffn

@deffn {Scheme Procedure} assert-bound value obj
@deffnx {C Function} scm_assert_bound (value, obj)
Return @var{value} if it is bound, and invoke the
@var{slot-unbound} method of @var{obj} if it is not.
@end deffn

@deffn {Scheme Procedure} unbound? obj
@deffnx {C Function} scm_unbound_p (obj)
Return @code{#t} if @var{obj} is unbound.
@end deffn

@deffn {Scheme Procedure} make-unbound
@deffnx {C Function} scm_make_unbound ()
Return the unbound value.
@end deffn

@deffn {Scheme Procedure} accessor-method-slot-definition obj
@deffnx {C Function} scm_accessor_method_slot_definition (obj)
Return the slot definition of the accessor @var{obj}.
@end deffn

@deffn {Scheme Procedure} method-procedure obj
@deffnx {C Function} scm_method_procedure (obj)
Return the procedure of the method @var{obj}.
@end deffn

@deffn {Scheme Procedure} method-specializers obj
@deffnx {C Function} scm_method_specializers (obj)
Return specializers of the method @var{obj}.
@end deffn

@deffn {Scheme Procedure} method-generic-function obj
@deffnx {C Function} scm_method_generic_function (obj)
Return the generic function for the method @var{obj}.
@end deffn

@deffn {Scheme Procedure} generic-function-methods obj
@deffnx {C Function} scm_generic_function_methods (obj)
Return the methods of the generic function @var{obj}.
@end deffn

@deffn {Scheme Procedure} generic-function-name obj
@deffnx {C Function} scm_generic_function_name (obj)
Return the name of the generic function @var{obj}.
@end deffn

@deffn {Scheme Procedure} class-environment obj
@deffnx {C Function} scm_class_environment (obj)
Return the environment of the class @var{obj}.
@end deffn

@deffn {Scheme Procedure} class-slots obj
@deffnx {C Function} scm_class_slots (obj)
Return the slot list of the class @var{obj}.
@end deffn

@deffn {Scheme Procedure} class-precedence-list obj
@deffnx {C Function} scm_class_precedence_list (obj)
Return the class precedence list of the class @var{obj}.
@end deffn

@deffn {Scheme Procedure} class-direct-methods obj
@deffnx {C Function} scm_class_direct_methods (obj)
Return the direct methods of the class @var{obj}
@end deffn

@deffn {Scheme Procedure} class-direct-subclasses obj
@deffnx {C Function} scm_class_direct_subclasses (obj)
Return the direct subclasses of the class @var{obj}.
@end deffn

@deffn {Scheme Procedure} class-direct-slots obj
@deffnx {C Function} scm_class_direct_slots (obj)
Return the direct slots of the class @var{obj}.
@end deffn

@deffn {Scheme Procedure} class-direct-supers obj
@deffnx {C Function} scm_class_direct_supers (obj)
Return the direct superclasses of the class @var{obj}.
@end deffn

@deffn {Scheme Procedure} class-name obj
@deffnx {C Function} scm_class_name (obj)
Return the class name of @var{obj}.
@end deffn

@deffn {Scheme Procedure} instance? obj
@deffnx {C Function} scm_instance_p (obj)
Return @code{#t} if @var{obj} is an instance.
@end deffn

@deffn {Scheme Procedure} %inherit-magic! class dsupers
@deffnx {C Function} scm_sys_inherit_magic_x (class, dsupers)

@end deffn

@deffn {Scheme Procedure} %prep-layout! class
@deffnx {C Function} scm_sys_prep_layout_x (class)

@end deffn

@deffn {Scheme Procedure} %initialize-object obj initargs
@deffnx {C Function} scm_sys_initialize_object (obj, initargs)
Initialize the object @var{obj} with the given arguments
@var{initargs}.
@end deffn

@deffn {Scheme Procedure} make . args
@deffnx {C Function} scm_make (args)
Make a new object.  @var{args} must contain the class and
all necessary initialization information.
@end deffn

@deffn {Scheme Procedure} slot-ref obj slot_name
@deffnx {C Function} scm_slot_ref (obj, slot_name)
Return the value from @var{obj}'s slot with the name
@var{slot_name}.
@end deffn

@deffn {Scheme Procedure} %tag-body body
@deffnx {C Function} scm_sys_tag_body (body)
Internal GOOPS magic---don't use this function!
@end deffn

@deffn {Scheme Procedure} make-keyword-from-dash-symbol symbol
@deffnx {C Function} scm_make_keyword_from_dash_symbol (symbol)
Make a keyword object from a @var{symbol} that starts with a dash.
@end deffn

@deffn {Scheme Procedure} keyword-dash-symbol keyword
@deffnx {C Function} scm_keyword_dash_symbol (keyword)
Return the dash symbol for @var{keyword}.
This is the inverse of @code{make-keyword-from-dash-symbol}.
@end deffn

@deffn {Scheme Procedure} dimensions->uniform-array dims prot [fill]
@deffnx {Scheme Procedure} make-uniform-vector length prototype [fill]
@deffnx {C Function} scm_dimensions_to_uniform_array (dims, prot, fill)
Create and return a uniform array or vector of type
corresponding to @var{prototype} with dimensions @var{dims} or
length @var{length}.  If @var{fill} is supplied, it's used to
fill the array, otherwise @var{prototype} is used.
@end deffn

@deffn {Scheme Procedure} list->uniform-array ndim prot lst
@deffnx {C Function} scm_list_to_uniform_array (ndim, prot, lst)
Return a uniform array of the type indicated by prototype
@var{prot} with elements the same as those of @var{lst}.
Elements must be of the appropriate type, no coercions are
done.

The argument @var{ndim} determines the number of dimensions
of the array.  It is either an exact integer, giving the
number directly, or a list of exact integers, whose length
specifies the number of dimensions and each element is the
lower index bound of its dimension.
@end deffn

@deffn {Scheme Procedure} array-prototype ra
@deffnx {C Function} scm_array_prototype (ra)
Return an object that would produce an array of the same type
as @var{array}, if used as the @var{prototype} for
@code{make-uniform-array}.
@end deffn

@deffn {Scheme Procedure} call-with-dynamic-root thunk handler
@deffnx {C Function} scm_call_with_dynamic_root (thunk, handler)
Call @var{thunk} with a new dynamic state and withina continuation barrier.  The @var{handler} catches allotherwise uncaught throws and executes within the samedynamic context as @var{thunk}.
@end deffn

@deffn {Scheme Procedure} dynamic-root
@deffnx {C Function} scm_dynamic_root ()
Return an object representing the current dynamic root.

These objects are only useful for comparison using @code{eq?}.

@end deffn

@deffn {Scheme Procedure} uniform-vector? obj
@deffnx {C Function} scm_uniform_vector_p (obj)
Return @code{#t} if @var{obj} is a uniform vector.
@end deffn

@deffn {Scheme Procedure} uniform-vector-ref v idx
@deffnx {C Function} scm_uniform_vector_ref (v, idx)
Return the element at index @var{idx} of the
homogenous numeric vector @var{v}.
@end deffn

@deffn {Scheme Procedure} uniform-vector-set! v idx val
@deffnx {C Function} scm_uniform_vector_set_x (v, idx, val)
Set the element at index @var{idx} of the
homogenous numeric vector @var{v} to @var{val}.
@end deffn

@deffn {Scheme Procedure} uniform-vector->list uvec
@deffnx {C Function} scm_uniform_vector_to_list (uvec)
Convert the uniform numeric vector @var{uvec} to a list.
@end deffn

@deffn {Scheme Procedure} uniform-vector-length v
@deffnx {C Function} scm_uniform_vector_length (v)
Return the number of elements in the uniform vector @var{v}.
@end deffn

@deffn {Scheme Procedure} make-u8vector len [fill]
@deffnx {C Function} scm_make_u8vector (len, fill)
Return a newly allocated uniform numeric vector which can
hold @var{len} elements.  If @var{fill} is given, it is used to
initialize the elements, otherwise the contents of the vector
is unspecified.
@end deffn

@deffn {Scheme Procedure} u8vector . l
@deffnx {C Function} scm_u8vector (l)
Return a newly allocated uniform numeric vector containing
all argument values.
@end deffn

@deffn {Scheme Procedure} list->u8vector l
@deffnx {C Function} scm_list_to_u8vector (l)
Convert the list @var{l} to a numeric uniform vector.
@end deffn

@deffn {Scheme Procedure} any->u8vector obj
@deffnx {C Function} scm_any_to_u8vector (obj)
Convert @var{obj}, which can be a list, vector, or
uniform vector, to a numeric uniform vector of
type u8.
@end deffn

@deffn {Scheme Procedure} string-any-c-code char_pred s [start [end]]
@deffnx {C Function} scm_string_any (char_pred, s, start, end)
Check if the predicate @var{pred} is true for any character in
the string @var{s}.

Calls to @var{pred} are made from left to right across @var{s}.
When it returns true (ie.@: non-@code{#f}), that return value
is the return from @code{string-any}.

The SRFI-13 specification requires that the call to @var{pred}
on the last character of @var{s} (assuming that point is
reached) be a tail call, but currently in Guile this is not the
case.
@end deffn

@deffn {Scheme Procedure} string-every-c-code char_pred s [start [end]]
@deffnx {C Function} scm_string_every (char_pred, s, start, end)
Check if the predicate @var{pred} is true for every character
in the string @var{s}.

Calls to @var{pred} are made from left to right across @var{s}.
If the predicate is true for every character then the return
value from the last @var{pred} call is the return from
@code{string-every}.

If there are no characters in @var{s} (ie.@: @var{start} equals
@var{end}) then the return is @code{#t}.

The SRFI-13 specification requires that the call to @var{pred}
on the last character of @var{s} (assuming that point is
reached) be a tail call, but currently in Guile this is not the
case.
@end deffn

@deffn {Scheme Procedure} inf? x
@deffnx {C Function} scm_inf_p (x)
Return @code{#t} if @var{x} is either @samp{+inf.0}
or @samp{-inf.0}, @code{#f} otherwise.
@end deffn


code:
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
@c   Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.

@node Utility Functions
@section General Utility Functions

@c FIXME::martin: Review me!

This chapter contains information about procedures which are not cleanly
tied to a specific data type.  Because of their wide range of
applications, they are collected in a @dfn{utility} chapter.

@menu
* Equality::                    When are two values `the same'?
* Object Properties::           A modern interface to object properties.
* Sorting::                     Sort utility procedures.
* Copying::                     Copying deep structures.
* General Conversion::          Converting objects to strings.
* Hooks::                       User-customizable event lists.
@end menu

@node Equality
@subsection Equality
@cindex sameness
@cindex equality

There are three kinds of core equality predicates in Scheme, described
below.  The same kinds of comparisons arise in other functions, like
@code{memq} and friends (@pxref{List Searching}).

For all three tests, objects of different types are never equal.  So
for instance a list and a vector are not @code{equal?}, even if their
contents are the same.  Exact and inexact numbers are considered
different types too, and are hence not equal even if their values are
the same.

@code{eq?} tests just for the same object (essentially a pointer
comparison).  This is fast, and can be used when searching for a
particular object, or when working with symbols or keywords (which are
always unique objects).

@code{eqv?} extends @code{eq?} to look at the value of numbers and
characters.  It can for instance be used somewhat like @code{=}
(@pxref{Comparison}) but without an error if one operand isn't a
number.

@code{equal?} goes further, it looks (recursively) into the contents
of lists, vectors, etc.  This is good for instance on lists that have
been read or calculated in various places and are the same, just not
made up of the same pairs.  Such lists look the same (when printed),
and @code{equal?} will consider them the same.

@sp 1
@deffn {Scheme Procedure} eq? x y
@deffnx {C Function} scm_eq_p (x, y)
@rnindex eq?
Return @code{#t} if @var{x} and @var{y} are the same object, except
for numbers and characters.  For example,

@example
(define x (vector 1 2 3))
(define y (vector 1 2 3))

(eq? x x)  @result{} #t
(eq? x y)  @result{} #f
@end example

Numbers and characters are not equal to any other object, but the
problem is they're not necessarily @code{eq?} to themselves either.
This is even so when the number comes directly from a variable,

@example
(let ((n (+ 2 3)))
  (eq? n n))       @result{} *unspecified*
@end example

Generally @code{eqv?} below should be used when comparing numbers or
characters.  @code{=} (@pxref{Comparison}) or @code{char=?}
(@pxref{Characters}) can be used too.

It's worth noting that end-of-list @code{()}, @code{#t}, @code{#f}, a
symbol of a given name, and a keyword of a given name, are unique
objects.  There's just one of each, so for instance no matter how
@code{()} arises in a program, it's the same object and can be
compared with @code{eq?},

@example
(define x (cdr '(123)))
(define y (cdr '(456)))
(eq? x y) @result{} #t

(define x (string->symbol "foo"))
(eq? x 'foo) @result{} #t
@end example
@end deffn

@deftypefn {C Function} int scm_is_eq (SCM x, SCM y)
Return @code{1} when @var{x} and @var{y} are equal in the sense of
@code{eq?}, otherwise return @code{0}.

@findex ==
The @code{==} operator should not be used on @code{SCM} values, an
@code{SCM} is a C type which cannot necessarily be compared using
@code{==} (@pxref{The SCM Type}).
@end deftypefn

@sp 1
@deffn {Scheme Procedure} eqv? x y
@deffnx {C Function} scm_eqv_p (x, y)
@rnindex eqv?
Return @code{#t} if @var{x} and @var{y} are the same object, or for
characters and numbers the same value.

On objects except characters and numbers, @code{eqv?} is the same as
@code{eq?} above, it's true if @var{x} and @var{y} are the same
object.

If @var{x} and @var{y} are numbers or characters, @code{eqv?} compares
their type and value.  An exact number is not @code{eqv?} to an
inexact number (even if their value is the same).

@example
(eqv? 3 (+ 1 2)) @result{} #t
(eqv? 1 1.0)     @result{} #f
@end example
@end deffn

@sp 1
@deffn {Scheme Procedure} equal? x y
@deffnx {C Function} scm_equal_p (x, y)
@rnindex equal?
Return @code{#t} if @var{x} and @var{y} are the same type, and their
contents or value are equal.

For a pair, string, vector, array or structure, @code{equal?} compares the
contents, and does so using the same @code{equal?} recursively,
so a deep structure can be traversed.

@example
(equal? (list 1 2 3) (list 1 2 3))   @result{} #t
(equal? (list 1 2 3) (vector 1 2 3)) @result{} #f
@end example

For other objects, @code{equal?} compares as per @code{eqv?} above,
which means characters and numbers are compared by type and value (and
like @code{eqv?}, exact and inexact numbers are not @code{equal?},
even if their value is the same).

@example
(equal? 3 (+ 1 2)) @result{} #t
(equal? 1 1.0)     @result{} #f
@end example

Hash tables are currently only compared as per @code{eq?}, so two
different tables are not @code{equal?}, even if their contents are the
same.

@code{equal?} does not support circular data structures, it may go
into an infinite loop if asked to compare two circular lists or
similar.

New application-defined object types (@pxref{Defining New Types
(Smobs)}) have an @code{equalp} handler which is called by
@code{equal?}.  This lets an application traverse the contents or
control what is considered @code{equal?} for two objects of such a
type.  If there's no such handler, the default is to just compare as
per @code{eq?}.
@end deffn

@node Object Properties
@subsection Object Properties

It's often useful to associate a piece of additional information with a
Scheme object even though that object does not have a dedicated slot
available in which the additional information could be stored.  Object
properties allow you to do just that.

Guile's representation of an object property is a procedure-with-setter
(@pxref{Procedures with Setters}) that can be used with the generalized
form of @code{set!} (REFFIXME) to set and retrieve that property for any
Scheme object.  So, setting a property looks like this:

@lisp
(set! (my-property obj1) value-for-obj1)
(set! (my-property obj2) value-for-obj2)
@end lisp

@noindent
And retrieving values of the same property looks like this:

@lisp
(my-property obj1)
@result{}
value-for-obj1

(my-property obj2)
@result{}
value-for-obj2
@end lisp

To create an object property in the first place, use the
@code{make-object-property} procedure:

@lisp
(define my-property (make-object-property))
@end lisp

@deffn {Scheme Procedure} make-object-property
Create and return an object property.  An object property is a
procedure-with-setter that can be called in two ways.  @code{(set!
(@var{property} @var{obj}) @var{val})} sets @var{obj}'s @var{property}
to @var{val}.  @code{(@var{property} @var{obj})} returns the current
setting of @var{obj}'s @var{property}.
@end deffn

A single object property created by @code{make-object-property} can
associate distinct property values with all Scheme values that are
distinguishable by @code{eq?} (including, for example, integers).

Internally, object properties are implemented using a weak key hash
table.  This means that, as long as a Scheme value with property values
is protected from garbage collection, its property values are also
protected.  When the Scheme value is collected, its entry in the
property table is removed and so the (ex-) property values are no longer
protected by the table.

@menu
* Property Primitives::         Low level property implementation.
* Old-fashioned Properties::    An older approach to properties.
@end menu

@node Property Primitives
@subsubsection Low Level Property Implementation.

@deffn {Scheme Procedure} primitive-make-property not-found-proc
@deffnx {C Function} scm_primitive_make_property (not_found_proc)
Create a @dfn{property token} that can be used with
@code{primitive-property-ref} and @code{primitive-property-set!}.
See @code{primitive-property-ref} for the significance of
@var{not-found-proc}.
@end deffn

@deffn {Scheme Procedure} primitive-property-ref prop obj
@deffnx {C Function} scm_primitive_property_ref (prop, obj)
Return the property @var{prop} of @var{obj}.

When no value has yet been associated with @var{prop} and @var{obj},
the @var{not-found-proc} from @var{prop} is used.  A call
@code{(@var{not-found-proc} @var{prop} @var{obj})} is made and the
result set as the property value.  If @var{not-found-proc} is
@code{#f} then @code{#f} is the property value.
@end deffn

@deffn {Scheme Procedure} primitive-property-set! prop obj val
@deffnx {C Function} scm_primitive_property_set_x (prop, obj, val)
Set the property @var{prop} of @var{obj} to @var{val}.
@end deffn

@deffn {Scheme Procedure} primitive-property-del! prop obj
@deffnx {C Function} scm_primitive_property_del_x (prop, obj)
Remove any value associated with @var{prop} and @var{obj}.
@end deffn

@node Old-fashioned Properties
@subsubsection An Older Approach to Properties

Traditionally, Lisp systems provide a different object property
interface to that provided by @code{make-object-property}, in which the
object property that is being set or retrieved is indicated by a symbol.

Guile includes this older kind of interface as well, but it may well be
removed in a future release, as it is less powerful than
@code{make-object-property} and so increases the size of the Guile
library for no benefit.  (And it is trivial to write a compatibility
layer in Scheme.)

@deffn {Scheme Procedure} object-properties obj
@deffnx {C Function} scm_object_properties (obj)
Return @var{obj}'s property list.
@end deffn

@deffn {Scheme Procedure} set-object-properties! obj alist
@deffnx {C Function} scm_set_object_properties_x (obj, alist)
Set @var{obj}'s property list to @var{alist}.
@end deffn

@deffn {Scheme Procedure} object-property obj key
@deffnx {C Function} scm_object_property (obj, key)
Return the property of @var{obj} with name @var{key}.
@end deffn

@deffn {Scheme Procedure} set-object-property! obj key value
@deffnx {C Function} scm_set_object_property_x (obj, key, value)
In @var{obj}'s property list, set the property named @var{key}
to @var{value}.
@end deffn

@node Sorting
@subsection Sorting

@c FIXME::martin: Review me!

@cindex sorting
@cindex sorting lists
@cindex sorting vectors

Sorting is very important in computer programs.  Therefore, Guile comes
with several sorting procedures built-in.  As always, procedures with
names ending in @code{!} are side-effecting, that means that they may
modify their parameters in order to produce their results.

The first group of procedures can be used to merge two lists (which must
be already sorted on their own) and produce sorted lists containing
all elements of the input lists.

@deffn {Scheme Procedure} merge alist blist less
@deffnx {C Function} scm_merge (alist, blist, less)
Merge two already sorted lists into one.
Given two lists @var{alist} and @var{blist}, such that
@code{(sorted? alist less?)} and @code{(sorted? blist less?)},
return a new list in which the elements of @var{alist} and
@var{blist} have been stably interleaved so that
@code{(sorted? (merge alist blist less?) less?)}.
Note:  this does _not_ accept vectors.
@end deffn

@deffn {Scheme Procedure} merge! alist blist less
@deffnx {C Function} scm_merge_x (alist, blist, less)
Takes two lists @var{alist} and @var{blist} such that
@code{(sorted? alist less?)} and @code{(sorted? blist less?)} and
returns a new list in which the elements of @var{alist} and
@var{blist} have been stably interleaved so that
 @code{(sorted? (merge alist blist less?) less?)}.
This is the destructive variant of @code{merge}
Note:  this does _not_ accept vectors.
@end deffn

The following procedures can operate on sequences which are either
vectors or list.  According to the given arguments, they return sorted
vectors or lists, respectively.  The first of the following procedures
determines whether a sequence is already sorted, the other sort a given
sequence.  The variants with names starting with @code{stable-} are
special in that they maintain a special property of the input sequences:
If two or more elements are the same according to the comparison
predicate, they are left in the same order as they appeared in the
input.

@deffn {Scheme Procedure} sorted? items less
@deffnx {C Function} scm_sorted_p (items, less)
Return @code{#t} iff @var{items} is a list or a vector such that
for all 1 <= i <= m, the predicate @var{less} returns true when
applied to all elements i - 1 and i
@end deffn

@deffn {Scheme Procedure} sort items less
@deffnx {C Function} scm_sort (items, less)
Sort the sequence @var{items}, which may be a list or a
vector.  @var{less} is used for comparing the sequence
elements.  This is not a stable sort.
@end deffn

@deffn {Scheme Procedure} sort! items less
@deffnx {C Function} scm_sort_x (items, less)
Sort the sequence @var{items}, which may be a list or a
vector.  @var{less} is used for comparing the sequence
elements.  The sorting is destructive, that means that the
input sequence is modified to produce the sorted result.
This is not a stable sort.
@end deffn

@deffn {Scheme Procedure} stable-sort items less
@deffnx {C Function} scm_stable_sort (items, less)
Sort the sequence @var{items}, which may be a list or a
vector. @var{less} is used for comparing the sequence elements.
This is a stable sort.
@end deffn

@deffn {Scheme Procedure} stable-sort! items less
@deffnx {C Function} scm_stable_sort_x (items, less)
Sort the sequence @var{items}, which may be a list or a
vector. @var{less} is used for comparing the sequence elements.
The sorting is destructive, that means that the input sequence
is modified to produce the sorted result.
This is a stable sort.
@end deffn

The procedures in the last group only accept lists or vectors as input,
as their names indicate.

@deffn {Scheme Procedure} sort-list items less
@deffnx {C Function} scm_sort_list (items, less)
Sort the list @var{items}, using @var{less} for comparing the
list elements. This is a stable sort.
@end deffn

@deffn {Scheme Procedure} sort-list! items less
@deffnx {C Function} scm_sort_list_x (items, less)
Sort the list @var{items}, using @var{less} for comparing the
list elements. The sorting is destructive, that means that the
input list is modified to produce the sorted result.
This is a stable sort.
@end deffn

@deffn {Scheme Procedure} restricted-vector-sort! vec less startpos endpos
@deffnx {C Function} scm_restricted_vector_sort_x (vec, less, startpos, endpos)
Sort the vector @var{vec}, using @var{less} for comparing
the vector elements.  @var{startpos} (inclusively) and
@var{endpos} (exclusively) delimit
the range of the vector which gets sorted.  The return value
is not specified.
@end deffn

@node Copying
@subsection Copying Deep Structures

@c FIXME::martin: Review me!

The procedures for copying lists (@pxref{Lists}) only produce a flat
copy of the input list, and currently Guile does not even contain
procedures for copying vectors.  @code{copy-tree} can be used for these
application, as it does not only copy the spine of a list, but also
copies any pairs in the cars of the input lists.

@deffn {Scheme Procedure} copy-tree obj
@deffnx {C Function} scm_copy_tree (obj)
Recursively copy the data tree that is bound to @var{obj}, and return a
the new data structure.  @code{copy-tree} recurses down the
contents of both pairs and vectors (since both cons cells and vector
cells may point to arbitrary objects), and stops recursing when it hits
any other object.
@end deffn

@node General Conversion
@subsection General String Conversion

@c FIXME::martin: Review me!

When debugging Scheme programs, but also for providing a human-friendly
interface, a procedure for converting any Scheme object into string
format is very useful.  Conversion from/to strings can of course be done
with specialized procedures when the data type of the object to convert
is known, but with this procedure, it is often more comfortable.

@code{object->string} converts an object by using a print procedure for
writing to a string port, and then returning the resulting string.
Converting an object back from the string is only possible if the object
type has a read syntax and the read syntax is preserved by the printing
procedure.

@deffn {Scheme Procedure} object->string obj [printer]
@deffnx {C Function} scm_object_to_string (obj, printer)
Return a Scheme string obtained by printing @var{obj}.
Printing function can be specified by the optional second
argument @var{printer} (default: @code{write}).
@end deffn

@node Hooks
@subsection Hooks
@tpindex Hooks

A hook is a list of procedures to be called at well defined points in
time.  Typically, an application provides a hook @var{h} and promises
its users that it will call all of the procedures in @var{h} at a
defined point in the application's processing.  By adding its own
procedure to @var{h}, an application user can tap into or even influence
the progress of the application.

Guile itself provides several such hooks for debugging and customization
purposes: these are listed in a subsection below.

When an application first creates a hook, it needs to know how many
arguments will be passed to the hook's procedures when the hook is run.
The chosen number of arguments (which may be none) is declared when the
hook is created, and all the procedures that are added to that hook must
be capable of accepting that number of arguments.

A hook is created using @code{make-hook}.  A procedure can be added to
or removed from a hook using @code{add-hook!} or @code{remove-hook!},
and all of a hook's procedures can be removed together using
@code{reset-hook!}.  When an application wants to run a hook, it does so
using @code{run-hook}.

@menu
* Hook Example::                Hook usage by example.
* Hook Reference::              Reference of all hook procedures.
* C Hooks::                     Hooks for use from C code.
* GC Hooks::                    Garbage collection hooks.
* REPL Hooks::                  Hooks into the Guile REPL.
@end menu

@node Hook Example
@subsubsection Hook Usage by Example

Hook usage is shown by some examples in this section.  First, we will
define a hook of arity 2 --- that is, the procedures stored in the hook
will have to accept two arguments.

@lisp
(define hook (make-hook 2))
hook
@result{} #<hook 2 40286c90>
@end lisp

Now we are ready to add some procedures to the newly created hook with
@code{add-hook!}.  In the following example, two procedures are added,
which print different messages and do different things with their
arguments.

@lisp
(add-hook! hook (lambda (x y)
                    (display "Foo: ")
                    (display (+ x y))
                    (newline)))
(add-hook! hook (lambda (x y)
                    (display "Bar: ")
                    (display (* x y))
                    (newline)))
@end lisp

Once the procedures have been added, we can invoke the hook using
@code{run-hook}.

@lisp
(run-hook hook 3 4)
@print{} Bar: 12
@print{} Foo: 7
@end lisp

Note that the procedures are called in the reverse of the order with
which they were added.  This is because the default behaviour of
@code{add-hook!} is to add its procedure to the @emph{front} of the
hook's procedure list.  You can force @code{add-hook!} to add its
procedure to the @emph{end} of the list instead by providing a third
@code{#t} argument on the second call to @code{add-hook!}.

@lisp
(add-hook! hook (lambda (x y)
                    (display "Foo: ")
                    (display (+ x y))
                    (newline)))
(add-hook! hook (lambda (x y)
                    (display "Bar: ")
                    (display (* x y))
                    (newline))
                    #t)             ; @r{<- Change here!}

(run-hook hook 3 4)
@print{} Foo: 7
@print{} Bar: 12
@end lisp

@node Hook Reference
@subsubsection Hook Reference

When you create a hook with @code{make-hook}, you must specify the arity
of the procedures which can be added to the hook.  If the arity is not
given explicitly as an argument to @code{make-hook}, it defaults to
zero.  All procedures of a given hook must have the same arity, and when
the procedures are invoked using @code{run-hook}, the number of
arguments passed must match the arity specified at hook creation time.

The order in which procedures are added to a hook matters.  If the third
parameter to @code{add-hook!} is omitted or is equal to @code{#f}, the
procedure is added in front of the procedures which might already be on
that hook, otherwise the procedure is added at the end.  The procedures
are always called from the front to the end of the list when they are
invoked via @code{run-hook}.

The ordering of the list of procedures returned by @code{hook->list}
matches the order in which those procedures would be called if the hook
was run using @code{run-hook}.

Note that the C functions in the following entries are for handling
@dfn{Scheme-level} hooks in C.  There are also @dfn{C-level} hooks which
have their own interface (@pxref{C Hooks}).

@deffn {Scheme Procedure} make-hook [n_args]
@deffnx {C Function} scm_make_hook (n_args)
Create a hook for storing procedure of arity @var{n_args}.
@var{n_args} defaults to zero.  The returned value is a hook
object to be used with the other hook procedures.
@end deffn

@deffn {Scheme Procedure} hook? x
@deffnx {C Function} scm_hook_p (x)
Return @code{#t} if @var{x} is a hook, @code{#f} otherwise.
@end deffn

@deffn {Scheme Procedure} hook-empty? hook
@deffnx {C Function} scm_hook_empty_p (hook)
Return @code{#t} if @var{hook} is an empty hook, @code{#f}
otherwise.
@end deffn

@deffn {Scheme Procedure} add-hook! hook proc [append_p]
@deffnx {C Function} scm_add_hook_x (hook, proc, append_p)
Add the procedure @var{proc} to the hook @var{hook}. The
procedure is added to the end if @var{append_p} is true,
otherwise it is added to the front.  The return value of this
procedure is not specified.
@end deffn

@deffn {Scheme Procedure} remove-hook! hook proc
@deffnx {C Function} scm_remove_hook_x (hook, proc)
Remove the procedure @var{proc} from the hook @var{hook}.  The
return value of this procedure is not specified.
@end deffn

@deffn {Scheme Procedure} reset-hook! hook
@deffnx {C Function} scm_reset_hook_x (hook)
Remove all procedures from the hook @var{hook}.  The return
value of this procedure is not specified.
@end deffn

@deffn {Scheme Procedure} hook->list hook
@deffnx {C Function} scm_hook_to_list (hook)
Convert the procedure list of @var{hook} to a list.
@end deffn

@deffn {Scheme Procedure} run-hook hook . args
@deffnx {C Function} scm_run_hook (hook, args)
Apply all procedures from the hook @var{hook} to the arguments
@var{args}.  The order of the procedure application is first to
last.  The return value of this procedure is not specified.
@end deffn

If, in C code, you are certain that you have a hook object and well
formed argument list for that hook, you can also use
@code{scm_c_run_hook}, which is identical to @code{scm_run_hook} but
does no type checking.

@deftypefn {C Function} void scm_c_run_hook (SCM hook, SCM args)
The same as @code{scm_run_hook} but without any type checking to confirm
that @var{hook} is actually a hook object and that @var{args} is a
well-formed list matching the arity of the hook.
@end deftypefn

For C code, @code{SCM_HOOKP} is a faster alternative to
@code{scm_hook_p}:

@deftypefn {C Macro} int SCM_HOOKP (x)
Return 1 if @var{x} is a Scheme-level hook, 0 otherwise.
@end deftypefn

@subsubsection Handling Scheme-level hooks from C code

Here is an example of how to handle Scheme-level hooks from C code using
the above functions.

@example
if (scm_is_true (scm_hook_p (obj)))
  /* handle Scheme-level hook using C functions */
  scm_reset_hook_x (obj);
else
  /* do something else (obj is not a hook) */
@end example

@node C Hooks
@subsubsection Hooks For C Code.

The hooks already described are intended to be populated by Scheme-level
procedures.  In addition to this, the Guile library provides an
independent set of interfaces for the creation and manipulation of hooks
that are designed to be populated by functions implemented in C.

The original motivation here was to provide a kind of hook that could
safely be invoked at various points during garbage collection.
Scheme-level hooks are unsuitable for this purpose as running them could
itself require memory allocation, which would then invoke garbage
collection recursively @dots{}  However, it is also the case that these
hooks are easier to work with than the Scheme-level ones if you only
want to register C functions with them.  So if that is mainly what your
code needs to do, you may prefer to use this interface.

To create a C hook, you should allocate storage for a structure of type
@code{scm_t_c_hook} and then initialize it using @code{scm_c_hook_init}.

@deftp {C Type} scm_t_c_hook
Data type for a C hook.  The internals of this type should be treated as
opaque.
@end deftp

@deftp {C Enum} scm_t_c_hook_type
Enumeration of possible hook types, which are:

@table @code
@item SCM_C_HOOK_NORMAL
@vindex SCM_C_HOOK_NORMAL
Type of hook for which all the registered functions will always be called.
@item SCM_C_HOOK_OR
@vindex SCM_C_HOOK_OR
Type of hook for which the sequence of registered functions will be
called only until one of them returns C true (a non-NULL pointer).
@item SCM_C_HOOK_AND
@vindex SCM_C_HOOK_AND
Type of hook for which the sequence of registered functions will be
called only until one of them returns C false (a NULL pointer).
@end table
@end deftp

@deftypefn {C Function} void scm_c_hook_init (scm_t_c_hook *hook, void *hook_data, scm_t_c_hook_type type)
Initialize the C hook at memory pointed to by @var{hook}.  @var{type}
should be one of the values of the @code{scm_t_c_hook_type} enumeration,
and controls how the hook functions will be called.  @var{hook_data} is
a closure parameter that will be passed to all registered hook functions
when they are called.
@end deftypefn

To add or remove a C function from a C hook, use @code{scm_c_hook_add}
or @code{scm_c_hook_remove}.  A hook function must expect three
@code{void *} parameters which are, respectively:

@table @var
@item hook_data
The hook closure data that was specified at the time the hook was
initialized by @code{scm_c_hook_init}.

@item func_data
The function closure data that was specified at the time that that
function was registered with the hook by @code{scm_c_hook_add}.

@item data
The call closure data specified by the @code{scm_c_hook_run} call that
runs the hook.
@end table

@deftp {C Type} scm_t_c_hook_function
Function type for a C hook function: takes three @code{void *}
parameters and returns a @code{void *} result.
@end deftp

@deftypefn {C Function} void scm_c_hook_add (scm_t_c_hook *hook, scm_t_c_hook_function func, void *func_data, int appendp)
Add function @var{func}, with function closure data @var{func_data}, to
the C hook @var{hook}.  The new function is appended to the hook's list
of functions if @var{appendp} is non-zero, otherwise prepended.
@end deftypefn

@deftypefn {C Function} void scm_c_hook_remove (scm_t_c_hook *hook, scm_t_c_hook_function func, void *func_data)
Remove function @var{func}, with function closure data @var{func_data},
from the C hook @var{hook}.  @code{scm_c_hook_remove} checks both
@var{func} and @var{func_data} so as to allow for the same @var{func}
being registered multiple times with different closure data.
@end deftypefn

Finally, to invoke a C hook, call the @code{scm_c_hook_run} function
specifying the hook and the call closure data for this run:

@deftypefn {C Function} {void *} scm_c_hook_run (scm_t_c_hook *hook, void *data)
Run the C hook @var{hook} will call closure data @var{data}.  Subject to
the variations for hook types @code{SCM_C_HOOK_OR} and
@code{SCM_C_HOOK_AND}, @code{scm_c_hook_run} calls @var{hook}'s
registered functions in turn, passing them the hook's closure data, each
function's closure data, and the call closure data.

@code{scm_c_hook_run}'s return value is the return value of the last
function to be called.
@end deftypefn

@node GC Hooks
@subsubsection Hooks for Garbage Collection

Whenever Guile performs a garbage collection, it calls the following
hooks in the order shown.

@defvr {C Hook} scm_before_gc_c_hook
C hook called at the very start of a garbage collection, after setting
@code{scm_gc_running_p} to 1, but before entering the GC critical
section.

If garbage collection is blocked because @code{scm_block_gc} is
non-zero, GC exits early soon after calling this hook, and no further
hooks will be called.
@end defvr

@defvr {C Hook} scm_before_mark_c_hook
C hook called before beginning the mark phase of garbage collection,
after the GC thread has entered a critical section.
@end defvr

@defvr {C Hook} scm_before_sweep_c_hook
C hook called before beginning the sweep phase of garbage collection.
This is the same as at the end of the mark phase, since nothing else
happens between marking and sweeping.
@end defvr

@defvr {C Hook} scm_after_sweep_c_hook
C hook called after the end of the sweep phase of garbage collection,
but while the GC thread is still inside its critical section.
@end defvr

@defvr {C Hook} scm_after_gc_c_hook
C hook called at the very end of a garbage collection, after the GC
thread has left its critical section.
@end defvr

@defvr {Scheme Hook} after-gc-hook
@vindex scm_after_gc_hook
Scheme hook with arity 0.  This hook is run asynchronously
(@pxref{Asyncs}) soon after the GC has completed and any other events
that were deferred during garbage collection have been processed.  (Also
accessible from C with the name @code{scm_after_gc_hook}.)
@end defvr

All the C hooks listed here have type @code{SCM_C_HOOK_NORMAL}, are
initialized with hook closure data NULL, are invoked by
@code{scm_c_hook_run} with call closure data NULL.

@cindex guardians, testing for GC'd objects
The Scheme hook @code{after-gc-hook} is particularly useful in
conjunction with guardians (@pxref{Guardians}).  Typically, if you are
using a guardian, you want to call the guardian after garbage collection
to see if any of the objects added to the guardian have been collected.
By adding a thunk that performs this call to @code{after-gc-hook}, you
can ensure that your guardian is tested after every garbage collection
cycle.

@node REPL Hooks
@subsubsection Hooks into the Guile REPL

@c Local Variables:
@c TeX-master: "guile.texi"
@c End:


code:
Scheme objects
==============

There are two basic C data types to represent objects in guile:

- SCM:  SCM is the user level abstract C type that is used to represent all of
guile's scheme objects, no matter what the scheme object type is.  No C
operation except assignment is guaranteed to work with variables of type SCM.
Only use macros and functions to work with SCM values.  Values are converted
between C data types and the SCM type with utility functions and macros.

- scm_bits_t:  An integral data type that is guaranteed to be large enough to
hold all information that is required to represent any scheme object.  While
this data type is used to implement guile internals, the use of this type is
also necessary to write certain kinds of extensions to guile.

Relationship between SCM and scm_bits_t
=======================================

A variable of type SCM is guaranteed to hold a valid scheme object.  A
variable of type scm_bits_t, however, may either hold a representation of a
SCM value as a C integral type, but may also hold any C value, even if it does
not correspond to a valid scheme object.

For a variable x of type SCM, the scheme object's type information is stored
in a form that is not directly usable.  To be able to work on the type
encoding of the scheme value, the SCM variable has to be transformed into the
corresponding representation as a scm_bits_t variable y by using the
SCM_UNPACK macro.  After this has been done, the type of the scheme object x
can be derived from the content of the bits of the scm_bits_t value y, as is
described in -->data-rep.  A valid bit encoding of a scheme value as a
scm_bits_t variable can be transformed into the corresponding SCM value by
using the SCM_PACK macro.

- scm_bits_t SCM_UNPACK (SCM x):  Transforms the SCM value x into it's
representation as an integral type.  Only after applying SCM_UNPACK it is
possible to access the bits and contents of the SCM value.

- SCM SCM_PACK (scm_bits_t x):  Takes a valid integral representation of a
scheme object and transforms it into its representation as a SCM value.

Immediate objects
=================

A scheme object may either be an immediate, i. e. carrying all necessary
information by itself, or it may contain a reference to a 'cell' with
additional information on the heap.  While the fact, whether an object is an
immediate or not should be irrelevant for user code, within guile's own code
the distinction is sometimes of importance.  Thus, the following low level
macro is provided:

- int SCM_IMP (SCM x):  A scheme object is an immediate if it fullfills the
SCM_IMP predicate, otherwise it holds an encoded reference to a heap cell.
The result of the predicate is delivered as a C style boolean value.  User
code and code that extends guile should normally not be required to use this
macro.

Summary:
* For a scheme object x of unknown type, check first with SCM_IMP (x) if it is
an immediate object.  If so, all of the type and value information can be
determined from the scm_bits_t value that is delivered by SCM_UNPACK (x).

Non immediate objects
=====================

- (scm_t_cell *) SCM2PTR (SCM x)         (FIXME:: this name should be changed)
- SCM PTR2SCM (scm_t_cell * x)           (FIXME:: this name should be changed)

A scheme object of type SCM that does not fullfill the SCM_IMP predicate holds
an encoded reference to a heap cell.  This reference can be decoded to a C
pointer to a heap cell using the SCM2PTR macro.  The encoding of a pointer to
a heap cell into a SCM value is done using the PTR2SCM macro.

Note that it is also possible to transform a non immediate SCM value by using
SCM_UNPACK into a scm_bits_t variable.  Hower, the result of SCM_UNPACK may
not be used as a pointer to a scm_t_cell:  Only SCM2PTR is guaranteed to
transform a SCM object into a valid pointer to a heap cell.  Also, it is not
allowed to apply PTR2SCM to anything that is not a valid pointer to a heap
cell.

Summary:
* Only use SCM2PTR for SCM values for which SCM_IMP is false!
* Don't use '(scm_t_cell*) SCM_UNPACK (x)'!  Use 'SCM2PTR (x)' instead!
* Don't use PTR2SCM for anything but a cell pointer!

Heap Cell Type Information
==========================

Heap cells contain a number of entries, each of which is either a scheme
object of type SCM or a raw C value of type scm_bits_t.  Which of the cell
entries contain scheme objects and which contain raw C values is determined by
the first entry of the cell, which holds the cell type information.

- scm_bits_t SCM_CELL_TYPE (SCM x):  For a non immediate scheme object x,
deliver the content of the first entry of the heap cell referenced by x.  This
value holds the information about the cell type as described in -->data-rep.

- void SCM_SET_CELL_TYPE (SCM x, scm_bits_t t):  For a non immediate scheme
object x, write the value t into the first entry of the heap cell referenced
by x.  The value t must hold a valid cell type as described in -->data-rep.

Accessing Cell Entries
======================

For a non immediate scheme object x, the object type can be determined by
reading the cell type entry using the SCM_CELL_TYPE macro.  For the different
types of cells it is known which cell entry holds scheme objects and which cell
entry holds raw C data.  To access the different cell entries appropriately,
the following macros are provided:

- scm_bits_t SCM_CELL_WORD (SCM x, unsigned int n):  Deliver the cell entry n
of the heap cell referenced by the non immediate scheme object x as raw data.
It is illegal, to access cell entries that hold scheme objects by using these
macros.  For convenience, the following macros are also provided:
  SCM_CELL_WORD_0 (x)  -->  SCM_CELL_WORD (x, 0)
  SCM_CELL_WORD_1 (x)  -->  SCM_CELL_WORD (x, 1)
  ...
  SCM_CELL_WORD_n (x)  -->  SCM_CELL_WORD (x, n)

- SCM SCM_CELL_OBJECT (SCM x, unsigned int n):  Deliver the cell entry n of
the heap cell referenced by the non immediate scheme object x as a scheme
object.  It is illegal, to access cell entries that do not hold scheme objects
by using these macros.  For convenience, the following macros are also
provided:
  SCM_CELL_OBJECT_0 (x)  -->  SCM_CELL_OBJECT (x, 0)
  SCM_CELL_OBJECT_1 (x)  -->  SCM_CELL_OBJECT (x, 1)
  ...
  SCM_CELL_OBJECT_n (x)  -->  SCM_CELL_OBJECT (x, n)

- void SCM_SET_CELL_WORD (SCM x, unsigned int n, scm_bits_t w):  Write the raw
C value w into entry number n of the heap cell referenced by the non immediate
scheme value x.  Values that are written into cells this way may only be read
from the cells using the SCM_CELL_WORD macros or, in case cell entry 0 is
written, using the SCM_CELL_TYPE macro.  For the special case of cell entry 0
it has to be made sure that w contains a cell type information (see
-->data-rep) which does not describe a scheme object.  For convenience, the
following macros are also provided:
  SCM_SET_CELL_WORD_0 (x, w)  -->  SCM_SET_CELL_WORD (x, 0, w)
  SCM_SET_CELL_WORD_1 (x, w)  -->  SCM_SET_CELL_WORD (x, 1, w)
  ...
  SCM_SET_CELL_WORD_n (x, w)  -->  SCM_SET_CELL_WORD (x, n, w)

- void SCM_SET_CELL_OBJECT (SCM x, unsigned int n, SCM o):  Write the scheme
object o into entry number n of the heap cell referenced by the non immediate
scheme value x.  Values that are written into cells this way may only be read
from the cells using the SCM_CELL_OBJECT macros or, in case cell entry 0 is
written, using the SCM_CELL_TYPE macro.  For the special case of cell entry 0
the writing of a scheme object into this cell is only allowed, if the cell
forms a scheme pair.  For convenience, the following macros are also provided:
  SCM_SET_CELL_OBJECT_0 (x, o)  -->  SCM_SET_CELL_OBJECT (x, 0, o)
  SCM_SET_CELL_OBJECT_1 (x, o)  -->  SCM_SET_CELL_OBJECT (x, 1, o)
  ...
  SCM_SET_CELL_OBJECT_n (x, o)  -->  SCM_SET_CELL_OBJECT (x, n, o)

Summary:
* For a non immediate scheme object x of unknown type, get the type
  information by using SCM_CELL_TYPE (x).
* As soon as the cell type information is available, only use the appropriate
  access methods to read and write data to the different cell entries.

Basic Rules for Accessing Cell Entries
======================================

For each cell type it is generally up to the implementation of that type which
of the corresponding cell entries hold scheme objects and which hold raw C
values.  However, there is one basic rules that has to be followed:  Scheme
pairs consist of exactly two cell entries, which both contain scheme objects.
Further, a cell which contains a scheme object in it first entry has to be a
scheme pair.  In other words, it is not allowed to store a scheme object in
the first cell entry and a non scheme object in the second cell entry.

Fixme:shouldn't this rather be SCM_PAIRP / SCM_PAIR_P ?
- int SCM_CONSP (SCM x):  Determine, whether the scheme object x is a scheme
pair, i. e. whether x references a heap cell consisting of exactly two
entries, where both entries contain a scheme object.  In this case, both
entries will have to be accessed using the SCM_CELL_OBJECT macros.  On the
contrary, if the SCM_CONSP predicate is not fulfilled, the first entry of the
scheme cell is guaranteed not to be a scheme value and thus the first cell
entry must be accessed using the SCM_CELL_WORD_0 macro.