(%cond-expand-features): Add srfi-61.
[bpt/guile.git] / doc / ref / api-memory.texi
CommitLineData
07d83abe
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
7@page
8@node Memory Management
9@section Memory Management and Garbage Collection
10
11Guile uses a @emph{garbage collector} to manage most of its objects.
12While the garbage collector is designed to be mostly invisible, you
13sometimes need to interact with it explicitely.
14
15See @ref{Garbage Collection} for a general discussion of how garbage
16collection relates to using Guile from C.
17
18@menu
19* Garbage Collection Functions::
20* Memory Blocks::
21* Weak References::
22* Guardians::
23@end menu
24
25
26@node Garbage Collection Functions
27@subsection Function related to Garbage Collection
28
29@deffn {Scheme Procedure} gc
30@deffnx {C Function} scm_gc ()
31Scans all of SCM objects and reclaims for further use those that are
32no longer accessible. You normally don't need to call this function
33explicitly. It is called automatically when appropriate.
34@end deffn
35
36@deftypefn {C Function} SCM scm_gc_protect_object (SCM @var{obj})
37Protects @var{obj} from being freed by the garbage collector, when it
38otherwise 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
41the object remains protected until it has been unprotected as many times
42as it was protected. It is an error to unprotect an object more times
43than it has been protected. Returns the SCM object it was passed.
44@end deftypefn
45
46@deftypefn {C Function} SCM scm_gc_unprotect_object (SCM @var{obj})
47
48Unprotects an object from the garbage collector which was protected by
49@code{scm_gc_unprotect_object}. Returns the SCM object it was passed.
50@end deftypefn
51
52@deftypefn {C Function} SCM scm_permanent_object (SCM @var{obj})
53
54Similar to @code{scm_gc_protect_object} in that it causes the
55collector to always mark the object, except that it should not be
56nested (only call @code{scm_permanent_object} on an object once), and
57it has no corresponding unpermanent function. Once an object is
58declared permanent, it will never be freed. Returns the SCM object it
59was passed.
60@end deftypefn
61
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.
66
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)
69Create a reference to the given object or objects, so they're certain
70to be present on the stack or in a register and hence will not be
71freed by the garbage collector before this point.
72
73Note that these functions can only be applied to ordinary C local
74variables (ie.@: ``automatics''). Objects held in global or static
75variables or some malloced block or the like cannot be protected with
76this mechanism.
77@end deftypefn
78
79@deffn {Scheme Procedure} gc-stats
80@deffnx {C Function} scm_gc_stats ()
81Return an association list of statistics about Guile's current
82use of storage.
c93557e7 83@end deffn
07d83abe 84
673ba2da
MV
85@deffn {Scheme Procedure} gc-live-object-stats
86@deffnx {C Function} scm_gc_live_object_stats ()
87Return an alist of statistics of the current live objects.
88@end deffn
89
07d83abe
MV
90@deftypefun void scm_gc_mark (SCM @var{x})
91Mark the object @var{x}, and recurse on any objects @var{x} refers to.
92If @var{x}'s mark bit is already set, return immediately. This function
93must only be called during the mark-phase of garbage collection,
94typically from a smob @emph{mark} function.
95@end deftypefun
96
97
07d83abe
MV
98@node Memory Blocks
99@subsection Memory Blocks
100
101In C programs, dynamic management of memory blocks is normally done
102with the functions malloc, realloc, and free. Guile has additional
103functions for dynamic memory allocation that are integrated into the
104garbage collector and the error reporting system.
105
106Memory blocks that are associated with Scheme objects (for example a
107smob) should be allocated and freed with @code{scm_gc_malloc} and
108@code{scm_gc_free}. The function @code{scm_gc_malloc} will either
109return a valid pointer or signal an error. It will also assume that
110the new memory can be freed by a garbage collection. The garbage
111collector uses this information to decide when to try to actually
112collect some garbage. Memory blocks allocated with
113@code{scm_gc_malloc} must be freed with @code{scm_gc_free}.
114
115For memory that is not associated with a Scheme object, you can use
116@code{scm_malloc} instead of @code{malloc}. Like
117@code{scm_gc_malloc}, it will either return a valid pointer or signal
118an error. However, it will not assume that the new memory block can
119be freed by a garbage collection. The memory can be freed with
120@code{free}.
121
122There is also @code{scm_gc_realloc} and @code{scm_realloc}, to be used
ad0c2091
MV
123in place of @code{realloc} when appropriate, and @code{scm_gc_calloc}
124and @code{scm_calloc}, to be used in place of @code{calloc} when
07d83abe
MV
125appropriate.
126
ad0c2091
MV
127The function @code{scm_frame_free} can be useful when memory should be
128freed when a frame is left, @xref{Frames}.
a90968fa 129
07d83abe
MV
130For really specialized needs, take at look at
131@code{scm_gc_register_collectable_memory} and
132@code{scm_gc_unregister_collectable_memory}.
133
134@deftypefn {C Function} {void *} scm_malloc (size_t @var{size})
135@deftypefnx {C Function} {void *} scm_calloc (size_t @var{size})
136Allocate @var{size} bytes of memory and return a pointer to it. When
137@var{size} is 0, return @code{NULL}. When not enough memory is
138available, signal an error. This function runs the GC to free up some
139memory when it deems it appropriate.
140
141The memory is allocated by the libc @code{malloc} function and can be
142freed with @code{free}. There is no @code{scm_free} function to go
143with @code{scm_malloc} to make it easier to pass memory back and forth
a90968fa 144between different modules.
07d83abe
MV
145
146The function @code{scm_calloc} is similar to @code{scm_malloc}, but
147initializes the block of memory to zero as well.
148@end deftypefn
149
150@deftypefn {C Function} {void *} scm_realloc (void *@var{mem}, size_t @var{new_size})
151Change the size of the memory block at @var{mem} to @var{new_size} and
152return its new location. When @var{new_size} is 0, this is the same
153as calling @code{free} on @var{mem} and @code{NULL} is returned. When
154@var{mem} is @code{NULL}, this function behaves like @code{scm_malloc}
155and allocates a new block of size @var{new_size}.
156
157When not enough memory is available, signal an error. This function
158runs the GC to free up some memory when it deems it appropriate.
159@end deftypefn
160
161
162
163
164@deftypefn {C Function} void scm_gc_register_collectable_memory (void *@var{mem}, size_t @var{size}, const char *@var{what})
165Informs the GC that the memory at @var{mem} of size @var{size} can
166potentially be freed during a GC. That is, announce that @var{mem} is
167part of a GC controlled object and when the GC happens to free that
168object, @var{size} bytes will be freed along with it. The GC will
169@strong{not} free the memory itself, it will just know that so-and-so
170much bytes of memory are associated with GC controlled objects and the
171memory system figures this into its decisions when to run a GC.
172
173@var{mem} does not need to come from @code{scm_malloc}. You can only
174call this function once for every memory block.
175
176The @var{what} argument is used for statistical purposes. It should
177describe the type of object that the memory will be used for so that
178users can identify just what strange objects are eating up their
179memory.
180@end deftypefn
181
182@deftypefn {C Function} void scm_gc_unregister_collectable_memory (void *@var{mem}, size_t @var{size})
183Informs the GC that the memory at @var{mem} of size @var{size} is no
184longer associated with a GC controlled object. You must take care to
185match up every call to @code{scm_gc_register_collectable_memory} with
186a call to @code{scm_gc_unregister_collectable_memory}. If you don't do
187this, the GC might have a wrong impression of what is going on and run
188much less efficiently than it could.
189@end deftypefn
190
191@deftypefn {C Function} {void *} scm_gc_malloc (size_t @var{size}, const char *@var{what})
192@deftypefnx {C Function} {void *} scm_gc_realloc (void *@var{mem}, size_t @var{old_size}, size_t @var{new_size}, const char *@var{what});
193@deftypefnx {C Function} {void *} scm_gc_calloc (size_t @var{size}, const char *@var{what})
194Like @code{scm_malloc}, @code{scm_realloc} or @code{scm_calloc}, but
195also call @code{scm_gc_register_collectable_memory}. Note that you
196need to pass the old size of a reallocated memory block as well. See
197below for a motivation.
198@end deftypefn
199
200
201@deftypefn {C Function} void scm_gc_free (void *@var{mem}, size_t @var{size}, const char *@var{what})
202Like @code{free}, but also call @code{scm_gc_unregister_collectable_memory}.
203
204Note that you need to explicitely pass the @var{size} parameter. This
205is done since it should normally be easy to provide this parameter
206(for memory that is associated with GC controlled objects) and this
207frees us from tracking this value in the GC itself, which will keep
208the memory management overhead very low.
209@end deftypefn
210
a90968fa
MV
211@deftypefn {C Function} void scm_frame_free (void *mem)
212Equivalent to @code{scm_frame_unwind_handler (free, @var{mem},
213SCM_F_WIND_EXPLICITLY)}. That is, the memory block at @var{mem} will
214be freed when the current frame is left.
215@end deftypefn
216
07d83abe
MV
217@deffn {Scheme Procedure} malloc-stats
218Return an alist ((@var{what} . @var{n}) ...) describing number
219of malloced objects.
220@var{what} is the second argument to @code{scm_gc_malloc},
221@var{n} is the number of objects of that type currently
222allocated.
223@end deffn
224
225
226@subsubsection Upgrading from scm_must_malloc et al.
227
228Version 1.6 of Guile and earlier did not have the functions from the
229previous section. In their place, it had the functions
230@code{scm_must_malloc}, @code{scm_must_realloc} and
231@code{scm_must_free}. This section explains why we want you to stop
232using them, and how to do this.
233
234@findex scm_must_malloc
235@findex scm_must_realloc
236@findex scm_must_calloc
237@findex scm_must_free
238The functions @code{scm_must_malloc} and @code{scm_must_realloc}
239behaved like @code{scm_gc_malloc} and @code{scm_gc_realloc} do now,
240respectively. They would inform the GC about the newly allocated
241memory via the internal equivalent of
242@code{scm_gc_register_collectable_memory}. However,
243@code{scm_must_free} did not unregister the memory it was about to
244free. The usual way to unregister memory was to return its size from
245a smob free function.
246
247This disconnectedness of the actual freeing of memory and reporting
248this to the GC proved to be bad in practice. It was easy to make
249mistakes and report the wrong size because allocating and freeing was
250not done with symmetric code, and because it is cumbersome to compute
251the total size of nested data structures that were freed with multiple
252calls to @code{scm_must_free}. Additionally, there was no equivalent
253to @code{scm_malloc}, and it was tempting to just use
254@code{scm_must_malloc} and never to tell the GC that the memory has
255been freed.
256
257The effect was that the internal statistics kept by the GC drifted out
258of sync with reality and could even overflow in long running programs.
259When this happened, the result was a dramatic increase in (senseless)
260GC activity which would effectively stop the program dead.
261
262@findex scm_done_malloc
263@findex scm_done_free
264The functions @code{scm_done_malloc} and @code{scm_done_free} were
265introduced to help restore balance to the force, but existing bugs did
266not magically disappear, of course.
267
268Therefore we decided to force everybody to review their code by
269deprecating the existing functions and introducing new ones in their
270place that are hopefully easier to use correctly.
271
272For every use of @code{scm_must_malloc} you need to decide whether to
273use @code{scm_malloc} or @code{scm_gc_malloc} in its place. When the
274memory block is not part of a smob or some other Scheme object whose
275lifetime is ultimately managed by the garbage collector, use
276@code{scm_malloc} and @code{free}. When it is part of a smob, use
277@code{scm_gc_malloc} and change the smob free function to use
278@code{scm_gc_free} instead of @code{scm_must_free} or @code{free} and
279make it return zero.
280
281The important thing is to always pair @code{scm_malloc} with
282@code{free}; and to always pair @code{scm_gc_malloc} with
283@code{scm_gc_free}.
284
285The same reasoning applies to @code{scm_must_realloc} and
286@code{scm_realloc} versus @code{scm_gc_realloc}.
287
288
289@node Weak References
290@subsection Weak References
291
292[FIXME: This chapter is based on Mikael Djurfeldt's answer to a
293question by Michael Livshin. Any mistakes are not theirs, of course. ]
294
295Weak references let you attach bookkeeping information to data so that
296the additional information automatically disappears when the original
297data is no longer in use and gets garbage collected. In a weak key hash,
298the hash entry for that key disappears as soon as the key is no longer
299referenced from anywhere else. For weak value hashes, the same happens
300as soon as the value is no longer in use. Entries in a doubly weak hash
301disappear when either the key or the value are not used anywhere else
302anymore.
303
304Object properties offer the same kind of functionality as weak key
305hashes in many situations. (@pxref{Object Properties})
306
307Here's an example (a little bit strained perhaps, but one of the
308examples is actually used in Guile):
309
310Assume that you're implementing a debugging system where you want to
311associate information about filename and position of source code
312expressions with the expressions themselves.
313
314Hashtables can be used for that, but if you use ordinary hash tables
315it will be impossible for the scheme interpreter to "forget" old
316source when, for example, a file is reloaded.
317
318To implement the mapping from source code expressions to positional
319information it is necessary to use weak-key tables since we don't want
320the expressions to be remembered just because they are in our table.
321
322To implement a mapping from source file line numbers to source code
323expressions you would use a weak-value table.
324
325To implement a mapping from source code expressions to the procedures
326they constitute a doubly-weak table has to be used.
327
328@menu
cdf1ad3b 329* Weak hash tables::
07d83abe
MV
330* Weak vectors::
331@end menu
332
333
cdf1ad3b
MV
334@node Weak hash tables
335@subsubsection Weak hash tables
07d83abe
MV
336
337@deffn {Scheme Procedure} make-weak-key-hash-table size
338@deffnx {Scheme Procedure} make-weak-value-hash-table size
339@deffnx {Scheme Procedure} make-doubly-weak-hash-table size
340@deffnx {C Function} scm_make_weak_key_hash_table (size)
341@deffnx {C Function} scm_make_weak_value_hash_table (size)
342@deffnx {C Function} scm_make_doubly_weak_hash_table (size)
343Return a weak hash table with @var{size} buckets. As with any
344hash table, choosing a good size for the table requires some
345caution.
346
347You can modify weak hash tables in exactly the same way you
348would modify regular hash tables. (@pxref{Hash Tables})
349@end deffn
350
351@deffn {Scheme Procedure} weak-key-hash-table? obj
352@deffnx {Scheme Procedure} weak-value-hash-table? obj
353@deffnx {Scheme Procedure} doubly-weak-hash-table? obj
354@deffnx {C Function} scm_weak_key_hash_table_p (obj)
355@deffnx {C Function} scm_weak_value_hash_table_p (obj)
356@deffnx {C Function} scm_doubly_weak_hash_table_p (obj)
357Return @code{#t} if @var{obj} is the specified weak hash
358table. Note that a doubly weak hash table is neither a weak key
359nor a weak value hash table.
360@end deffn
361
07d83abe
MV
362@node Weak vectors
363@subsubsection Weak vectors
364
365Weak vectors are mainly useful in Guile's implementation of weak hash
366tables.
367
368@deffn {Scheme Procedure} make-weak-vector size [fill]
369@deffnx {C Function} scm_make_weak_vector (size, fill)
370Return a weak vector with @var{size} elements. If the optional
371argument @var{fill} is given, all entries in the vector will be
372set to @var{fill}. The default value for @var{fill} is the
373empty list.
374@end deffn
375
376@deffn {Scheme Procedure} weak-vector . l
377@deffnx {Scheme Procedure} list->weak-vector l
378@deffnx {C Function} scm_weak_vector (l)
379Construct a weak vector from a list: @code{weak-vector} uses
380the list of its arguments while @code{list->weak-vector} uses
381its only argument @var{l} (a list) to construct a weak vector
382the same way @code{list->vector} would.
383@end deffn
384
385@deffn {Scheme Procedure} weak-vector? obj
386@deffnx {C Function} scm_weak_vector_p (obj)
387Return @code{#t} if @var{obj} is a weak vector. Note that all
388weak hashes are also weak vectors.
389@end deffn
390
391
392@node Guardians
393@subsection Guardians
394
930888e8
MV
395Guardians provide a way to be notified about objects that would
396otherwise be collected as garbage. Guarding them prevents the objects
397from being collected and cleanup actions can be performed on them, for
398example.
07d83abe 399
930888e8
MV
400See R. Kent Dybvig, Carl Bruggeman, and David Eby (1993) "Guardians in
401a Generation-Based Garbage Collector". ACM SIGPLAN Conference on
402Programming Language Design and Implementation, June 1993.
07d83abe 403
930888e8
MV
404@deffn {Scheme Procedure} make-guardian
405@deffnx {C Function} scm_make_guardian ()
406Create a new guardian. A guardian protects a set of objects from
407garbage collection, allowing a program to apply cleanup or other
408actions.
07d83abe 409
930888e8
MV
410@code{make-guardian} returns a procedure representing the guardian.
411Calling the guardian procedure with an argument adds the argument to
412the guardian's set of protected objects. Calling the guardian
413procedure without an argument returns one of the protected objects
414which are ready for garbage collection, or @code{#f} if no such object
415is available. Objects which are returned in this way are removed from
416the guardian.
07d83abe 417
930888e8
MV
418You can put a single object into a guardian more than once and you can
419put a single object into more than one guardian. The object will then
420be returned multiple times by the guardian procedures.
421
422An object is eligible to be returned from a guardian when it is no
423longer referenced from outside any guardian.
424
425There is no guarantee about the order in which objects are returned
426from a guardian. If you want to impose an order on finalization
427actions, for example, you can do that by keeping objects alive in some
428global data structure until they are no longer needed for finalizing
429other objects.
430
431Being an element in a weak vector, a key in a hash table with weak
432keys, or a value in a hash table with weak value does not prevent an
433object from being returned by a guardian. But as long as an object
434can be returned from a guardian it will not be removed from such a
435weak vector or hash table. In other words, a weak link does not
436prevent an object from being considered collectable, but being inside
437a guardian prevents a weak link from being broken.
438
439A key in a weak key hash table can be though of as having a strong
440reference to its associated value as long as the key is accessible.
441Consequently, when the key only accessible from within a guardian, the
442reference from the key to the value is also considered to be coming
443from within a guardian. Thus, if there is no other reference to the
444value, it is eligible to be returned from a guardian.
07d83abe
MV
445@end deffn
446
447
448@page
449@node Objects
450@section Objects
451
452@deffn {Scheme Procedure} entity? obj
453@deffnx {C Function} scm_entity_p (obj)
454Return @code{#t} if @var{obj} is an entity.
455@end deffn
456
457@deffn {Scheme Procedure} operator? obj
458@deffnx {C Function} scm_operator_p (obj)
459Return @code{#t} if @var{obj} is an operator.
460@end deffn
461
462@deffn {Scheme Procedure} set-object-procedure! obj proc
463@deffnx {C Function} scm_set_object_procedure_x (obj, proc)
464Set the object procedure of @var{obj} to @var{proc}.
465@var{obj} must be either an entity or an operator.
466@end deffn
467
468@deffn {Scheme Procedure} make-class-object metaclass layout
469@deffnx {C Function} scm_make_class_object (metaclass, layout)
470Create a new class object of class @var{metaclass}, with the
471slot layout specified by @var{layout}.
472@end deffn
473
474@deffn {Scheme Procedure} make-subclass-object class layout
475@deffnx {C Function} scm_make_subclass_object (class, layout)
476Create a subclass object of @var{class}, with the slot layout
477specified by @var{layout}.
478@end deffn
479
480
481@c Local Variables:
482@c TeX-master: "guile.texi"
483@c End: