doc/ref/api-smobs.texi

   1 @c -*-texinfo-*-
   2 @c This is part of the GNU Guile Reference Manual.
   3 @c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2013, 2014
   4 @c   Free Software Foundation, Inc.
   5 @c See the file guile.texi for copying conditions.
   6
   7 @node Smobs
   8 @section Smobs
   9
  10 @cindex smob
  11
  12 A @dfn{smob} is a ``small object''.  Before foreign objects were
  13 introduced in Guile 2.0.12 (@pxref{Foreign Objects}), smobs were the
  14 preferred way to for C code to define new kinds of Scheme objects.  With
  15 the exception of the so-called ``applicable SMOBs'' discussed below,
  16 smobs are now a legacy interface and are headed for eventual
  17 deprecation.  @xref{Deprecation}.  New code should use the foreign
  18 object interface.
  19
  20 This section contains reference information related to defining and
  21 working with smobs.  For a tutorial-like introduction to smobs, see
  22 ``Defining New Types (Smobs)'' in previous versions of this manual.
  23
  24 @deftypefun scm_t_bits scm_make_smob_type (const char *name, size_t size)
  25 This function adds a new smob type, named @var{name}, with instance size
  26 @var{size}, to the system.  The return value is a tag that is used in
  27 creating instances of the type.
  28
  29 If @var{size} is 0, the default @emph{free} function will do nothing.
  30
  31 If @var{size} is not 0, the default @emph{free} function will
  32 deallocate the memory block pointed to by @code{SCM_SMOB_DATA} with
  33 @code{scm_gc_free}.  The @var{what} parameter in the call to
  34 @code{scm_gc_free} will be @var{name}.
  35
  36 Default values are provided for the @emph{mark}, @emph{free},
  37 @emph{print}, and @emph{equalp} functions.  If you want to customize any
  38 of these functions, the call to @code{scm_make_smob_type} should be
  39 immediately followed by calls to one or several of
  40 @code{scm_set_smob_mark}, @code{scm_set_smob_free},
  41 @code{scm_set_smob_print}, and/or @code{scm_set_smob_equalp}.
  42 @end deftypefun
  43
  44 @cindex finalizer
  45 @cindex finalization
  46
  47 @deftypefn {C Function} void scm_set_smob_free (scm_t_bits tc, size_t (*free) (SCM obj))
  48 This function sets the smob freeing procedure (sometimes referred to as
  49 a @dfn{finalizer}) for the smob type specified by the tag
  50 @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
  51
  52 The @var{free} procedure must deallocate all resources that are
  53 directly associated with the smob instance @var{obj}.  It must assume
  54 that all @code{SCM} values that it references have already been freed
  55 and are thus invalid.
  56
  57 It must also not call any libguile function or macro except
  58 @code{scm_gc_free}, @code{SCM_SMOB_FLAGS}, @code{SCM_SMOB_DATA},
  59 @code{SCM_SMOB_DATA_2}, and @code{SCM_SMOB_DATA_3}.
  60
  61 The @var{free} procedure must return 0.
  62
  63 Note that defining a freeing procedure is not necessary if the resources
  64 associated with @var{obj} consists only of memory allocated with
  65 @code{scm_gc_malloc} or @code{scm_gc_malloc_pointerless} because this
  66 memory is automatically reclaimed by the garbage collector when it is no
  67 longer needed (@pxref{Memory Blocks, @code{scm_gc_malloc}}).
  68 @end deftypefn
  69
  70 Smob free functions must be thread-safe.  @xref{Foreign Object Memory
  71 Management}, for a discussion on finalizers and concurrency.  If you are
  72 embedding Guile in an application that is not thread-safe, and you
  73 define smob types that need finalization, you might want to disable
  74 automatic finalization, and arrange to call
  75 @code{scm_manually_run_finalizers ()} yourself.  @xref{Foreign Objects}.
  76
  77 @deftypefn {C Function} void scm_set_smob_mark (scm_t_bits tc, SCM (*mark) (SCM obj))
  78 This function sets the smob marking procedure for the smob type specified by
  79 the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
  80
  81 Defining a marking procedure is almost always the wrong thing to do.  It
  82 is much, much preferable to allocate smob data with the
  83 @code{scm_gc_malloc} and @code{scm_gc_malloc_pointerless} functions, and
  84 allow the GC to trace pointers automatically.
  85
  86 Any mark procedures you see currently almost surely date from the time
  87 of Guile 1.8, before the switch to the Boehm-Demers-Weiser collector.
  88 Such smob implementations should be changed to just use
  89 @code{scm_gc_malloc} and friends, and to lose their mark function.
  90
  91 If you decide to keep the mark function, note that it may be called on
  92 objects that are on the free list.  Please read and digest the comments
  93 from the BDW GC's @code{gc/gc_mark.h} header.
  94
  95 The @var{mark} procedure must cause @code{scm_gc_mark} to be called
  96 for every @code{SCM} value that is directly referenced by the smob
  97 instance @var{obj}.  One of these @code{SCM} values can be returned
  98 from the procedure and Guile will call @code{scm_gc_mark} for it.
  99 This can be used to avoid deep recursions for smob instances that form
 100 a list.
 101
 102 It must not call any libguile function or macro except
 103 @code{scm_gc_mark}, @code{SCM_SMOB_FLAGS}, @code{SCM_SMOB_DATA},
 104 @code{SCM_SMOB_DATA_2}, and @code{SCM_SMOB_DATA_3}.
 105 @end deftypefn
 106
 107
 108 @deftypefn {C Function} void scm_set_smob_print (scm_t_bits tc, int (*print) (SCM obj, SCM port, scm_print_state* pstate))
 109 This function sets the smob printing procedure for the smob type
 110 specified by the tag @var{tc}. @var{tc} is the tag returned by
 111 @code{scm_make_smob_type}.
 112
 113 The @var{print} procedure should output a textual representation of
 114 the smob instance @var{obj} to @var{port}, using information in
 115 @var{pstate}.
 116
 117 The textual representation should be of the form @code{#<name ...>}.
 118 This ensures that @code{read} will not interpret it as some other
 119 Scheme value.
 120
 121 It is often best to ignore @var{pstate} and just print to @var{port}
 122 with @code{scm_display}, @code{scm_write}, @code{scm_simple_format},
 123 and @code{scm_puts}.
 124 @end deftypefn
 125
 126 @deftypefn {C Function} void scm_set_smob_equalp (scm_t_bits tc, SCM (*equalp) (SCM obj1, SCM obj2))
 127 This function sets the smob equality-testing predicate for the smob
 128 type specified by the tag @var{tc}. @var{tc} is the tag returned by
 129 @code{scm_make_smob_type}.
 130
 131 The @var{equalp} procedure should return @code{SCM_BOOL_T} when
 132 @var{obj1} is @code{equal?} to @var{obj2}.  Else it should return
 133 @code{SCM_BOOL_F}.  Both @var{obj1} and @var{obj2} are instances of the
 134 smob type @var{tc}.
 135 @end deftypefn
 136
 137 @deftypefn {C Function} void scm_assert_smob_type (scm_t_bits tag, SCM val)
 138 When @var{val} is a smob of the type indicated by @var{tag}, do nothing.
 139 Else, signal an error.
 140 @end deftypefn
 141
 142 @deftypefn {C Macro} int SCM_SMOB_PREDICATE (scm_t_bits tag, SCM exp)
 143 Return true if @var{exp} is a smob instance of the type indicated by
 144 @var{tag}, or false otherwise.  The expression @var{exp} can be
 145 evaluated more than once, so it shouldn't contain any side effects.
 146 @end deftypefn
 147
 148 @deftypefn {C Function} SCM scm_new_smob (scm_t_bits tag, void *data)
 149 @deftypefnx {C Function} SCM scm_new_double_smob (scm_t_bits tag, void *data, void *data2, void *data3)
 150 Make a new smob of the type with tag @var{tag} and smob data @var{data},
 151 @var{data2}, and @var{data3}, as appropriate.
 152
 153 The @var{tag} is what has been returned by @code{scm_make_smob_type}.
 154 The initial values @var{data}, @var{data2}, and @var{data3} are of
 155 type @code{scm_t_bits}; when you want to use them for @code{SCM}
 156 values, these values need to be converted to a @code{scm_t_bits} first
 157 by using @code{SCM_UNPACK}.
 158
 159 The flags of the smob instance start out as zero.
 160 @end deftypefn
 161
 162 @deftypefn {C Macro} scm_t_bits SCM_SMOB_FLAGS (SCM obj)
 163 Return the 16 extra bits of the smob @var{obj}.  No meaning is
 164 predefined for these bits, you can use them freely.
 165 @end deftypefn
 166
 167 @deftypefn {C Macro} scm_t_bits SCM_SET_SMOB_FLAGS (SCM obj, scm_t_bits flags)
 168 Set the 16 extra bits of the smob @var{obj} to @var{flags}.  No
 169 meaning is predefined for these bits, you can use them freely.
 170 @end deftypefn
 171
 172 @deftypefn {C Macro} scm_t_bits SCM_SMOB_DATA (SCM obj)
 173 @deftypefnx {C Macro} scm_t_bits SCM_SMOB_DATA_2 (SCM obj)
 174 @deftypefnx {C Macro} scm_t_bits SCM_SMOB_DATA_3 (SCM obj)
 175 Return the first (second, third) immediate word of the smob @var{obj}
 176 as a @code{scm_t_bits} value.  When the word contains a @code{SCM}
 177 value, use @code{SCM_SMOB_OBJECT} (etc.) instead.
 178 @end deftypefn
 179
 180 @deftypefn {C Macro} void SCM_SET_SMOB_DATA (SCM obj, scm_t_bits val)
 181 @deftypefnx {C Macro} void SCM_SET_SMOB_DATA_2 (SCM obj, scm_t_bits val)
 182 @deftypefnx {C Macro} void SCM_SET_SMOB_DATA_3 (SCM obj, scm_t_bits val)
 183 Set the first (second, third) immediate word of the smob @var{obj} to
 184 @var{val}.  When the word should be set to a @code{SCM} value, use
 185 @code{SCM_SMOB_SET_OBJECT} (etc.) instead.
 186 @end deftypefn
 187
 188 @deftypefn {C Macro} SCM SCM_SMOB_OBJECT (SCM obj)
 189 @deftypefnx {C Macro} SCM SCM_SMOB_OBJECT_2 (SCM obj)
 190 @deftypefnx {C Macro} SCM SCM_SMOB_OBJECT_3 (SCM obj)
 191 Return the first (second, third) immediate word of the smob @var{obj}
 192 as a @code{SCM} value.  When the word contains a @code{scm_t_bits}
 193 value, use @code{SCM_SMOB_DATA} (etc.) instead.
 194 @end deftypefn
 195
 196 @deftypefn {C Macro} void SCM_SET_SMOB_OBJECT (SCM obj, SCM val)
 197 @deftypefnx {C Macro} void SCM_SET_SMOB_OBJECT_2 (SCM obj, SCM val)
 198 @deftypefnx {C Macro} void SCM_SET_SMOB_OBJECT_3 (SCM obj, SCM val)
 199 Set the first (second, third) immediate word of the smob @var{obj} to
 200 @var{val}.  When the word should be set to a @code{scm_t_bits} value, use
 201 @code{SCM_SMOB_SET_DATA} (etc.) instead.
 202 @end deftypefn
 203
 204 @deftypefn {C Macro} {SCM *} SCM_SMOB_OBJECT_LOC (SCM obj)
 205 @deftypefnx {C Macro} {SCM *} SCM_SMOB_OBJECT_2_LOC (SCM obj)
 206 @deftypefnx {C Macro} {SCM *} SCM_SMOB_OBJECT_3_LOC (SCM obj)
 207 Return a pointer to the first (second, third) immediate word of the
 208 smob @var{obj}.  Note that this is a pointer to @code{SCM}.  If you
 209 need to work with @code{scm_t_bits} values, use @code{SCM_PACK} and
 210 @code{SCM_UNPACK}, as appropriate.
 211 @end deftypefn
 212
 213 @deftypefun SCM scm_markcdr (SCM @var{x})
 214 Mark the references in the smob @var{x}, assuming that @var{x}'s first
 215 data word contains an ordinary Scheme object, and @var{x} refers to no
 216 other objects.  This function simply returns @var{x}'s first data word.
 217 @end deftypefun
 218
 219 @c Local Variables:
 220 @c TeX-master: "guile.texi"
 221 @c End: