summaryrefslogtreecommitdiff
path: root/doc/ref/api-smobs.texi
blob: 345bf7cbda2bff2bc0dacc456e2b151306b6728d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2013
@c   Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.

@node Smobs
@section Smobs

@cindex smob

This chapter contains reference information related to defining and
working with smobs.  See @ref{Defining New Types (Smobs)} for a
tutorial-like introduction to smobs.

@deftypefun scm_t_bits scm_make_smob_type (const char *name, size_t size)
This function adds a new smob type, named @var{name}, with instance size
@var{size}, to the system.  The return value is a tag that is used in
creating instances of the type.

If @var{size} is 0, the default @emph{free} function will do nothing.

If @var{size} is not 0, the default @emph{free} function will
deallocate the memory block pointed to by @code{SCM_SMOB_DATA} with
@code{scm_gc_free}.  The @var{what} parameter in the call to
@code{scm_gc_free} will be @var{name}.

Default values are provided for the @emph{mark}, @emph{free},
@emph{print}, and @emph{equalp} functions, as described in
@ref{Defining New Types (Smobs)}.  If you want to customize any of
these functions, the call to @code{scm_make_smob_type} should be
immediately followed by calls to one or several of
@code{scm_set_smob_mark}, @code{scm_set_smob_free},
@code{scm_set_smob_print}, and/or @code{scm_set_smob_equalp}.
@end deftypefun

@cindex finalizer
@cindex finalization

@deftypefn {C Function} void scm_set_smob_free (scm_t_bits tc, size_t (*free) (SCM obj))
This function sets the smob freeing procedure (sometimes referred to as
a @dfn{finalizer}) for the smob type specified by the tag
@var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.

The @var{free} procedure must deallocate all resources that are
directly associated with the smob instance @var{obj}.  It must assume
that all @code{SCM} values that it references have already been freed
and are thus invalid.

It must also not call any libguile function or macro except
@code{scm_gc_free}, @code{SCM_SMOB_FLAGS}, @code{SCM_SMOB_DATA},
@code{SCM_SMOB_DATA_2}, and @code{SCM_SMOB_DATA_3}.

The @var{free} procedure must return 0.

Note that defining a freeing procedure is not necessary if the resources
associated with @var{obj} consists only of memory allocated with
@code{scm_gc_malloc} or @code{scm_gc_malloc_pointerless} because this
memory is automatically reclaimed by the garbage collector when it is no
longer needed (@pxref{Memory Blocks, @code{scm_gc_malloc}}).
@end deftypefn

@cindex precise marking

@deftypefn {C Function} void scm_set_smob_mark (scm_t_bits tc, SCM (*mark) (SCM obj))
This function sets the smob marking procedure for the smob type specified by
the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.

Defining a marking procedure may sometimes be unnecessary because large
parts of the process' memory (with the exception of
@code{scm_gc_malloc_pointerless} regions, and @code{malloc}- or
@code{scm_malloc}-allocated memory) are scanned for live
pointers@footnote{Conversely, in Guile up to the 1.8 series, the marking
procedure was always required.  The reason is that Guile's GC would only
look for pointers in the memory area used for built-in types (the
@dfn{cell heap}), not in user-allocated or statically allocated memory.
This approach is often referred to as @dfn{precise marking}.}.

The @var{mark} procedure must cause @code{scm_gc_mark} to be called
for every @code{SCM} value that is directly referenced by the smob
instance @var{obj}.  One of these @code{SCM} values can be returned
from the procedure and Guile will call @code{scm_gc_mark} for it.
This can be used to avoid deep recursions for smob instances that form
a list.

It must not call any libguile function or macro except
@code{scm_gc_mark}, @code{SCM_SMOB_FLAGS}, @code{SCM_SMOB_DATA},
@code{SCM_SMOB_DATA_2}, and @code{SCM_SMOB_DATA_3}.
@end deftypefn


@deftypefn {C Function} void scm_set_smob_print (scm_t_bits tc, int (*print) (SCM obj, SCM port, scm_print_state* pstate))
This function sets the smob printing procedure for the smob type
specified by the tag @var{tc}. @var{tc} is the tag returned by
@code{scm_make_smob_type}.

The @var{print} procedure should output a textual representation of
the smob instance @var{obj} to @var{port}, using information in
@var{pstate}.

The textual representation should be of the form @code{#<name ...>}.
This ensures that @code{read} will not interpret it as some other
Scheme value.

It is often best to ignore @var{pstate} and just print to @var{port}
with @code{scm_display}, @code{scm_write}, @code{scm_simple_format},
and @code{scm_puts}.
@end deftypefn

@deftypefn {C Function} void scm_set_smob_equalp (scm_t_bits tc, SCM (*equalp) (SCM obj1, SCM obj2))
This function sets the smob equality-testing predicate for the smob
type specified by the tag @var{tc}. @var{tc} is the tag returned by
@code{scm_make_smob_type}.

The @var{equalp} procedure should return @code{SCM_BOOL_T} when
@var{obj1} is @code{equal?} to @var{obj2}.  Else it should return
@code{SCM_BOOL_F}.  Both @var{obj1} and @var{obj2} are instances of the
smob type @var{tc}.
@end deftypefn

@deftypefn {C Function} void scm_assert_smob_type (scm_t_bits tag, SCM val)
When @var{val} is a smob of the type indicated by @var{tag}, do nothing.
Else, signal an error.
@end deftypefn

@deftypefn {C Macro} int SCM_SMOB_PREDICATE (scm_t_bits tag, SCM exp)
Return true if @var{exp} is a smob instance of the type indicated by
@var{tag}, or false otherwise.  The expression @var{exp} can be
evaluated more than once, so it shouldn't contain any side effects.
@end deftypefn

@deftypefn {C Function} SCM scm_new_smob (scm_t_bits tag, void *data)
@deftypefnx {C Function} SCM scm_new_double_smob (scm_t_bits tag, void *data, void *data2, void *data3)
Make a new smob of the type with tag @var{tag} and smob data @var{data},
@var{data2}, and @var{data3}, as appropriate.

The @var{tag} is what has been returned by @code{scm_make_smob_type}.
The initial values @var{data}, @var{data2}, and @var{data3} are of
type @code{scm_t_bits}; when you want to use them for @code{SCM}
values, these values need to be converted to a @code{scm_t_bits} first
by using @code{SCM_UNPACK}.

The flags of the smob instance start out as zero.
@end deftypefn

@deftypefn {C Macro} scm_t_bits SCM_SMOB_FLAGS (SCM obj)
Return the 16 extra bits of the smob @var{obj}.  No meaning is
predefined for these bits, you can use them freely.
@end deftypefn

@deftypefn {C Macro} scm_t_bits SCM_SET_SMOB_FLAGS (SCM obj, scm_t_bits flags)
Set the 16 extra bits of the smob @var{obj} to @var{flags}.  No
meaning is predefined for these bits, you can use them freely.
@end deftypefn

@deftypefn {C Macro} scm_t_bits SCM_SMOB_DATA (SCM obj)
@deftypefnx {C Macro} scm_t_bits SCM_SMOB_DATA_2 (SCM obj)
@deftypefnx {C Macro} scm_t_bits SCM_SMOB_DATA_3 (SCM obj)
Return the first (second, third) immediate word of the smob @var{obj}
as a @code{scm_t_bits} value.  When the word contains a @code{SCM}
value, use @code{SCM_SMOB_OBJECT} (etc.) instead.
@end deftypefn

@deftypefn {C Macro} void SCM_SET_SMOB_DATA (SCM obj, scm_t_bits val)
@deftypefnx {C Macro} void SCM_SET_SMOB_DATA_2 (SCM obj, scm_t_bits val)
@deftypefnx {C Macro} void SCM_SET_SMOB_DATA_3 (SCM obj, scm_t_bits val)
Set the first (second, third) immediate word of the smob @var{obj} to
@var{val}.  When the word should be set to a @code{SCM} value, use
@code{SCM_SMOB_SET_OBJECT} (etc.) instead.
@end deftypefn

@deftypefn {C Macro} SCM SCM_SMOB_OBJECT (SCM obj)
@deftypefnx {C Macro} SCM SCM_SMOB_OBJECT_2 (SCM obj)
@deftypefnx {C Macro} SCM SCM_SMOB_OBJECT_3 (SCM obj)
Return the first (second, third) immediate word of the smob @var{obj}
as a @code{SCM} value.  When the word contains a @code{scm_t_bits}
value, use @code{SCM_SMOB_DATA} (etc.) instead.
@end deftypefn

@deftypefn {C Macro} void SCM_SET_SMOB_OBJECT (SCM obj, SCM val)
@deftypefnx {C Macro} void SCM_SET_SMOB_OBJECT_2 (SCM obj, SCM val)
@deftypefnx {C Macro} void SCM_SET_SMOB_OBJECT_3 (SCM obj, SCM val)
Set the first (second, third) immediate word of the smob @var{obj} to
@var{val}.  When the word should be set to a @code{scm_t_bits} value, use
@code{SCM_SMOB_SET_DATA} (etc.) instead.
@end deftypefn

@deftypefn {C Macro} {SCM *} SCM_SMOB_OBJECT_LOC (SCM obj)
@deftypefnx {C Macro} {SCM *} SCM_SMOB_OBJECT_2_LOC (SCM obj)
@deftypefnx {C Macro} {SCM *} SCM_SMOB_OBJECT_3_LOC (SCM obj)
Return a pointer to the first (second, third) immediate word of the
smob @var{obj}.  Note that this is a pointer to @code{SCM}.  If you
need to work with @code{scm_t_bits} values, use @code{SCM_PACK} and
@code{SCM_UNPACK}, as appropriate.
@end deftypefn

@deftypefun SCM scm_markcdr (SCM @var{x})
Mark the references in the smob @var{x}, assuming that @var{x}'s first
data word contains an ordinary Scheme object, and @var{x} refers to no
other objects.  This function simply returns @var{x}'s first data word.
@end deftypefun

@c Local Variables:
@c TeX-master: "guile.texi"
@c End: