Commit | Line | Data |
---|---|---|
07d83abe MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
5b70b4e2 | 3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2013 |
07d83abe MV |
4 | @c Free Software Foundation, Inc. |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
07d83abe MV |
7 | @node Smobs |
8 | @section Smobs | |
9 | ||
f07c349e LC |
10 | @cindex smob |
11 | ||
07d83abe MV |
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 | |
64de6db5 BT |
25 | @code{scm_gc_free}. The @var{what} parameter in the call to |
26 | @code{scm_gc_free} will be @var{name}. | |
07d83abe MV |
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 | ||
f07c349e LC |
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 | |
64de6db5 | 46 | directly associated with the smob instance @var{obj}. It must assume |
f07c349e LC |
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 | @cindex precise marking | |
64 | ||
07d83abe MV |
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}. | |
68 | ||
e0f65135 LC |
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}.}. | |
f07c349e | 78 | |
07d83abe MV |
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 | |
84 | a list. | |
e8a7ec79 MV |
85 | |
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}. | |
07d83abe MV |
89 | @end deftypefn |
90 | ||
07d83abe MV |
91 | |
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}. | |
96 | ||
97 | The @var{print} procedure should output a textual representation of | |
98 | the smob instance @var{obj} to @var{port}, using information in | |
99 | @var{pstate}. | |
100 | ||
101 | The textual representation should be of the form @code{#<name ...>}. | |
102 | This ensures that @code{read} will not interpret it as some other | |
103 | Scheme value. | |
104 | ||
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}, | |
107 | and @code{scm_puts}. | |
108 | @end deftypefn | |
109 | ||
64de6db5 | 110 | @deftypefn {C Function} void scm_set_smob_equalp (scm_t_bits tc, SCM (*equalp) (SCM obj1, SCM obj2)) |
07d83abe MV |
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}. | |
114 | ||
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 | |
64de6db5 | 117 | @code{SCM_BOOL_F}. Both @var{obj1} and @var{obj2} are instances of the |
07d83abe MV |
118 | smob type @var{tc}. |
119 | @end deftypefn | |
120 | ||
52191b37 MV |
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. | |
124 | @end deftypefn | |
125 | ||
07d83abe | 126 | @deftypefn {C Macro} int SCM_SMOB_PREDICATE (scm_t_bits tag, SCM exp) |
a4b4fbbd JE |
127 | Return true if @var{exp} is a smob instance of the type indicated by |
128 | @var{tag}, or false otherwise. The expression @var{exp} can be | |
129 | evaluated more than once, so it shouldn't contain any side effects. | |
07d83abe MV |
130 | @end deftypefn |
131 | ||
5b70b4e2 AW |
132 | @deftypefn {C Function} SCM scm_new_smob (scm_t_bits tag, void *data) |
133 | @deftypefnx {C Function} SCM scm_new_double_smob (scm_t_bits tag, void *data, void *data2, void *data3) | |
134 | Make a new smob of the type with tag @var{tag} and smob data @var{data}, | |
135 | @var{data2}, and @var{data3}, as appropriate. | |
07d83abe MV |
136 | |
137 | The @var{tag} is what has been returned by @code{scm_make_smob_type}. | |
138 | The initial values @var{data}, @var{data2}, and @var{data3} are of | |
139 | type @code{scm_t_bits}; when you want to use them for @code{SCM} | |
140 | values, these values need to be converted to a @code{scm_t_bits} first | |
141 | by using @code{SCM_UNPACK}. | |
142 | ||
143 | The flags of the smob instance start out as zero. | |
144 | @end deftypefn | |
145 | ||
07d83abe MV |
146 | @deftypefn {C Macro} scm_t_bits SCM_SMOB_FLAGS (SCM obj) |
147 | Return the 16 extra bits of the smob @var{obj}. No meaning is | |
148 | predefined for these bits, you can use them freely. | |
149 | @end deftypefn | |
150 | ||
151 | @deftypefn {C Macro} scm_t_bits SCM_SET_SMOB_FLAGS (SCM obj, scm_t_bits flags) | |
152 | Set the 16 extra bits of the smob @var{obj} to @var{flags}. No | |
153 | meaning is predefined for these bits, you can use them freely. | |
154 | @end deftypefn | |
155 | ||
156 | @deftypefn {C Macro} scm_t_bits SCM_SMOB_DATA (SCM obj) | |
157 | @deftypefnx {C Macro} scm_t_bits SCM_SMOB_DATA_2 (SCM obj) | |
158 | @deftypefnx {C Macro} scm_t_bits SCM_SMOB_DATA_3 (SCM obj) | |
159 | Return the first (second, third) immediate word of the smob @var{obj} | |
160 | as a @code{scm_t_bits} value. When the word contains a @code{SCM} | |
161 | value, use @code{SCM_SMOB_OBJECT} (etc.) instead. | |
162 | @end deftypefn | |
163 | ||
164 | @deftypefn {C Macro} void SCM_SET_SMOB_DATA (SCM obj, scm_t_bits val) | |
165 | @deftypefnx {C Macro} void SCM_SET_SMOB_DATA_2 (SCM obj, scm_t_bits val) | |
166 | @deftypefnx {C Macro} void SCM_SET_SMOB_DATA_3 (SCM obj, scm_t_bits val) | |
167 | Set the first (second, third) immediate word of the smob @var{obj} to | |
168 | @var{val}. When the word should be set to a @code{SCM} value, use | |
169 | @code{SCM_SMOB_SET_OBJECT} (etc.) instead. | |
170 | @end deftypefn | |
171 | ||
172 | @deftypefn {C Macro} SCM SCM_SMOB_OBJECT (SCM obj) | |
173 | @deftypefnx {C Macro} SCM SCM_SMOB_OBJECT_2 (SCM obj) | |
174 | @deftypefnx {C Macro} SCM SCM_SMOB_OBJECT_3 (SCM obj) | |
175 | Return the first (second, third) immediate word of the smob @var{obj} | |
176 | as a @code{SCM} value. When the word contains a @code{scm_t_bits} | |
177 | value, use @code{SCM_SMOB_DATA} (etc.) instead. | |
178 | @end deftypefn | |
179 | ||
180 | @deftypefn {C Macro} void SCM_SET_SMOB_OBJECT (SCM obj, SCM val) | |
181 | @deftypefnx {C Macro} void SCM_SET_SMOB_OBJECT_2 (SCM obj, SCM val) | |
182 | @deftypefnx {C Macro} void SCM_SET_SMOB_OBJECT_3 (SCM obj, SCM 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_t_bits} value, use | |
185 | @code{SCM_SMOB_SET_DATA} (etc.) instead. | |
186 | @end deftypefn | |
187 | ||
188 | @deftypefn {C Macro} {SCM *} SCM_SMOB_OBJECT_LOC (SCM obj) | |
189 | @deftypefnx {C Macro} {SCM *} SCM_SMOB_OBJECT_2_LOC (SCM obj) | |
190 | @deftypefnx {C Macro} {SCM *} SCM_SMOB_OBJECT_3_LOC (SCM obj) | |
191 | Return a pointer to the first (second, third) immediate word of the | |
192 | smob @var{obj}. Note that this is a pointer to @code{SCM}. If you | |
193 | need to work with @code{scm_t_bits} values, use @code{SCM_PACK} and | |
194 | @code{SCM_UNPACK}, as appropriate. | |
195 | @end deftypefn | |
196 | ||
197 | @deftypefun SCM scm_markcdr (SCM @var{x}) | |
198 | Mark the references in the smob @var{x}, assuming that @var{x}'s first | |
199 | data word contains an ordinary Scheme object, and @var{x} refers to no | |
200 | other objects. This function simply returns @var{x}'s first data word. | |
201 | @end deftypefun | |
202 | ||
203 | @c Local Variables: | |
204 | @c TeX-master: "guile.texi" | |
205 | @c End: |