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