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 This chapter contains reference information related to defining and
  13 working with smobs.  See @ref{Defining New Types (Smobs)} for a
  14 tutorial-like introduction to smobs.
  15
  16 @deftypefun scm_t_bits scm_make_smob_type (const char *name, size_t size)
  17 This function adds a new smob type, named @var{name}, with instance size
  18 @var{size}, to the system.  The return value is a tag that is used in
  19 creating instances of the type.
  20
  21 If @var{size} is 0, the default @emph{free} function will do nothing.
  22
  23 If @var{size} is not 0, the default @emph{free} function will
  24 deallocate the memory block pointed to by @code{SCM_SMOB_DATA} with
  25 @code{scm_gc_free}.  The @var{what} parameter in the call to
  26 @code{scm_gc_free} will be @var{name}.
  27
  28 Default values are provided for the @emph{mark}, @emph{free},
  29 @emph{print}, and @emph{equalp} functions, as described in
  30 @ref{Defining New Types (Smobs)}.  If you want to customize any of
  31 these functions, the call to @code{scm_make_smob_type} should be
  32 immediately followed by calls to one or several of
  33 @code{scm_set_smob_mark}, @code{scm_set_smob_free},
  34 @code{scm_set_smob_print}, and/or @code{scm_set_smob_equalp}.
  35 @end deftypefun
  36
  37 @cindex finalizer
  38 @cindex finalization
  39
  40 @deftypefn {C Function} void scm_set_smob_free (scm_t_bits tc, size_t (*free) (SCM obj))
  41 This function sets the smob freeing procedure (sometimes referred to as
  42 a @dfn{finalizer}) for the smob type specified by the tag
  43 @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
  44
  45 The @var{free} procedure must deallocate all resources that are
  46 directly associated with the smob instance @var{obj}.  It must assume
  47 that all @code{SCM} values that it references have already been freed
  48 and are thus invalid.
  49
  50 It must also not call any libguile function or macro except
  51 @code{scm_gc_free}, @code{SCM_SMOB_FLAGS}, @code{SCM_SMOB_DATA},
  52 @code{SCM_SMOB_DATA_2}, and @code{SCM_SMOB_DATA_3}.
  53
  54 The @var{free} procedure must return 0.
  55
  56 Note that defining a freeing procedure is not necessary if the resources
  57 associated with @var{obj} consists only of memory allocated with
  58 @code{scm_gc_malloc} or @code{scm_gc_malloc_pointerless} because this
  59 memory is automatically reclaimed by the garbage collector when it is no
  60 longer needed (@pxref{Memory Blocks, @code{scm_gc_malloc}}).
  61 @end deftypefn
  62
  63 Smob free functions must be thread-safe.  @xref{Garbage Collecting
  64 Smobs}, for a discussion on finalizers and concurrency.  If you are
  65 embedding Guile in an application that is not thread-safe, and you
  66 define smob types that need finalization, you might want to disable
  67 automatic finalization, and arrange to call
  68 @code{scm_manually_run_finalizers ()} yourself.
  69
  70 @deftypefn {C Function} int scm_set_automatic_finalization_enabled (int enabled_p)
  71 Enable or disable automatic finalization.  By default, Guile arranges to
  72 invoke object finalizers automatically, in a separate thread if
  73 possible.  Passing a zero value for @var{enabled_p} will disable
  74 automatic finalization for Guile as a whole.  If you disable automatic
  75 finalization, you will have to call @code{scm_run_finalizers ()}
  76 periodically.
  77
  78 Unlike most other Guile functions, you can call
  79 @code{scm_set_automatic_finalization_enabled} before Guile has been
  80 initialized.
  81
  82 Return the previous status of automatic finalization.
  83 @end deftypefn
  84
  85 @deftypefn {C Function} int scm_run_finalizers (void)
  86 Invoke any pending finalizers.  Returns the number of finalizers that
  87 were invoked.  This function should be called when automatic
  88 finalization is disabled, though it may be called if it is enabled as
  89 well.
  90 @end deftypefn
  91
  92
  93 @cindex precise marking
  94
  95 @deftypefn {C Function} void scm_set_smob_mark (scm_t_bits tc, SCM (*mark) (SCM obj))
  96 This function sets the smob marking procedure for the smob type specified by
  97 the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
  98
  99 Defining a marking procedure may sometimes be unnecessary because large
 100 parts of the process' memory (with the exception of
 101 @code{scm_gc_malloc_pointerless} regions, and @code{malloc}- or
 102 @code{scm_malloc}-allocated memory) are scanned for live
 103 pointers@footnote{Conversely, in Guile up to the 1.8 series, the marking
 104 procedure was always required.  The reason is that Guile's GC would only
 105 look for pointers in the memory area used for built-in types (the
 106 @dfn{cell heap}), not in user-allocated or statically allocated memory.
 107 This approach is often referred to as @dfn{precise marking}.}.
 108
 109 The @var{mark} procedure must cause @code{scm_gc_mark} to be called
 110 for every @code{SCM} value that is directly referenced by the smob
 111 instance @var{obj}.  One of these @code{SCM} values can be returned
 112 from the procedure and Guile will call @code{scm_gc_mark} for it.
 113 This can be used to avoid deep recursions for smob instances that form
 114 a list.
 115
 116 It must not call any libguile function or macro except
 117 @code{scm_gc_mark}, @code{SCM_SMOB_FLAGS}, @code{SCM_SMOB_DATA},
 118 @code{SCM_SMOB_DATA_2}, and @code{SCM_SMOB_DATA_3}.
 119 @end deftypefn
 120
 121
 122 @deftypefn {C Function} void scm_set_smob_print (scm_t_bits tc, int (*print) (SCM obj, SCM port, scm_print_state* pstate))
 123 This function sets the smob printing procedure for the smob type
 124 specified by the tag @var{tc}. @var{tc} is the tag returned by
 125 @code{scm_make_smob_type}.
 126
 127 The @var{print} procedure should output a textual representation of
 128 the smob instance @var{obj} to @var{port}, using information in
 129 @var{pstate}.
 130
 131 The textual representation should be of the form @code{#<name ...>}.
 132 This ensures that @code{read} will not interpret it as some other
 133 Scheme value.
 134
 135 It is often best to ignore @var{pstate} and just print to @var{port}
 136 with @code{scm_display}, @code{scm_write}, @code{scm_simple_format},
 137 and @code{scm_puts}.
 138 @end deftypefn
 139
 140 @deftypefn {C Function} void scm_set_smob_equalp (scm_t_bits tc, SCM (*equalp) (SCM obj1, SCM obj2))
 141 This function sets the smob equality-testing predicate for the smob
 142 type specified by the tag @var{tc}. @var{tc} is the tag returned by
 143 @code{scm_make_smob_type}.
 144
 145 The @var{equalp} procedure should return @code{SCM_BOOL_T} when
 146 @var{obj1} is @code{equal?} to @var{obj2}.  Else it should return
 147 @code{SCM_BOOL_F}.  Both @var{obj1} and @var{obj2} are instances of the
 148 smob type @var{tc}.
 149 @end deftypefn
 150
 151 @deftypefn {C Function} void scm_assert_smob_type (scm_t_bits tag, SCM val)
 152 When @var{val} is a smob of the type indicated by @var{tag}, do nothing.
 153 Else, signal an error.
 154 @end deftypefn
 155
 156 @deftypefn {C Macro} int SCM_SMOB_PREDICATE (scm_t_bits tag, SCM exp)
 157 Return true if @var{exp} is a smob instance of the type indicated by
 158 @var{tag}, or false otherwise.  The expression @var{exp} can be
 159 evaluated more than once, so it shouldn't contain any side effects.
 160 @end deftypefn
 161
 162 @deftypefn {C Function} SCM scm_new_smob (scm_t_bits tag, void *data)
 163 @deftypefnx {C Function} SCM scm_new_double_smob (scm_t_bits tag, void *data, void *data2, void *data3)
 164 Make a new smob of the type with tag @var{tag} and smob data @var{data},
 165 @var{data2}, and @var{data3}, as appropriate.
 166
 167 The @var{tag} is what has been returned by @code{scm_make_smob_type}.
 168 The initial values @var{data}, @var{data2}, and @var{data3} are of
 169 type @code{scm_t_bits}; when you want to use them for @code{SCM}
 170 values, these values need to be converted to a @code{scm_t_bits} first
 171 by using @code{SCM_UNPACK}.
 172
 173 The flags of the smob instance start out as zero.
 174 @end deftypefn
 175
 176 @deftypefn {C Macro} scm_t_bits SCM_SMOB_FLAGS (SCM obj)
 177 Return the 16 extra bits of the smob @var{obj}.  No meaning is
 178 predefined for these bits, you can use them freely.
 179 @end deftypefn
 180
 181 @deftypefn {C Macro} scm_t_bits SCM_SET_SMOB_FLAGS (SCM obj, scm_t_bits flags)
 182 Set the 16 extra bits of the smob @var{obj} to @var{flags}.  No
 183 meaning is predefined for these bits, you can use them freely.
 184 @end deftypefn
 185
 186 @deftypefn {C Macro} scm_t_bits SCM_SMOB_DATA (SCM obj)
 187 @deftypefnx {C Macro} scm_t_bits SCM_SMOB_DATA_2 (SCM obj)
 188 @deftypefnx {C Macro} scm_t_bits SCM_SMOB_DATA_3 (SCM obj)
 189 Return the first (second, third) immediate word of the smob @var{obj}
 190 as a @code{scm_t_bits} value.  When the word contains a @code{SCM}
 191 value, use @code{SCM_SMOB_OBJECT} (etc.) instead.
 192 @end deftypefn
 193
 194 @deftypefn {C Macro} void SCM_SET_SMOB_DATA (SCM obj, scm_t_bits val)
 195 @deftypefnx {C Macro} void SCM_SET_SMOB_DATA_2 (SCM obj, scm_t_bits val)
 196 @deftypefnx {C Macro} void SCM_SET_SMOB_DATA_3 (SCM obj, scm_t_bits val)
 197 Set the first (second, third) immediate word of the smob @var{obj} to
 198 @var{val}.  When the word should be set to a @code{SCM} value, use
 199 @code{SCM_SMOB_SET_OBJECT} (etc.) instead.
 200 @end deftypefn
 201
 202 @deftypefn {C Macro} SCM SCM_SMOB_OBJECT (SCM obj)
 203 @deftypefnx {C Macro} SCM SCM_SMOB_OBJECT_2 (SCM obj)
 204 @deftypefnx {C Macro} SCM SCM_SMOB_OBJECT_3 (SCM obj)
 205 Return the first (second, third) immediate word of the smob @var{obj}
 206 as a @code{SCM} value.  When the word contains a @code{scm_t_bits}
 207 value, use @code{SCM_SMOB_DATA} (etc.) instead.
 208 @end deftypefn
 209
 210 @deftypefn {C Macro} void SCM_SET_SMOB_OBJECT (SCM obj, SCM val)
 211 @deftypefnx {C Macro} void SCM_SET_SMOB_OBJECT_2 (SCM obj, SCM val)
 212 @deftypefnx {C Macro} void SCM_SET_SMOB_OBJECT_3 (SCM obj, SCM val)
 213 Set the first (second, third) immediate word of the smob @var{obj} to
 214 @var{val}.  When the word should be set to a @code{scm_t_bits} value, use
 215 @code{SCM_SMOB_SET_DATA} (etc.) instead.
 216 @end deftypefn
 217
 218 @deftypefn {C Macro} {SCM *} SCM_SMOB_OBJECT_LOC (SCM obj)
 219 @deftypefnx {C Macro} {SCM *} SCM_SMOB_OBJECT_2_LOC (SCM obj)
 220 @deftypefnx {C Macro} {SCM *} SCM_SMOB_OBJECT_3_LOC (SCM obj)
 221 Return a pointer to the first (second, third) immediate word of the
 222 smob @var{obj}.  Note that this is a pointer to @code{SCM}.  If you
 223 need to work with @code{scm_t_bits} values, use @code{SCM_PACK} and
 224 @code{SCM_UNPACK}, as appropriate.
 225 @end deftypefn
 226
 227 @deftypefun SCM scm_markcdr (SCM @var{x})
 228 Mark the references in the smob @var{x}, assuming that @var{x}'s first
 229 data word contains an ordinary Scheme object, and @var{x} refers to no
 230 other objects.  This function simply returns @var{x}'s first data word.
 231 @end deftypefun
 232
 233 @c Local Variables:
 234 @c TeX-master: "guile.texi"
 235 @c End: