@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009
+@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.
+A @dfn{smob} is a ``small object''. Before foreign objects were
+introduced in Guile 2.0.12 (@pxref{Foreign Objects}), smobs were the
+preferred way to for C code to define new kinds of Scheme objects. With
+the exception of the so-called ``applicable SMOBs'' discussed below,
+smobs are now a legacy interface and are headed for eventual
+deprecation. @xref{Deprecation}. New code should use the foreign
+object interface.
+
+This section contains reference information related to defining and
+working with smobs. For a tutorial-like introduction to smobs, see
+``Defining New Types (Smobs)'' in previous versions of this manual.
@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
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
-@ref{Defining New Types (Smobs)}. If you want to customize any of
-these functions, the call to @code{scm_make_smob_type} should be
+@emph{print}, and @emph{equalp} functions. 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}.
@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
+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.
longer needed (@pxref{Memory Blocks, @code{scm_gc_malloc}}).
@end deftypefn
-@cindex precise marking
+Smob free functions must be thread-safe. @xref{Foreign Object Memory
+Management}, 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. @xref{Foreign Objects}.
@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 should rarely be necessary because all the
-process' memory (with the exception of @code{scm_gc_malloc_pointerless}
-or read-only regions) is scanned for live pointers@footnote{Conversely,
-in Guile up to the 1.8 series, the marking procedure was 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}.}.
+Defining a marking procedure is almost always the wrong thing to do. It
+is much, much preferable to allocate smob data with the
+@code{scm_gc_malloc} and @code{scm_gc_malloc_pointerless} functions, and
+allow the GC to trace pointers automatically.
+
+Any mark procedures you see currently almost surely date from the time
+of Guile 1.8, before the switch to the Boehm-Demers-Weiser collector.
+Such smob implementations should be changed to just use
+@code{scm_gc_malloc} and friends, and to lose their mark function.
+
+If you decide to keep the mark function, note that it may be called on
+objects that are on the free list. Please read and digest the comments
+from the BDW GC's @code{gc/gc_mark.h} header.
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
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