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