@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2013, 2014
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
-@page
@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.
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}.
+@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
@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
+
+Smob free functions must be thread-safe. @xref{Garbage Collecting
+Smobs}, for a discussion on finalizers and concurrency. If you are
+embedding Guile in an application that is not thread-safe, and you
+define smob types that need finalization, you might want to disable
+automatic finalization, and arrange to call
+@code{scm_manually_run_finalizers ()} yourself.
+
+@deftypefn {C Function} int scm_set_automatic_finalization_enabled (int enabled_p)
+Enable or disable automatic finalization. By default, Guile arranges to
+invoke object finalizers automatically, in a separate thread if
+possible. Passing a zero value for @var{enabled_p} will disable
+automatic finalization for Guile as a whole. If you disable automatic
+finalization, you will have to call @code{scm_run_finalizers ()}
+periodically.
+
+Unlike most other Guile functions, you can call
+@code{scm_set_automatic_finalization_enabled} before Guile has been
+initialized.
+
+Return the previous status of automatic finalization.
+@end deftypefn
+
+@deftypefn {C Function} int scm_run_finalizers (void)
+Invoke any pending finalizers. Returns the number of finalizers that
+were invoked. This function should be called when automatic
+finalization is disabled, though it may be called if it is enabled as
+well.
+@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.
-@end deftypefn
-@deftypefn {C Function} void scm_set_smob_free (scm_t_bits tc, size_t (*free) (SCM obj))
-This function sets the smob freeing 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{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.
-
-The @var{free} procedure must return 0.
+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
and @code{scm_puts}.
@end deftypefn
-@deftypefn {C Function} void scm_set_smob_equalp (scm_t_bits tc, SCM (*equalp) (SCM obj1, SCM obj1))
+@deftypefn {C Function} void scm_set_smob_equalp (scm_t_bits tc, SCM (*equalp) (SCM obj1, SCM obj2))
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
+@code{SCM_BOOL_F}. Both @var{obj1} and @var{obj2} are instances of the
smob type @var{tc}.
@end deftypefn
@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.
+Return true if @var{exp} is a smob instance of the type indicated by
+@var{tag}, or false otherwise. 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.
+@deftypefn {C Function} SCM scm_new_smob (scm_t_bits tag, void *data)
+@deftypefnx {C Function} SCM scm_new_double_smob (scm_t_bits tag, void *data, void *data2, void *data3)
+Make a new smob 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
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.
HCoop / bpt / guile.git / blobdiff