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.
8 @node Memory Management
9 @section Memory Management and Garbage Collection
11 Guile uses a @emph{garbage collector} to manage most of its objects.
12 While the garbage collector is designed to be mostly invisible, you
13 sometimes need to interact with it explicitely.
15 See @ref{Garbage Collection} for a general discussion of how garbage
16 collection relates to using Guile from C.
19 * Garbage Collection Functions::
26 @node Garbage Collection Functions
27 @subsection Function related to Garbage Collection
29 @deffn {Scheme Procedure} gc
30 @deffnx {C Function} scm_gc ()
31 Scans all of SCM objects and reclaims for further use those that are
32 no longer accessible. You normally don't need to call this function
33 explicitly. It is called automatically when appropriate.
36 @deftypefn {C Function} SCM scm_gc_protect_object (SCM @var{obj})
37 Protects @var{obj} from being freed by the garbage collector, when it
38 otherwise might be. When you are done with the object, call
39 @code{scm_gc_unprotect_object} on the object. Calls to
40 @code{scm_gc_protect}/@code{scm_gc_unprotect_object} can be nested, and
41 the object remains protected until it has been unprotected as many times
42 as it was protected. It is an error to unprotect an object more times
43 than it has been protected. Returns the SCM object it was passed.
46 @deftypefn {C Function} SCM scm_gc_unprotect_object (SCM @var{obj})
48 Unprotects an object from the garbage collector which was protected by
49 @code{scm_gc_unprotect_object}. Returns the SCM object it was passed.
52 @deftypefn {C Function} SCM scm_permanent_object (SCM @var{obj})
54 Similar to @code{scm_gc_protect_object} in that it causes the
55 collector to always mark the object, except that it should not be
56 nested (only call @code{scm_permanent_object} on an object once), and
57 it has no corresponding unpermanent function. Once an object is
58 declared permanent, it will never be freed. Returns the SCM object it
62 @c NOTE: The varargs scm_remember_upto_here is deliberately not
63 @c documented, because we don't think it can be implemented as a nice
64 @c inline compiler directive or asm block. New _3, _4 or whatever
65 @c forms could certainly be added though, if needed.
67 @deftypefn {C Macro} void scm_remember_upto_here_1 (SCM obj)
68 @deftypefnx {C Macro} void scm_remember_upto_here_2 (SCM obj1, SCM obj2)
69 Create a reference to the given object or objects, so they're certain
70 to be present on the stack or in a register and hence will not be
71 freed by the garbage collector before this point.
73 Note that these functions can only be applied to ordinary C local
74 variables (ie.@: ``automatics''). Objects held in global or static
75 variables or some malloced block or the like cannot be protected with
79 @deffn {Scheme Procedure} gc-stats
80 @deffnx {C Function} scm_gc_stats ()
81 Return an association list of statistics about Guile's current
84 @deffn {Scheme Procedure} gc-live-object-stats
85 @deffnx {C Function} scm_gc_live_object_stats ()
86 Return an alist of statistics of the current live objects.
89 @deftypefun void scm_gc_mark (SCM @var{x})
90 Mark the object @var{x}, and recurse on any objects @var{x} refers to.
91 If @var{x}'s mark bit is already set, return immediately. This function
92 must only be called during the mark-phase of garbage collection,
93 typically from a smob @emph{mark} function.
101 @subsection Memory Blocks
103 In C programs, dynamic management of memory blocks is normally done
104 with the functions malloc, realloc, and free. Guile has additional
105 functions for dynamic memory allocation that are integrated into the
106 garbage collector and the error reporting system.
108 Memory blocks that are associated with Scheme objects (for example a
109 smob) should be allocated and freed with @code{scm_gc_malloc} and
110 @code{scm_gc_free}. The function @code{scm_gc_malloc} will either
111 return a valid pointer or signal an error. It will also assume that
112 the new memory can be freed by a garbage collection. The garbage
113 collector uses this information to decide when to try to actually
114 collect some garbage. Memory blocks allocated with
115 @code{scm_gc_malloc} must be freed with @code{scm_gc_free}.
117 For memory that is not associated with a Scheme object, you can use
118 @code{scm_malloc} instead of @code{malloc}. Like
119 @code{scm_gc_malloc}, it will either return a valid pointer or signal
120 an error. However, it will not assume that the new memory block can
121 be freed by a garbage collection. The memory can be freed with
124 There is also @code{scm_gc_realloc} and @code{scm_realloc}, to be used
125 in place of @code{realloc} when appropriate, @code{scm_gc_calloc} and
126 @code{scm_calloc}, to be used in place of @code{calloc} when
129 There function @code{scm_frame_free} can be useful when memory should
130 be freed when a frame is left, @xref{Frames}.
132 For really specialized needs, take at look at
133 @code{scm_gc_register_collectable_memory} and
134 @code{scm_gc_unregister_collectable_memory}.
136 @deftypefn {C Function} {void *} scm_malloc (size_t @var{size})
137 @deftypefnx {C Function} {void *} scm_calloc (size_t @var{size})
138 Allocate @var{size} bytes of memory and return a pointer to it. When
139 @var{size} is 0, return @code{NULL}. When not enough memory is
140 available, signal an error. This function runs the GC to free up some
141 memory when it deems it appropriate.
143 The memory is allocated by the libc @code{malloc} function and can be
144 freed with @code{free}. There is no @code{scm_free} function to go
145 with @code{scm_malloc} to make it easier to pass memory back and forth
146 between different modules.
148 The function @code{scm_calloc} is similar to @code{scm_malloc}, but
149 initializes the block of memory to zero as well.
152 @deftypefn {C Function} {void *} scm_realloc (void *@var{mem}, size_t @var{new_size})
153 Change the size of the memory block at @var{mem} to @var{new_size} and
154 return its new location. When @var{new_size} is 0, this is the same
155 as calling @code{free} on @var{mem} and @code{NULL} is returned. When
156 @var{mem} is @code{NULL}, this function behaves like @code{scm_malloc}
157 and allocates a new block of size @var{new_size}.
159 When not enough memory is available, signal an error. This function
160 runs the GC to free up some memory when it deems it appropriate.
166 @deftypefn {C Function} void scm_gc_register_collectable_memory (void *@var{mem}, size_t @var{size}, const char *@var{what})
167 Informs the GC that the memory at @var{mem} of size @var{size} can
168 potentially be freed during a GC. That is, announce that @var{mem} is
169 part of a GC controlled object and when the GC happens to free that
170 object, @var{size} bytes will be freed along with it. The GC will
171 @strong{not} free the memory itself, it will just know that so-and-so
172 much bytes of memory are associated with GC controlled objects and the
173 memory system figures this into its decisions when to run a GC.
175 @var{mem} does not need to come from @code{scm_malloc}. You can only
176 call this function once for every memory block.
178 The @var{what} argument is used for statistical purposes. It should
179 describe the type of object that the memory will be used for so that
180 users can identify just what strange objects are eating up their
184 @deftypefn {C Function} void scm_gc_unregister_collectable_memory (void *@var{mem}, size_t @var{size})
185 Informs the GC that the memory at @var{mem} of size @var{size} is no
186 longer associated with a GC controlled object. You must take care to
187 match up every call to @code{scm_gc_register_collectable_memory} with
188 a call to @code{scm_gc_unregister_collectable_memory}. If you don't do
189 this, the GC might have a wrong impression of what is going on and run
190 much less efficiently than it could.
193 @deftypefn {C Function} {void *} scm_gc_malloc (size_t @var{size}, const char *@var{what})
194 @deftypefnx {C Function} {void *} scm_gc_realloc (void *@var{mem}, size_t @var{old_size}, size_t @var{new_size}, const char *@var{what});
195 @deftypefnx {C Function} {void *} scm_gc_calloc (size_t @var{size}, const char *@var{what})
196 Like @code{scm_malloc}, @code{scm_realloc} or @code{scm_calloc}, but
197 also call @code{scm_gc_register_collectable_memory}. Note that you
198 need to pass the old size of a reallocated memory block as well. See
199 below for a motivation.
203 @deftypefn {C Function} void scm_gc_free (void *@var{mem}, size_t @var{size}, const char *@var{what})
204 Like @code{free}, but also call @code{scm_gc_unregister_collectable_memory}.
206 Note that you need to explicitely pass the @var{size} parameter. This
207 is done since it should normally be easy to provide this parameter
208 (for memory that is associated with GC controlled objects) and this
209 frees us from tracking this value in the GC itself, which will keep
210 the memory management overhead very low.
213 @deftypefn {C Function} void scm_frame_free (void *mem)
214 Equivalent to @code{scm_frame_unwind_handler (free, @var{mem},
215 SCM_F_WIND_EXPLICITLY)}. That is, the memory block at @var{mem} will
216 be freed when the current frame is left.
219 @deffn {Scheme Procedure} malloc-stats
220 Return an alist ((@var{what} . @var{n}) ...) describing number
222 @var{what} is the second argument to @code{scm_gc_malloc},
223 @var{n} is the number of objects of that type currently
228 @subsubsection Upgrading from scm_must_malloc et al.
230 Version 1.6 of Guile and earlier did not have the functions from the
231 previous section. In their place, it had the functions
232 @code{scm_must_malloc}, @code{scm_must_realloc} and
233 @code{scm_must_free}. This section explains why we want you to stop
234 using them, and how to do this.
236 @findex scm_must_malloc
237 @findex scm_must_realloc
238 @findex scm_must_calloc
239 @findex scm_must_free
240 The functions @code{scm_must_malloc} and @code{scm_must_realloc}
241 behaved like @code{scm_gc_malloc} and @code{scm_gc_realloc} do now,
242 respectively. They would inform the GC about the newly allocated
243 memory via the internal equivalent of
244 @code{scm_gc_register_collectable_memory}. However,
245 @code{scm_must_free} did not unregister the memory it was about to
246 free. The usual way to unregister memory was to return its size from
247 a smob free function.
249 This disconnectedness of the actual freeing of memory and reporting
250 this to the GC proved to be bad in practice. It was easy to make
251 mistakes and report the wrong size because allocating and freeing was
252 not done with symmetric code, and because it is cumbersome to compute
253 the total size of nested data structures that were freed with multiple
254 calls to @code{scm_must_free}. Additionally, there was no equivalent
255 to @code{scm_malloc}, and it was tempting to just use
256 @code{scm_must_malloc} and never to tell the GC that the memory has
259 The effect was that the internal statistics kept by the GC drifted out
260 of sync with reality and could even overflow in long running programs.
261 When this happened, the result was a dramatic increase in (senseless)
262 GC activity which would effectively stop the program dead.
264 @findex scm_done_malloc
265 @findex scm_done_free
266 The functions @code{scm_done_malloc} and @code{scm_done_free} were
267 introduced to help restore balance to the force, but existing bugs did
268 not magically disappear, of course.
270 Therefore we decided to force everybody to review their code by
271 deprecating the existing functions and introducing new ones in their
272 place that are hopefully easier to use correctly.
274 For every use of @code{scm_must_malloc} you need to decide whether to
275 use @code{scm_malloc} or @code{scm_gc_malloc} in its place. When the
276 memory block is not part of a smob or some other Scheme object whose
277 lifetime is ultimately managed by the garbage collector, use
278 @code{scm_malloc} and @code{free}. When it is part of a smob, use
279 @code{scm_gc_malloc} and change the smob free function to use
280 @code{scm_gc_free} instead of @code{scm_must_free} or @code{free} and
283 The important thing is to always pair @code{scm_malloc} with
284 @code{free}; and to always pair @code{scm_gc_malloc} with
287 The same reasoning applies to @code{scm_must_realloc} and
288 @code{scm_realloc} versus @code{scm_gc_realloc}.
291 @node Weak References
292 @subsection Weak References
294 [FIXME: This chapter is based on Mikael Djurfeldt's answer to a
295 question by Michael Livshin. Any mistakes are not theirs, of course. ]
297 Weak references let you attach bookkeeping information to data so that
298 the additional information automatically disappears when the original
299 data is no longer in use and gets garbage collected. In a weak key hash,
300 the hash entry for that key disappears as soon as the key is no longer
301 referenced from anywhere else. For weak value hashes, the same happens
302 as soon as the value is no longer in use. Entries in a doubly weak hash
303 disappear when either the key or the value are not used anywhere else
306 Object properties offer the same kind of functionality as weak key
307 hashes in many situations. (@pxref{Object Properties})
309 Here's an example (a little bit strained perhaps, but one of the
310 examples is actually used in Guile):
312 Assume that you're implementing a debugging system where you want to
313 associate information about filename and position of source code
314 expressions with the expressions themselves.
316 Hashtables can be used for that, but if you use ordinary hash tables
317 it will be impossible for the scheme interpreter to "forget" old
318 source when, for example, a file is reloaded.
320 To implement the mapping from source code expressions to positional
321 information it is necessary to use weak-key tables since we don't want
322 the expressions to be remembered just because they are in our table.
324 To implement a mapping from source file line numbers to source code
325 expressions you would use a weak-value table.
327 To implement a mapping from source code expressions to the procedures
328 they constitute a doubly-weak table has to be used.
336 @node Weak hash tables
337 @subsubsection Weak hash tables
339 @deffn {Scheme Procedure} make-weak-key-hash-table size
340 @deffnx {Scheme Procedure} make-weak-value-hash-table size
341 @deffnx {Scheme Procedure} make-doubly-weak-hash-table size
342 @deffnx {C Function} scm_make_weak_key_hash_table (size)
343 @deffnx {C Function} scm_make_weak_value_hash_table (size)
344 @deffnx {C Function} scm_make_doubly_weak_hash_table (size)
345 Return a weak hash table with @var{size} buckets. As with any
346 hash table, choosing a good size for the table requires some
349 You can modify weak hash tables in exactly the same way you
350 would modify regular hash tables. (@pxref{Hash Tables})
353 @deffn {Scheme Procedure} weak-key-hash-table? obj
354 @deffnx {Scheme Procedure} weak-value-hash-table? obj
355 @deffnx {Scheme Procedure} doubly-weak-hash-table? obj
356 @deffnx {C Function} scm_weak_key_hash_table_p (obj)
357 @deffnx {C Function} scm_weak_value_hash_table_p (obj)
358 @deffnx {C Function} scm_doubly_weak_hash_table_p (obj)
359 Return @code{#t} if @var{obj} is the specified weak hash
360 table. Note that a doubly weak hash table is neither a weak key
361 nor a weak value hash table.
365 @subsubsection Weak vectors
367 Weak vectors are mainly useful in Guile's implementation of weak hash
370 @deffn {Scheme Procedure} make-weak-vector size [fill]
371 @deffnx {C Function} scm_make_weak_vector (size, fill)
372 Return a weak vector with @var{size} elements. If the optional
373 argument @var{fill} is given, all entries in the vector will be
374 set to @var{fill}. The default value for @var{fill} is the
378 @deffn {Scheme Procedure} weak-vector . l
379 @deffnx {Scheme Procedure} list->weak-vector l
380 @deffnx {C Function} scm_weak_vector (l)
381 Construct a weak vector from a list: @code{weak-vector} uses
382 the list of its arguments while @code{list->weak-vector} uses
383 its only argument @var{l} (a list) to construct a weak vector
384 the same way @code{list->vector} would.
387 @deffn {Scheme Procedure} weak-vector? obj
388 @deffnx {C Function} scm_weak_vector_p (obj)
389 Return @code{#t} if @var{obj} is a weak vector. Note that all
390 weak hashes are also weak vectors.
395 @subsection Guardians
397 @deffn {Scheme Procedure} make-guardian [greedy?]
398 @deffnx {C Function} scm_make_guardian (greedy_p)
399 Create a new guardian.
400 A guardian protects a set of objects from garbage collection,
401 allowing a program to apply cleanup or other actions.
403 @code{make-guardian} returns a procedure representing the guardian.
404 Calling the guardian procedure with an argument adds the
405 argument to the guardian's set of protected objects.
406 Calling the guardian procedure without an argument returns
407 one of the protected objects which are ready for garbage
408 collection, or @code{#f} if no such object is available.
409 Objects which are returned in this way are removed from
412 @code{make-guardian} takes one optional argument that says whether the
413 new guardian should be greedy or sharing. If there is any chance
414 that any object protected by the guardian may be resurrected,
415 then you should make the guardian greedy (this is the default).
417 See R. Kent Dybvig, Carl Bruggeman, and David Eby (1993)
418 "Guardians in a Generation-Based Garbage Collector".
419 ACM SIGPLAN Conference on Programming Language Design
420 and Implementation, June 1993.
422 (the semantics are slightly different at this point, but the
423 paper still (mostly) accurately describes the interface).
426 @deffn {Scheme Procedure} destroy-guardian! guardian
427 @deffnx {C Function} scm_destroy_guardian_x (guardian)
428 Destroys @var{guardian}, by making it impossible to put any more
429 objects in it or get any objects from it. It also unguards any
430 objects guarded by @var{guardian}.
433 @deffn {Scheme Procedure} guardian-greedy? guardian
434 @deffnx {C Function} scm_guardian_greedy_p (guardian)
435 Return @code{#t} if @var{guardian} is a greedy guardian, otherwise @code{#f}.
438 @deffn {Scheme Procedure} guardian-destroyed? guardian
439 @deffnx {C Function} scm_guardian_destroyed_p (guardian)
440 Return @code{#t} if @var{guardian} has been destroyed, otherwise @code{#f}.
448 @deffn {Scheme Procedure} entity? obj
449 @deffnx {C Function} scm_entity_p (obj)
450 Return @code{#t} if @var{obj} is an entity.
453 @deffn {Scheme Procedure} operator? obj
454 @deffnx {C Function} scm_operator_p (obj)
455 Return @code{#t} if @var{obj} is an operator.
458 @deffn {Scheme Procedure} set-object-procedure! obj proc
459 @deffnx {C Function} scm_set_object_procedure_x (obj, proc)
460 Set the object procedure of @var{obj} to @var{proc}.
461 @var{obj} must be either an entity or an operator.
464 @deffn {Scheme Procedure} make-class-object metaclass layout
465 @deffnx {C Function} scm_make_class_object (metaclass, layout)
466 Create a new class object of class @var{metaclass}, with the
467 slot layout specified by @var{layout}.
470 @deffn {Scheme Procedure} make-subclass-object class layout
471 @deffnx {C Function} scm_make_subclass_object (class, layout)
472 Create a subclass object of @var{class}, with the slot layout
473 specified by @var{layout}.
478 @c TeX-master: "guile.texi"