Commit | Line | Data |
---|---|---|
07d83abe MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
cc620af7 | 3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2010, 2012, 2013, 2014 |
07d83abe MV |
4 | @c Free Software Foundation, Inc. |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
07d83abe MV |
7 | @node Memory Management |
8 | @section Memory Management and Garbage Collection | |
9 | ||
10 | Guile uses a @emph{garbage collector} to manage most of its objects. | |
11 | While the garbage collector is designed to be mostly invisible, you | |
877f06c3 | 12 | sometimes need to interact with it explicitly. |
07d83abe MV |
13 | |
14 | See @ref{Garbage Collection} for a general discussion of how garbage | |
15 | collection relates to using Guile from C. | |
16 | ||
17 | @menu | |
18 | * Garbage Collection Functions:: | |
19 | * Memory Blocks:: | |
20 | * Weak References:: | |
21 | * Guardians:: | |
22 | @end menu | |
23 | ||
24 | ||
25 | @node Garbage Collection Functions | |
26 | @subsection Function related to Garbage Collection | |
27 | ||
28 | @deffn {Scheme Procedure} gc | |
29 | @deffnx {C Function} scm_gc () | |
30 | Scans all of SCM objects and reclaims for further use those that are | |
31 | no longer accessible. You normally don't need to call this function | |
32 | explicitly. It is called automatically when appropriate. | |
33 | @end deffn | |
34 | ||
35 | @deftypefn {C Function} SCM scm_gc_protect_object (SCM @var{obj}) | |
36 | Protects @var{obj} from being freed by the garbage collector, when it | |
37 | otherwise might be. When you are done with the object, call | |
38 | @code{scm_gc_unprotect_object} on the object. Calls to | |
39 | @code{scm_gc_protect}/@code{scm_gc_unprotect_object} can be nested, and | |
40 | the object remains protected until it has been unprotected as many times | |
41 | as it was protected. It is an error to unprotect an object more times | |
42 | than it has been protected. Returns the SCM object it was passed. | |
f07c349e LC |
43 | |
44 | Note that storing @var{obj} in a C global variable has the same | |
45 | effect@footnote{In Guile up to version 1.8, C global variables were not | |
46 | scanned by the garbage collector; hence, @code{scm_gc_protect_object} | |
47 | was the only way in C to prevent a Scheme object from being freed.}. | |
07d83abe MV |
48 | @end deftypefn |
49 | ||
50 | @deftypefn {C Function} SCM scm_gc_unprotect_object (SCM @var{obj}) | |
51 | ||
52 | Unprotects an object from the garbage collector which was protected by | |
53 | @code{scm_gc_unprotect_object}. Returns the SCM object it was passed. | |
54 | @end deftypefn | |
55 | ||
56 | @deftypefn {C Function} SCM scm_permanent_object (SCM @var{obj}) | |
57 | ||
58 | Similar to @code{scm_gc_protect_object} in that it causes the | |
59 | collector to always mark the object, except that it should not be | |
60 | nested (only call @code{scm_permanent_object} on an object once), and | |
61 | it has no corresponding unpermanent function. Once an object is | |
62 | declared permanent, it will never be freed. Returns the SCM object it | |
63 | was passed. | |
64 | @end deftypefn | |
65 | ||
66 | @c NOTE: The varargs scm_remember_upto_here is deliberately not | |
67 | @c documented, because we don't think it can be implemented as a nice | |
68 | @c inline compiler directive or asm block. New _3, _4 or whatever | |
69 | @c forms could certainly be added though, if needed. | |
70 | ||
71 | @deftypefn {C Macro} void scm_remember_upto_here_1 (SCM obj) | |
72 | @deftypefnx {C Macro} void scm_remember_upto_here_2 (SCM obj1, SCM obj2) | |
73 | Create a reference to the given object or objects, so they're certain | |
74 | to be present on the stack or in a register and hence will not be | |
75 | freed by the garbage collector before this point. | |
76 | ||
77 | Note that these functions can only be applied to ordinary C local | |
78 | variables (ie.@: ``automatics''). Objects held in global or static | |
79 | variables or some malloced block or the like cannot be protected with | |
80 | this mechanism. | |
81 | @end deftypefn | |
82 | ||
83 | @deffn {Scheme Procedure} gc-stats | |
84 | @deffnx {C Function} scm_gc_stats () | |
85 | Return an association list of statistics about Guile's current | |
86 | use of storage. | |
c93557e7 | 87 | @end deffn |
07d83abe | 88 | |
673ba2da MV |
89 | @deffn {Scheme Procedure} gc-live-object-stats |
90 | @deffnx {C Function} scm_gc_live_object_stats () | |
91 | Return an alist of statistics of the current live objects. | |
92 | @end deffn | |
93 | ||
07d83abe MV |
94 | @deftypefun void scm_gc_mark (SCM @var{x}) |
95 | Mark the object @var{x}, and recurse on any objects @var{x} refers to. | |
96 | If @var{x}'s mark bit is already set, return immediately. This function | |
97 | must only be called during the mark-phase of garbage collection, | |
98 | typically from a smob @emph{mark} function. | |
99 | @end deftypefun | |
100 | ||
101 | ||
07d83abe MV |
102 | @node Memory Blocks |
103 | @subsection Memory Blocks | |
104 | ||
56273dea LC |
105 | @cindex automatically-managed memory |
106 | @cindex GC-managed memory | |
107 | @cindex conservative garbage collection | |
108 | ||
07d83abe MV |
109 | In C programs, dynamic management of memory blocks is normally done |
110 | with the functions malloc, realloc, and free. Guile has additional | |
111 | functions for dynamic memory allocation that are integrated into the | |
112 | garbage collector and the error reporting system. | |
113 | ||
114 | Memory blocks that are associated with Scheme objects (for example a | |
4338f2f9 | 115 | foreign object) should be allocated with @code{scm_gc_malloc} or |
56273dea LC |
116 | @code{scm_gc_malloc_pointerless}. These two functions will either |
117 | return a valid pointer or signal an error. Memory blocks allocated this | |
4338f2f9 AW |
118 | way may be released explicitly; however, this is not strictly needed, |
119 | and we recommend @emph{not} calling @code{scm_gc_free}. All memory | |
120 | allocated with @code{scm_gc_malloc} or @code{scm_gc_malloc_pointerless} | |
121 | is automatically reclaimed when the garbage collector no longer sees any | |
122 | live reference to it@footnote{In Guile up to version 1.8, memory | |
123 | allocated with @code{scm_gc_malloc} @emph{had} to be freed with | |
124 | @code{scm_gc_free}.}. | |
56273dea LC |
125 | |
126 | Memory allocated with @code{scm_gc_malloc} is scanned for live pointers. | |
127 | This means that if @code{scm_gc_malloc}-allocated memory contains a | |
128 | pointer to some other part of the memory, the garbage collector notices | |
129 | it and prevents it from being reclaimed@footnote{In Guile up to 1.8, | |
130 | memory allocated with @code{scm_gc_malloc} was @emph{not} scanned. | |
131 | Consequently, the GC had to be told explicitly about pointers to live | |
132 | objects contained in the memory block, e.g., @i{via} SMOB mark functions | |
133 | (@pxref{Smobs, @code{scm_set_smob_mark}})}. Conversely, memory | |
134 | allocated with @code{scm_gc_malloc_pointerless} is assumed to be | |
135 | ``pointer-less'' and is not scanned. | |
07d83abe MV |
136 | |
137 | For memory that is not associated with a Scheme object, you can use | |
138 | @code{scm_malloc} instead of @code{malloc}. Like | |
139 | @code{scm_gc_malloc}, it will either return a valid pointer or signal | |
140 | an error. However, it will not assume that the new memory block can | |
56273dea LC |
141 | be freed by a garbage collection. The memory must be explicitly freed |
142 | with @code{free}. | |
07d83abe MV |
143 | |
144 | There is also @code{scm_gc_realloc} and @code{scm_realloc}, to be used | |
ad0c2091 MV |
145 | in place of @code{realloc} when appropriate, and @code{scm_gc_calloc} |
146 | and @code{scm_calloc}, to be used in place of @code{calloc} when | |
07d83abe MV |
147 | appropriate. |
148 | ||
56273dea LC |
149 | The function @code{scm_dynwind_free} can be useful when memory should be |
150 | freed with libc's @code{free} when leaving a dynwind context, | |
151 | @xref{Dynamic Wind}. | |
07d83abe MV |
152 | |
153 | @deftypefn {C Function} {void *} scm_malloc (size_t @var{size}) | |
154 | @deftypefnx {C Function} {void *} scm_calloc (size_t @var{size}) | |
155 | Allocate @var{size} bytes of memory and return a pointer to it. When | |
156 | @var{size} is 0, return @code{NULL}. When not enough memory is | |
157 | available, signal an error. This function runs the GC to free up some | |
158 | memory when it deems it appropriate. | |
159 | ||
160 | The memory is allocated by the libc @code{malloc} function and can be | |
161 | freed with @code{free}. There is no @code{scm_free} function to go | |
162 | with @code{scm_malloc} to make it easier to pass memory back and forth | |
a90968fa | 163 | between different modules. |
07d83abe MV |
164 | |
165 | The function @code{scm_calloc} is similar to @code{scm_malloc}, but | |
166 | initializes the block of memory to zero as well. | |
cd3370ba AW |
167 | |
168 | These functions will (indirectly) call | |
169 | @code{scm_gc_register_allocation}. | |
07d83abe MV |
170 | @end deftypefn |
171 | ||
172 | @deftypefn {C Function} {void *} scm_realloc (void *@var{mem}, size_t @var{new_size}) | |
173 | Change the size of the memory block at @var{mem} to @var{new_size} and | |
174 | return its new location. When @var{new_size} is 0, this is the same | |
175 | as calling @code{free} on @var{mem} and @code{NULL} is returned. When | |
176 | @var{mem} is @code{NULL}, this function behaves like @code{scm_malloc} | |
177 | and allocates a new block of size @var{new_size}. | |
178 | ||
179 | When not enough memory is available, signal an error. This function | |
180 | runs the GC to free up some memory when it deems it appropriate. | |
cd3370ba AW |
181 | |
182 | This function will call @code{scm_gc_register_allocation}. | |
07d83abe MV |
183 | @end deftypefn |
184 | ||
185 | ||
186 | ||
187 | ||
56273dea LC |
188 | @deftypefn {C Function} {void *} scm_gc_malloc (size_t @var{size}, const char *@var{what}) |
189 | @deftypefnx {C Function} {void *} scm_gc_malloc_pointerless (size_t @var{size}, const char *@var{what}) | |
190 | @deftypefnx {C Function} {void *} scm_gc_realloc (void *@var{mem}, size_t @var{old_size}, size_t @var{new_size}, const char *@var{what}); | |
191 | @deftypefnx {C Function} {void *} scm_gc_calloc (size_t @var{size}, const char *@var{what}) | |
192 | Allocate @var{size} bytes of automatically-managed memory. The memory | |
193 | is automatically freed when no longer referenced from any live memory | |
194 | block. | |
195 | ||
196 | Memory allocated with @code{scm_gc_malloc} or @code{scm_gc_calloc} is | |
197 | scanned for pointers. Memory allocated by | |
198 | @code{scm_gc_malloc_pointerless} is not scanned. | |
199 | ||
200 | The @code{scm_gc_realloc} call preserves the ``pointerlessness'' of the | |
201 | memory area pointed to by @var{mem}. Note that you need to pass the old | |
202 | size of a reallocated memory block as well. See below for a motivation. | |
203 | @end deftypefn | |
204 | ||
205 | ||
206 | @deftypefn {C Function} void scm_gc_free (void *@var{mem}, size_t @var{size}, const char *@var{what}) | |
207 | Explicitly free the memory block pointed to by @var{mem}, which was | |
4338f2f9 AW |
208 | previously allocated by one of the above @code{scm_gc} functions. This |
209 | function is almost always unnecessary, except for codebases that still | |
210 | need to compile on Guile 1.8. | |
56273dea LC |
211 | |
212 | Note that you need to explicitly pass the @var{size} parameter. This | |
213 | is done since it should normally be easy to provide this parameter | |
214 | (for memory that is associated with GC controlled objects) and help keep | |
215 | the memory management overhead very low. However, in Guile 2.x, | |
216 | @var{size} is always ignored. | |
217 | @end deftypefn | |
218 | ||
219 | ||
cd3370ba AW |
220 | @deftypefn {C Function} void scm_gc_register_allocation (size_t @var{size}) |
221 | Informs the garbage collector that @var{size} bytes have been allocated, | |
222 | which the collector would otherwise not have known about. | |
07d83abe | 223 | |
cd3370ba AW |
224 | In general, Scheme will decide to collect garbage only after some amount |
225 | of memory has been allocated. Calling this function will make the | |
226 | Scheme garbage collector know about more allocation, and thus run more | |
227 | often (as appropriate). | |
07d83abe | 228 | |
cd3370ba AW |
229 | It is especially important to call this function when large unmanaged |
230 | allocations, like images, may be freed by small Scheme allocations, like | |
4338f2f9 | 231 | foreign objects. |
07d83abe MV |
232 | @end deftypefn |
233 | ||
234 | ||
cd3370ba AW |
235 | @deftypefn {C Function} void scm_dynwind_free (void *mem) |
236 | Equivalent to @code{scm_dynwind_unwind_handler (free, @var{mem}, | |
237 | SCM_F_WIND_EXPLICITLY)}. That is, the memory block at @var{mem} will be | |
238 | freed (using @code{free} from the C library) when the current dynwind is | |
239 | left. | |
a90968fa MV |
240 | @end deftypefn |
241 | ||
07d83abe MV |
242 | @deffn {Scheme Procedure} malloc-stats |
243 | Return an alist ((@var{what} . @var{n}) ...) describing number | |
244 | of malloced objects. | |
245 | @var{what} is the second argument to @code{scm_gc_malloc}, | |
246 | @var{n} is the number of objects of that type currently | |
247 | allocated. | |
56273dea LC |
248 | |
249 | This function is only available if the @code{GUILE_DEBUG_MALLOC} | |
250 | preprocessor macro was defined when Guile was compiled. | |
07d83abe MV |
251 | @end deffn |
252 | ||
253 | ||
07d83abe MV |
254 | @node Weak References |
255 | @subsection Weak References | |
256 | ||
257 | [FIXME: This chapter is based on Mikael Djurfeldt's answer to a | |
258 | question by Michael Livshin. Any mistakes are not theirs, of course. ] | |
259 | ||
260 | Weak references let you attach bookkeeping information to data so that | |
261 | the additional information automatically disappears when the original | |
262 | data is no longer in use and gets garbage collected. In a weak key hash, | |
263 | the hash entry for that key disappears as soon as the key is no longer | |
264 | referenced from anywhere else. For weak value hashes, the same happens | |
265 | as soon as the value is no longer in use. Entries in a doubly weak hash | |
266 | disappear when either the key or the value are not used anywhere else | |
267 | anymore. | |
268 | ||
269 | Object properties offer the same kind of functionality as weak key | |
270 | hashes in many situations. (@pxref{Object Properties}) | |
271 | ||
272 | Here's an example (a little bit strained perhaps, but one of the | |
273 | examples is actually used in Guile): | |
274 | ||
275 | Assume that you're implementing a debugging system where you want to | |
276 | associate information about filename and position of source code | |
277 | expressions with the expressions themselves. | |
278 | ||
279 | Hashtables can be used for that, but if you use ordinary hash tables | |
280 | it will be impossible for the scheme interpreter to "forget" old | |
281 | source when, for example, a file is reloaded. | |
282 | ||
283 | To implement the mapping from source code expressions to positional | |
284 | information it is necessary to use weak-key tables since we don't want | |
285 | the expressions to be remembered just because they are in our table. | |
286 | ||
287 | To implement a mapping from source file line numbers to source code | |
288 | expressions you would use a weak-value table. | |
289 | ||
290 | To implement a mapping from source code expressions to the procedures | |
291 | they constitute a doubly-weak table has to be used. | |
292 | ||
293 | @menu | |
cdf1ad3b | 294 | * Weak hash tables:: |
07d83abe MV |
295 | * Weak vectors:: |
296 | @end menu | |
297 | ||
298 | ||
cdf1ad3b MV |
299 | @node Weak hash tables |
300 | @subsubsection Weak hash tables | |
07d83abe | 301 | |
b86069c1 MW |
302 | @deffn {Scheme Procedure} make-weak-key-hash-table [size] |
303 | @deffnx {Scheme Procedure} make-weak-value-hash-table [size] | |
304 | @deffnx {Scheme Procedure} make-doubly-weak-hash-table [size] | |
07d83abe MV |
305 | @deffnx {C Function} scm_make_weak_key_hash_table (size) |
306 | @deffnx {C Function} scm_make_weak_value_hash_table (size) | |
307 | @deffnx {C Function} scm_make_doubly_weak_hash_table (size) | |
308 | Return a weak hash table with @var{size} buckets. As with any | |
309 | hash table, choosing a good size for the table requires some | |
310 | caution. | |
311 | ||
312 | You can modify weak hash tables in exactly the same way you | |
313 | would modify regular hash tables. (@pxref{Hash Tables}) | |
314 | @end deffn | |
315 | ||
316 | @deffn {Scheme Procedure} weak-key-hash-table? obj | |
317 | @deffnx {Scheme Procedure} weak-value-hash-table? obj | |
318 | @deffnx {Scheme Procedure} doubly-weak-hash-table? obj | |
319 | @deffnx {C Function} scm_weak_key_hash_table_p (obj) | |
320 | @deffnx {C Function} scm_weak_value_hash_table_p (obj) | |
321 | @deffnx {C Function} scm_doubly_weak_hash_table_p (obj) | |
322 | Return @code{#t} if @var{obj} is the specified weak hash | |
323 | table. Note that a doubly weak hash table is neither a weak key | |
324 | nor a weak value hash table. | |
325 | @end deffn | |
326 | ||
07d83abe MV |
327 | @node Weak vectors |
328 | @subsubsection Weak vectors | |
329 | ||
07d83abe MV |
330 | @deffn {Scheme Procedure} make-weak-vector size [fill] |
331 | @deffnx {C Function} scm_make_weak_vector (size, fill) | |
332 | Return a weak vector with @var{size} elements. If the optional | |
333 | argument @var{fill} is given, all entries in the vector will be | |
334 | set to @var{fill}. The default value for @var{fill} is the | |
335 | empty list. | |
336 | @end deffn | |
337 | ||
df0a1002 | 338 | @deffn {Scheme Procedure} weak-vector elem @dots{} |
07d83abe MV |
339 | @deffnx {Scheme Procedure} list->weak-vector l |
340 | @deffnx {C Function} scm_weak_vector (l) | |
341 | Construct a weak vector from a list: @code{weak-vector} uses | |
342 | the list of its arguments while @code{list->weak-vector} uses | |
343 | its only argument @var{l} (a list) to construct a weak vector | |
344 | the same way @code{list->vector} would. | |
345 | @end deffn | |
346 | ||
347 | @deffn {Scheme Procedure} weak-vector? obj | |
348 | @deffnx {C Function} scm_weak_vector_p (obj) | |
54cded99 | 349 | Return @code{#t} if @var{obj} is a weak vector. |
07d83abe MV |
350 | @end deffn |
351 | ||
1e3fd6a0 AW |
352 | @deffn {Scheme Procedure} weak-vector-ref wvect k |
353 | @deffnx {C Function} scm_weak_vector_ref (wvect, k) | |
354 | Return the @var{k}th element of the weak vector @var{wvect}, or | |
355 | @code{#f} if that element has been collected. | |
356 | @end deffn | |
357 | ||
358 | @deffn {Scheme Procedure} weak-vector-set! wvect k elt | |
359 | @deffnx {C Function} scm_weak_vector_set_x (wvect, k, elt) | |
360 | Set the @var{k}th element of the weak vector @var{wvect} to @var{elt}. | |
361 | @end deffn | |
362 | ||
07d83abe MV |
363 | |
364 | @node Guardians | |
365 | @subsection Guardians | |
366 | ||
930888e8 MV |
367 | Guardians provide a way to be notified about objects that would |
368 | otherwise be collected as garbage. Guarding them prevents the objects | |
369 | from being collected and cleanup actions can be performed on them, for | |
370 | example. | |
07d83abe | 371 | |
930888e8 MV |
372 | See R. Kent Dybvig, Carl Bruggeman, and David Eby (1993) "Guardians in |
373 | a Generation-Based Garbage Collector". ACM SIGPLAN Conference on | |
374 | Programming Language Design and Implementation, June 1993. | |
07d83abe | 375 | |
930888e8 MV |
376 | @deffn {Scheme Procedure} make-guardian |
377 | @deffnx {C Function} scm_make_guardian () | |
378 | Create a new guardian. A guardian protects a set of objects from | |
379 | garbage collection, allowing a program to apply cleanup or other | |
380 | actions. | |
07d83abe | 381 | |
930888e8 MV |
382 | @code{make-guardian} returns a procedure representing the guardian. |
383 | Calling the guardian procedure with an argument adds the argument to | |
384 | the guardian's set of protected objects. Calling the guardian | |
385 | procedure without an argument returns one of the protected objects | |
386 | which are ready for garbage collection, or @code{#f} if no such object | |
387 | is available. Objects which are returned in this way are removed from | |
388 | the guardian. | |
07d83abe | 389 | |
930888e8 MV |
390 | You can put a single object into a guardian more than once and you can |
391 | put a single object into more than one guardian. The object will then | |
392 | be returned multiple times by the guardian procedures. | |
393 | ||
394 | An object is eligible to be returned from a guardian when it is no | |
395 | longer referenced from outside any guardian. | |
396 | ||
397 | There is no guarantee about the order in which objects are returned | |
398 | from a guardian. If you want to impose an order on finalization | |
399 | actions, for example, you can do that by keeping objects alive in some | |
400 | global data structure until they are no longer needed for finalizing | |
401 | other objects. | |
402 | ||
403 | Being an element in a weak vector, a key in a hash table with weak | |
e5547d5f | 404 | keys, or a value in a hash table with weak values does not prevent an |
930888e8 MV |
405 | object from being returned by a guardian. But as long as an object |
406 | can be returned from a guardian it will not be removed from such a | |
407 | weak vector or hash table. In other words, a weak link does not | |
408 | prevent an object from being considered collectable, but being inside | |
409 | a guardian prevents a weak link from being broken. | |
410 | ||
e5547d5f | 411 | A key in a weak key hash table can be thought of as having a strong |
930888e8 | 412 | reference to its associated value as long as the key is accessible. |
e5547d5f MV |
413 | Consequently, when the key is only accessible from within a guardian, |
414 | the reference from the key to the value is also considered to be | |
415 | coming from within a guardian. Thus, if there is no other reference | |
416 | to the value, it is eligible to be returned from a guardian. | |
07d83abe MV |
417 | @end deffn |
418 | ||
419 | ||
07d83abe MV |
420 | @c Local Variables: |
421 | @c TeX-master: "guile.texi" | |
422 | @c End: |