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.
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.
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.
21 If @var{size} is 0, the default @emph{free} function will do nothing.
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}.
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}.
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}.
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
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}.
54 The @var{free} procedure must return 0.
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}}).
63 @cindex precise marking
65 @deftypefn {C Function} void scm_set_smob_mark (scm_t_bits tc, SCM (*mark) (SCM obj))
66 This function sets the smob marking procedure for the smob type specified by
67 the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
69 Defining a marking procedure may sometimes be unnecessary because large
70 parts of the process' memory (with the exception of
71 @code{scm_gc_malloc_pointerless} regions, and @code{malloc}- or
72 @code{scm_malloc}-allocated memory) are scanned for live
73 pointers@footnote{Conversely, in Guile up to the 1.8 series, the marking
74 procedure was always required. The reason is that Guile's GC would only
75 look for pointers in the memory area used for built-in types (the
76 @dfn{cell heap}), not in user-allocated or statically allocated memory.
77 This approach is often referred to as @dfn{precise marking}.}.
79 The @var{mark} procedure must cause @code{scm_gc_mark} to be called
80 for every @code{SCM} value that is directly referenced by the smob
81 instance @var{obj}. One of these @code{SCM} values can be returned
82 from the procedure and Guile will call @code{scm_gc_mark} for it.
83 This can be used to avoid deep recursions for smob instances that form
86 It must not call any libguile function or macro except
87 @code{scm_gc_mark}, @code{SCM_SMOB_FLAGS}, @code{SCM_SMOB_DATA},
88 @code{SCM_SMOB_DATA_2}, and @code{SCM_SMOB_DATA_3}.
92 @deftypefn {C Function} void scm_set_smob_print (scm_t_bits tc, int (*print) (SCM obj, SCM port, scm_print_state* pstate))
93 This function sets the smob printing procedure for the smob type
94 specified by the tag @var{tc}. @var{tc} is the tag returned by
95 @code{scm_make_smob_type}.
97 The @var{print} procedure should output a textual representation of
98 the smob instance @var{obj} to @var{port}, using information in
101 The textual representation should be of the form @code{#<name ...>}.
102 This ensures that @code{read} will not interpret it as some other
105 It is often best to ignore @var{pstate} and just print to @var{port}
106 with @code{scm_display}, @code{scm_write}, @code{scm_simple_format},
110 @deftypefn {C Function} void scm_set_smob_equalp (scm_t_bits tc, SCM (*equalp) (SCM obj1, SCM obj1))
111 This function sets the smob equality-testing predicate for the smob
112 type specified by the tag @var{tc}. @var{tc} is the tag returned by
113 @code{scm_make_smob_type}.
115 The @var{equalp} procedure should return @code{SCM_BOOL_T} when
116 @var{obj1} is @code{equal?} to @var{obj2}. Else it should return
117 @var{SCM_BOOL_F}. Both @var{obj1} and @var{obj2} are instances of the
121 @deftypefn {C Function} void scm_assert_smob_type (scm_t_bits tag, SCM val)
122 When @var{val} is a smob of the type indicated by @var{tag}, do nothing.
123 Else, signal an error.
126 @deftypefn {C Macro} int SCM_SMOB_PREDICATE (scm_t_bits tag, SCM exp)
127 Return true iff @var{exp} is a smob instance of the type indicated by
128 @var{tag}. The expression @var{exp} can be evaluated more than once,
129 so it shouldn't contain any side effects.
132 @deftypefn {C Macro} void SCM_NEWSMOB (SCM value, scm_t_bits tag, void *data)
133 @deftypefnx {C Macro} void SCM_NEWSMOB2 (SCM value, scm_t_bits tag, void *data, void *data2)
134 @deftypefnx {C Macro} void SCM_NEWSMOB3 (SCM value, scm_t_bits tag, void *data, void *data2, void *data3)
135 Make @var{value} contain a smob instance of the type with tag
136 @var{tag} and smob data @var{data}, @var{data2}, and @var{data3}, as
139 The @var{tag} is what has been returned by @code{scm_make_smob_type}.
140 The initial values @var{data}, @var{data2}, and @var{data3} are of
141 type @code{scm_t_bits}; when you want to use them for @code{SCM}
142 values, these values need to be converted to a @code{scm_t_bits} first
143 by using @code{SCM_UNPACK}.
145 The flags of the smob instance start out as zero.
148 Since it is often the case (e.g., in smob constructors) that you will
149 create a smob instance and return it, there is also a slightly specialized
150 macro for this situation:
152 @deftypefn {C Macro} {} SCM_RETURN_NEWSMOB (scm_t_bits tag, void *data)
153 @deftypefnx {C Macro} {} SCM_RETURN_NEWSMOB2 (scm_t_bits tag, void *data1, void *data2)
154 @deftypefnx {C Macro} {} SCM_RETURN_NEWSMOB3 (scm_t_bits tag, void *data1, void *data2, void *data3)
155 This macro expands to a block of code that creates a smob instance of
156 the type with tag @var{tag} and smob data @var{data}, @var{data2}, and
157 @var{data3}, as with @code{SCM_NEWSMOB}, etc., and causes the
158 surrounding function to return that @code{SCM} value. It should be
159 the last piece of code in a block.
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.
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.
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.
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.
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.
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.
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.
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.
220 @c TeX-master: "guile.texi"