Commit | Line | Data |
---|---|---|
2da09c3f MV |
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 | ||
a0e07ba4 NJ |
7 | @page |
8 | @node Memory Management | |
9 | @chapter Memory Management and Garbage Collection | |
10 | ||
c5ee546d MV |
11 | Guile uses a @emph{garbage collector} to manage most of its objects. |
12 | This means that the memory used to store a Scheme string, say, is | |
13 | automatically reclaimed when no one is using this string any longer. | |
14 | This can work because Guile knows enough about its objects at run-time | |
3446b6ef MV |
15 | to be able to trace all references between them. Thus, it can find all |
16 | 'live' objects (objects that are still in use) by starting from a known | |
17 | set of 'root' objects and following the links that these objects have to | |
18 | other objects, and so on. The objects that are not reached by this | |
19 | recursive process can be considered 'dead' and their memory can be | |
20 | reused for new objects. | |
c5ee546d | 21 | |
a0e07ba4 NJ |
22 | @menu |
23 | * Garbage Collection:: | |
0deb6826 | 24 | * Memory Blocks:: |
a0e07ba4 NJ |
25 | * Weak References:: |
26 | * Guardians:: | |
27 | @end menu | |
28 | ||
29 | ||
30 | @node Garbage Collection | |
31 | @section Garbage Collection | |
32 | ||
3446b6ef MV |
33 | The general process of collecting dead objects outlined above relies on |
34 | the fact that the garbage collector is able to find all references to | |
35 | SCM objects that might be used by the program in the future. When you | |
36 | are programming in Scheme, you don't need to worry about this: The | |
37 | collector is automatically aware of all objects in use by Scheme code. | |
38 | ||
39 | When programming in C, you must help the garbage collector a bit so that | |
40 | it can find all objects that are accessible from C. You do this when | |
41 | writing a SMOB mark function, for example. By calling this function, | |
42 | the garbage collector learns about all references that your SMOB has to | |
43 | other SCM objects. | |
44 | ||
45 | Other references to SCM objects, such as global variables of type SCM or | |
46 | other random data structures in the heap that contain fields of type | |
47 | SCM, can be made visible to the garbage collector by calling the | |
48 | functions @code{scm_gc_protect} or @code{scm_permanent_object}. You | |
49 | normally use these funtions for long lived objects such as a hash table | |
50 | that is stored in a global variable. For temporary references in local | |
51 | variables or function arguments, using these functions would be too | |
52 | expensive. | |
53 | ||
54 | These references are handled differently: Local variables (and function | |
55 | arguments) of type SCM are automatically visible to the garbage | |
56 | collector. This works because the collector scans the stack for | |
57 | potential references to SCM objects and considers all referenced objects | |
58 | to be alive. The scanning considers each and every word of the stack, | |
59 | regardless of what it is actually used for, and then decides whether it | |
60 | could possible be a reference to a SCM object. Thus, the scanning is | |
61 | guaranteed to find all actual references, but it might also find words | |
62 | that only accidentally look like references. These `false positives' | |
63 | might keep SCM objects alive that would otherwise be considered dead. | |
64 | While this might waste memory, keeping an object around longer than it | |
65 | strictly needs to is harmless. This is why this technique is called | |
66 | ``conservative garbage collection''. In practice, the wasted memory | |
67 | seems to be no problem. | |
68 | ||
69 | The stack of every thread is scanned in this way and the registers of | |
70 | the CPU and all other memory locations where local variables or function | |
71 | parameters might show up are included in this scan as well. | |
72 | ||
73 | The consequence of the conservative scanning is that you can just | |
74 | declare local variables and function parameters of type SCM and be sure | |
75 | that the garbage collector will not free the corresponding objects. | |
76 | ||
77 | However, a local variable or function parameter is only protected as | |
78 | long as it is really on the stack (or in some register). As an | |
79 | optimization, the C compiler might reuse its location for some other | |
80 | value and the SCM object would no longer be protected. Normally, this | |
81 | leads to exactly the right behabvior: the compiler will only overwrite a | |
82 | reference when it is no longer needed and thus the object becomes | |
83 | unprotected precisely when the reference disappears, just as wanted. | |
84 | ||
85 | There are situations, however, where a SCM object needs to be around | |
86 | longer than its reference from a local variable or function parameter. | |
87 | This happens, for example, when you retrieve the array of characters | |
88 | from a Scheme string and work on that array directly. The reference to | |
89 | the SCM string object might be dead after the character array has been | |
90 | retrieved, but the array itself is still in use and thus the string | |
91 | object must be protected. The compiler does not know about this | |
92 | connection and might overwrite the SCM reference too early. | |
93 | ||
94 | To get around this problem, you can use @code{scm_remember_upto_here_1} | |
95 | and its cousins. It will keep the compiler from overwriting the | |
96 | reference. For an example of its use, see @ref{Remembering During | |
97 | Operations}. | |
98 | ||
8f85c0c6 NJ |
99 | @deffn {Scheme Procedure} gc |
100 | @deffnx {C Function} scm_gc () | |
a0e07ba4 | 101 | Scans all of SCM objects and reclaims for further use those that are |
0deb6826 | 102 | no longer accessible. You normally don't need to call this function |
bcf009c3 | 103 | explicitly. It is called automatically when appropriate. |
a0e07ba4 NJ |
104 | @end deffn |
105 | ||
3446b6ef MV |
106 | @deftypefn {C Function} SCM scm_gc_protect_object (SCM @var{obj}) |
107 | Protects @var{obj} from being freed by the garbage collector, when it | |
108 | otherwise might be. When you are done with the object, call | |
109 | @code{scm_gc_unprotect_object} on the object. Calls to | |
110 | @code{scm_gc_protect}/@code{scm_gc_unprotect_object} can be nested, and | |
111 | the object remains protected until it has been unprotected as many times | |
112 | as it was protected. It is an error to unprotect an object more times | |
113 | than it has been protected. Returns the SCM object it was passed. | |
114 | @end deftypefn | |
115 | ||
116 | @deftypefn {C Function} SCM scm_gc_unprotect_object (SCM @var{obj}) | |
117 | ||
118 | Unprotects an object from the garbage collector which was protected by | |
119 | @code{scm_gc_unprotect_object}. Returns the SCM object it was passed. | |
120 | @end deftypefn | |
121 | ||
122 | @deftypefn {C Function} SCM scm_permanent_object (SCM @var{obj}) | |
123 | ||
124 | Similar to @code{scm_gc_protect_object} in that it causes the | |
125 | collector to always mark the object, except that it should not be | |
126 | nested (only call @code{scm_permanent_object} on an object once), and | |
127 | it has no corresponding unpermanent function. Once an object is | |
128 | declared permanent, it will never be freed. Returns the SCM object it | |
129 | was passed. | |
130 | @end deftypefn | |
131 | ||
132 | @c NOTE: The varargs scm_remember_upto_here is deliberately not | |
133 | @c documented, because we don't think it can be implemented as a nice | |
134 | @c inline compiler directive or asm block. New _3, _4 or whatever | |
135 | @c forms could certainly be added though, if needed. | |
136 | ||
137 | @deftypefn {C Macro} void scm_remember_upto_here_1 (SCM obj) | |
138 | @deftypefnx {C Macro} void scm_remember_upto_here_2 (SCM obj1, SCM obj2) | |
139 | Create a reference to the given object or objects, so they're certain | |
140 | to be present on the stack or in a register and hence will not be | |
141 | freed by the garbage collector before this point. | |
142 | ||
143 | Note that these functions can only be applied to ordinary C local | |
144 | variables (ie.@: ``automatics''). Objects held in global or static | |
145 | variables or some malloced block or the like cannot be protected with | |
146 | this mechanism. | |
147 | @end deftypefn | |
148 | ||
8f85c0c6 NJ |
149 | @deffn {Scheme Procedure} gc-stats |
150 | @deffnx {C Function} scm_gc_stats () | |
a0e07ba4 NJ |
151 | Return an association list of statistics about Guile's current |
152 | use of storage. | |
f631e15e | 153 | |
a0e07ba4 NJ |
154 | @end deffn |
155 | ||
f2ba76ae | 156 | |
0deb6826 MV |
157 | @node Memory Blocks |
158 | @section Memory Blocks | |
159 | ||
160 | In C programs, dynamic management of memory blocks is normally done | |
161 | with the functions malloc, realloc, and free. Guile has additional | |
162 | functions for dynamic memory allocation that are integrated into the | |
163 | garbage collector and the error reporting system. | |
164 | ||
165 | Memory blocks that are associated with Scheme objects (for example a | |
166 | smob) should be allocated and freed with @code{scm_gc_malloc} and | |
167 | @code{scm_gc_free}. The function @code{scm_gc_malloc} will either | |
168 | return a valid pointer or signal an error. It will also assume that | |
169 | the new memory can be freed by a garbage collection. The garbage | |
170 | collector uses this information to decide when to try to actually | |
171 | collect some garbage. Memory blocks allocated with | |
172 | @code{scm_gc_malloc} must be freed with @code{scm_gc_free}. | |
173 | ||
174 | For memory that is not associated with a Scheme object, you can use | |
175 | @code{scm_malloc} instead of @code{malloc}. Like | |
176 | @code{scm_gc_malloc}, it will either return a valid pointer or signal | |
177 | an error. However, it will not assume that the new memory block can | |
178 | be freed by a garbage collection. The memory can be freed with | |
179 | @code{free}. | |
180 | ||
181 | There is also @code{scm_gc_realloc} and @code{scm_realloc}, to be used | |
ba1b2226 HWN |
182 | in place of @code{realloc} when appropriate, @code{scm_gc_calloc} and |
183 | @code{scm_calloc}, to be used in place of @code{calloc} when | |
184 | appropriate. | |
0deb6826 MV |
185 | |
186 | For really specialized needs, take at look at | |
187 | @code{scm_gc_register_collectable_memory} and | |
188 | @code{scm_gc_unregister_collectable_memory}. | |
189 | ||
800a5002 KR |
190 | @deftypefn {C Function} {void *} scm_malloc (size_t @var{size}) |
191 | @deftypefnx {C Function} {void *} scm_calloc (size_t @var{size}) | |
0deb6826 MV |
192 | Allocate @var{size} bytes of memory and return a pointer to it. When |
193 | @var{size} is 0, return @code{NULL}. When not enough memory is | |
194 | available, signal an error. This function runs the GC to free up some | |
195 | memory when it deems it appropriate. | |
196 | ||
197 | The memory is allocated by the libc @code{malloc} function and can be | |
198 | freed with @code{free}. There is no @code{scm_free} function to go | |
199 | with @code{scm_malloc} to make it easier to pass memory back and forth | |
200 | between different modules. | |
eab1b259 HWN |
201 | |
202 | The function @code{scm_calloc} is similar to @code{scm_malloc}, but | |
203 | initializes the block of memory to zero as well. | |
0deb6826 MV |
204 | @end deftypefn |
205 | ||
800a5002 | 206 | @deftypefn {C Function} {void *} scm_realloc (void *@var{mem}, size_t @var{new_size}) |
0deb6826 MV |
207 | Change the size of the memory block at @var{mem} to @var{new_size} and |
208 | return its new location. When @var{new_size} is 0, this is the same | |
209 | as calling @code{free} on @var{mem} and @code{NULL} is returned. When | |
210 | @var{mem} is @code{NULL}, this function behaves like @code{scm_malloc} | |
211 | and allocates a new block of size @var{new_size}. | |
212 | ||
213 | When not enough memory is available, signal an error. This function | |
214 | runs the GC to free up some memory when it deems it appropriate. | |
215 | @end deftypefn | |
216 | ||
eab1b259 HWN |
217 | |
218 | ||
219 | ||
0deb6826 MV |
220 | @deftypefn {C Function} void scm_gc_register_collectable_memory (void *@var{mem}, size_t @var{size}, const char *@var{what}) |
221 | Informs the GC that the memory at @var{mem} of size @var{size} can | |
222 | potentially be freed during a GC. That is, announce that @var{mem} is | |
223 | part of a GC controlled object and when the GC happens to free that | |
224 | object, @var{size} bytes will be freed along with it. The GC will | |
225 | @strong{not} free the memory itself, it will just know that so-and-so | |
226 | much bytes of memory are associated with GC controlled objects and the | |
227 | memory system figures this into its decisions when to run a GC. | |
228 | ||
229 | @var{mem} does not need to come from @code{scm_malloc}. You can only | |
230 | call this function once for every memory block. | |
231 | ||
232 | The @var{what} argument is used for statistical purposes. It should | |
233 | describe the type of object that the memory will be used for so that | |
234 | users can identify just what strange objects are eating up their | |
235 | memory. | |
236 | @end deftypefn | |
237 | ||
238 | @deftypefn {C Function} void scm_gc_unregister_collectable_memory (void *@var{mem}, size_t @var{size}) | |
239 | Informs the GC that the memory at @var{mem} of size @var{size} is no | |
240 | longer associated with a GC controlled object. You must take care to | |
241 | match up every call to @code{scm_gc_register_collectable_memory} with | |
242 | a call to @code{scm_gc_unregister_collectable_memory}. If you don't do | |
243 | this, the GC might have a wrong impression of what is going on and run | |
244 | much less efficiently than it could. | |
245 | @end deftypefn | |
246 | ||
800a5002 KR |
247 | @deftypefn {C Function} {void *} scm_gc_malloc (size_t @var{size}, const char *@var{what}) |
248 | @deftypefnx {C Function} {void *} scm_gc_realloc (void *@var{mem}, size_t @var{old_size}, size_t @var{new_size}, const char *@var{what}); | |
249 | @deftypefnx {C Function} {void *} scm_gc_calloc (size_t @var{size}, const char *@var{what}) | |
eab1b259 HWN |
250 | Like @code{scm_malloc}, @code{scm_realloc} or @code{scm_calloc}, but |
251 | also call @code{scm_gc_register_collectable_memory}. Note that you | |
252 | need to pass the old size of a reallocated memory block as well. See | |
253 | below for a motivation. | |
0deb6826 MV |
254 | @end deftypefn |
255 | ||
eab1b259 | 256 | |
0deb6826 MV |
257 | @deftypefn {C Function} void scm_gc_free (void *@var{mem}, size_t @var{size}, const char *@var{what}) |
258 | Like @code{free}, but also call @code{scm_gc_unregister_collectable_memory}. | |
259 | ||
260 | Note that you need to explicitely pass the @var{size} parameter. This | |
261 | is done since it should normally be easy to provide this parameter | |
262 | (for memory that is associated with GC controlled objects) and this | |
263 | frees us from tracking this value in the GC itself, which will keep | |
264 | the memory management overhead very low. | |
265 | @end deftypefn | |
a0e07ba4 | 266 | |
f2ba76ae NJ |
267 | @deffn {Scheme Procedure} malloc-stats |
268 | Return an alist ((@var{what} . @var{n}) ...) describing number | |
269 | of malloced objects. | |
270 | @var{what} is the second argument to @code{scm_gc_malloc}, | |
271 | @var{n} is the number of objects of that type currently | |
272 | allocated. | |
273 | @end deffn | |
274 | ||
a0e07ba4 | 275 | |
f2ba76ae | 276 | @subsection Upgrading from scm_must_malloc et al. |
3392a571 MV |
277 | |
278 | Version 1.6 of Guile and earlier did not have the functions from the | |
279 | previous section. In their place, it had the functions | |
280 | @code{scm_must_malloc}, @code{scm_must_realloc} and | |
281 | @code{scm_must_free}. This section explains why we want you to stop | |
282 | using them, and how to do this. | |
283 | ||
8510ef7a KR |
284 | @findex scm_must_malloc |
285 | @findex scm_must_realloc | |
286 | @findex scm_must_calloc | |
287 | @findex scm_must_free | |
3392a571 MV |
288 | The functions @code{scm_must_malloc} and @code{scm_must_realloc} |
289 | behaved like @code{scm_gc_malloc} and @code{scm_gc_realloc} do now, | |
290 | respectively. They would inform the GC about the newly allocated | |
291 | memory via the internal equivalent of | |
292 | @code{scm_gc_register_collectable_memory}. However, | |
293 | @code{scm_must_free} did not unregister the memory it was about to | |
294 | free. The usual way to unregister memory was to return its size from | |
295 | a smob free function. | |
296 | ||
297 | This disconnectedness of the actual freeing of memory and reporting | |
298 | this to the GC proved to be bad in practice. It was easy to make | |
299 | mistakes and report the wrong size because allocating and freeing was | |
300 | not done with symmetric code, and because it is cumbersome to compute | |
301 | the total size of nested data structures that were freed with multiple | |
302 | calls to @code{scm_must_free}. Additionally, there was no equivalent | |
303 | to @code{scm_malloc}, and it was tempting to just use | |
304 | @code{scm_must_malloc} and never to tell the GC that the memory has | |
305 | been freed. | |
306 | ||
307 | The effect was that the internal statistics kept by the GC drifted out | |
308 | of sync with reality and could even overflow in long running programs. | |
309 | When this happened, the result was a dramatic increase in (senseless) | |
310 | GC activity which would effectively stop the program dead. | |
311 | ||
8510ef7a KR |
312 | @findex scm_done_malloc |
313 | @findex scm_done_free | |
3392a571 MV |
314 | The functions @code{scm_done_malloc} and @code{scm_done_free} were |
315 | introduced to help restore balance to the force, but existing bugs did | |
316 | not magically disappear, of course. | |
317 | ||
318 | Therefore we decided to force everybody to review their code by | |
319 | deprecating the existing functions and introducing new ones in their | |
320 | place that are hopefully easier to use correctly. | |
321 | ||
322 | For every use of @code{scm_must_malloc} you need to decide whether to | |
323 | use @code{scm_malloc} or @code{scm_gc_malloc} in its place. When the | |
324 | memory block is not part of a smob or some other Scheme object whose | |
325 | lifetime is ultimately managed by the garbage collector, use | |
326 | @code{scm_malloc} and @code{free}. When it is part of a smob, use | |
327 | @code{scm_gc_malloc} and change the smob free function to use | |
328 | @code{scm_gc_free} instead of @code{scm_must_free} or @code{free} and | |
329 | make it return zero. | |
330 | ||
331 | The important thing is to always pair @code{scm_malloc} with | |
332 | @code{free}; and to always pair @code{scm_gc_malloc} with | |
333 | @code{scm_gc_free}. | |
334 | ||
335 | The same reasoning applies to @code{scm_must_realloc} and | |
336 | @code{scm_realloc} versus @code{scm_gc_realloc}. | |
337 | ||
f2ba76ae | 338 | |
a0e07ba4 NJ |
339 | @node Weak References |
340 | @section Weak References | |
341 | ||
0deb6826 MV |
342 | [FIXME: This chapter is based on Mikael Djurfeldt's answer to a |
343 | question by Michael Livshin. Any mistakes are not theirs, of course. ] | |
a0e07ba4 NJ |
344 | |
345 | Weak references let you attach bookkeeping information to data so that | |
346 | the additional information automatically disappears when the original | |
347 | data is no longer in use and gets garbage collected. In a weak key hash, | |
348 | the hash entry for that key disappears as soon as the key is no longer | |
85a9b4ed | 349 | referenced from anywhere else. For weak value hashes, the same happens |
a0e07ba4 NJ |
350 | as soon as the value is no longer in use. Entries in a doubly weak hash |
351 | disappear when either the key or the value are not used anywhere else | |
352 | anymore. | |
353 | ||
198586ed NJ |
354 | Object properties offer the same kind of functionality as weak key |
355 | hashes in many situations. (@pxref{Object Properties}) | |
a0e07ba4 NJ |
356 | |
357 | Here's an example (a little bit strained perhaps, but one of the | |
358 | examples is actually used in Guile): | |
359 | ||
360 | Assume that you're implementing a debugging system where you want to | |
361 | associate information about filename and position of source code | |
362 | expressions with the expressions themselves. | |
363 | ||
364 | Hashtables can be used for that, but if you use ordinary hash tables | |
365 | it will be impossible for the scheme interpreter to "forget" old | |
366 | source when, for example, a file is reloaded. | |
367 | ||
368 | To implement the mapping from source code expressions to positional | |
369 | information it is necessary to use weak-key tables since we don't want | |
370 | the expressions to be remembered just because they are in our table. | |
371 | ||
372 | To implement a mapping from source file line numbers to source code | |
373 | expressions you would use a weak-value table. | |
374 | ||
375 | To implement a mapping from source code expressions to the procedures | |
376 | they constitute a doubly-weak table has to be used. | |
377 | ||
378 | @menu | |
379 | * Weak key hashes:: | |
380 | * Weak vectors:: | |
381 | @end menu | |
382 | ||
383 | ||
384 | @node Weak key hashes | |
385 | @subsection Weak key hashes | |
386 | ||
8f85c0c6 NJ |
387 | @deffn {Scheme Procedure} make-weak-key-hash-table size |
388 | @deffnx {Scheme Procedure} make-weak-value-hash-table size | |
389 | @deffnx {Scheme Procedure} make-doubly-weak-hash-table size | |
390 | @deffnx {C Function} scm_make_weak_key_hash_table (size) | |
391 | @deffnx {C Function} scm_make_weak_value_hash_table (size) | |
392 | @deffnx {C Function} scm_make_doubly_weak_hash_table (size) | |
a0e07ba4 NJ |
393 | Return a weak hash table with @var{size} buckets. As with any |
394 | hash table, choosing a good size for the table requires some | |
395 | caution. | |
396 | ||
397 | You can modify weak hash tables in exactly the same way you | |
398 | would modify regular hash tables. (@pxref{Hash Tables}) | |
399 | @end deffn | |
400 | ||
8f85c0c6 NJ |
401 | @deffn {Scheme Procedure} weak-key-hash-table? obj |
402 | @deffnx {Scheme Procedure} weak-value-hash-table? obj | |
403 | @deffnx {Scheme Procedure} doubly-weak-hash-table? obj | |
404 | @deffnx {C Function} scm_weak_key_hash_table_p (obj) | |
405 | @deffnx {C Function} scm_weak_value_hash_table_p (obj) | |
406 | @deffnx {C Function} scm_doubly_weak_hash_table_p (obj) | |
a0e07ba4 NJ |
407 | Return @code{#t} if @var{obj} is the specified weak hash |
408 | table. Note that a doubly weak hash table is neither a weak key | |
409 | nor a weak value hash table. | |
410 | @end deffn | |
411 | ||
8f85c0c6 | 412 | @deffn {Scheme Procedure} make-weak-value-hash-table k |
a0e07ba4 NJ |
413 | @end deffn |
414 | ||
8f85c0c6 | 415 | @deffn {Scheme Procedure} weak-value-hash-table? x |
a0e07ba4 NJ |
416 | @end deffn |
417 | ||
8f85c0c6 | 418 | @deffn {Scheme Procedure} make-doubly-weak-hash-table k |
a0e07ba4 NJ |
419 | @end deffn |
420 | ||
8f85c0c6 | 421 | @deffn {Scheme Procedure} doubly-weak-hash-table? x |
a0e07ba4 NJ |
422 | @end deffn |
423 | ||
424 | ||
425 | @node Weak vectors | |
426 | @subsection Weak vectors | |
427 | ||
428 | Weak vectors are mainly useful in Guile's implementation of weak hash | |
429 | tables. | |
430 | ||
8f85c0c6 NJ |
431 | @deffn {Scheme Procedure} make-weak-vector size [fill] |
432 | @deffnx {C Function} scm_make_weak_vector (size, fill) | |
a0e07ba4 NJ |
433 | Return a weak vector with @var{size} elements. If the optional |
434 | argument @var{fill} is given, all entries in the vector will be | |
435 | set to @var{fill}. The default value for @var{fill} is the | |
436 | empty list. | |
437 | @end deffn | |
438 | ||
8f85c0c6 NJ |
439 | @deffn {Scheme Procedure} weak-vector . l |
440 | @deffnx {Scheme Procedure} list->weak-vector l | |
441 | @deffnx {C Function} scm_weak_vector (l) | |
a0e07ba4 NJ |
442 | Construct a weak vector from a list: @code{weak-vector} uses |
443 | the list of its arguments while @code{list->weak-vector} uses | |
444 | its only argument @var{l} (a list) to construct a weak vector | |
445 | the same way @code{list->vector} would. | |
446 | @end deffn | |
447 | ||
8f85c0c6 NJ |
448 | @deffn {Scheme Procedure} weak-vector? obj |
449 | @deffnx {C Function} scm_weak_vector_p (obj) | |
a0e07ba4 NJ |
450 | Return @code{#t} if @var{obj} is a weak vector. Note that all |
451 | weak hashes are also weak vectors. | |
452 | @end deffn | |
453 | ||
454 | ||
455 | @node Guardians | |
456 | @section Guardians | |
457 | ||
8f85c0c6 NJ |
458 | @deffn {Scheme Procedure} make-guardian [greedy?] |
459 | @deffnx {C Function} scm_make_guardian (greedy_p) | |
a0e07ba4 NJ |
460 | Create a new guardian. |
461 | A guardian protects a set of objects from garbage collection, | |
462 | allowing a program to apply cleanup or other actions. | |
463 | ||
464 | @code{make-guardian} returns a procedure representing the guardian. | |
465 | Calling the guardian procedure with an argument adds the | |
466 | argument to the guardian's set of protected objects. | |
467 | Calling the guardian procedure without an argument returns | |
468 | one of the protected objects which are ready for garbage | |
469 | collection, or @code{#f} if no such object is available. | |
470 | Objects which are returned in this way are removed from | |
471 | the guardian. | |
472 | ||
473 | @code{make-guardian} takes one optional argument that says whether the | |
474 | new guardian should be greedy or sharing. If there is any chance | |
475 | that any object protected by the guardian may be resurrected, | |
476 | then you should make the guardian greedy (this is the default). | |
477 | ||
478 | See R. Kent Dybvig, Carl Bruggeman, and David Eby (1993) | |
479 | "Guardians in a Generation-Based Garbage Collector". | |
480 | ACM SIGPLAN Conference on Programming Language Design | |
481 | and Implementation, June 1993. | |
482 | ||
483 | (the semantics are slightly different at this point, but the | |
484 | paper still (mostly) accurately describes the interface). | |
485 | @end deffn | |
486 | ||
8f85c0c6 NJ |
487 | @deffn {Scheme Procedure} destroy-guardian! guardian |
488 | @deffnx {C Function} scm_destroy_guardian_x (guardian) | |
a0e07ba4 NJ |
489 | Destroys @var{guardian}, by making it impossible to put any more |
490 | objects in it or get any objects from it. It also unguards any | |
491 | objects guarded by @var{guardian}. | |
492 | @end deffn | |
493 | ||
8f85c0c6 NJ |
494 | @deffn {Scheme Procedure} guardian-greedy? guardian |
495 | @deffnx {C Function} scm_guardian_greedy_p (guardian) | |
a0e07ba4 NJ |
496 | Return @code{#t} if @var{guardian} is a greedy guardian, otherwise @code{#f}. |
497 | @end deffn | |
498 | ||
8f85c0c6 NJ |
499 | @deffn {Scheme Procedure} guardian-destroyed? guardian |
500 | @deffnx {C Function} scm_guardian_destroyed_p (guardian) | |
a0e07ba4 NJ |
501 | Return @code{#t} if @var{guardian} has been destroyed, otherwise @code{#f}. |
502 | @end deffn | |
503 | ||
504 | ||
505 | @page | |
506 | @node Objects | |
507 | @chapter Objects | |
508 | ||
8f85c0c6 NJ |
509 | @deffn {Scheme Procedure} entity? obj |
510 | @deffnx {C Function} scm_entity_p (obj) | |
a0e07ba4 NJ |
511 | Return @code{#t} if @var{obj} is an entity. |
512 | @end deffn | |
513 | ||
8f85c0c6 NJ |
514 | @deffn {Scheme Procedure} operator? obj |
515 | @deffnx {C Function} scm_operator_p (obj) | |
a0e07ba4 NJ |
516 | Return @code{#t} if @var{obj} is an operator. |
517 | @end deffn | |
518 | ||
8f85c0c6 NJ |
519 | @deffn {Scheme Procedure} set-object-procedure! obj proc |
520 | @deffnx {C Function} scm_set_object_procedure_x (obj, proc) | |
9401323e | 521 | Set the object procedure of @var{obj} to @var{proc}. |
a0e07ba4 NJ |
522 | @var{obj} must be either an entity or an operator. |
523 | @end deffn | |
524 | ||
8f85c0c6 NJ |
525 | @deffn {Scheme Procedure} make-class-object metaclass layout |
526 | @deffnx {C Function} scm_make_class_object (metaclass, layout) | |
a0e07ba4 NJ |
527 | Create a new class object of class @var{metaclass}, with the |
528 | slot layout specified by @var{layout}. | |
529 | @end deffn | |
530 | ||
8f85c0c6 NJ |
531 | @deffn {Scheme Procedure} make-subclass-object class layout |
532 | @deffnx {C Function} scm_make_subclass_object (class, layout) | |
a0e07ba4 NJ |
533 | Create a subclass object of @var{class}, with the slot layout |
534 | specified by @var{layout}. | |
535 | @end deffn | |
536 | ||
537 | ||
538 | @c Local Variables: | |
539 | @c TeX-master: "guile.texi" | |
540 | @c End: |