@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
Guile uses a @emph{garbage collector} to manage most of its objects.
While the garbage collector is designed to be mostly invisible, you
-sometimes need to interact with it explicitely.
+sometimes need to interact with it explicitly.
See @ref{Garbage Collection} for a general discussion of how garbage
collection relates to using Guile from C.
the object remains protected until it has been unprotected as many times
as it was protected. It is an error to unprotect an object more times
than it has been protected. Returns the SCM object it was passed.
+
+Note that storing @var{obj} in a C global variable has the same
+effect@footnote{In Guile up to version 1.8, C global variables were not
+scanned by the garbage collector; hence, @code{scm_gc_protect_object}
+was the only way in C to prevent a Scheme object from being freed.}.
@end deftypefn
@deftypefn {C Function} SCM scm_gc_unprotect_object (SCM @var{obj})
@deffnx {C Function} scm_gc_stats ()
Return an association list of statistics about Guile's current
use of storage.
+@end deffn
+
+@deffn {Scheme Procedure} gc-live-object-stats
+@deffnx {C Function} scm_gc_live_object_stats ()
+Return an alist of statistics of the current live objects.
+@end deffn
@deftypefun void scm_gc_mark (SCM @var{x})
Mark the object @var{x}, and recurse on any objects @var{x} refers to.
@end deftypefun
-@end deffn
-
-
@node Memory Blocks
@subsection Memory Blocks
+@cindex automatically-managed memory
+@cindex GC-managed memory
+@cindex conservative garbage collection
+
In C programs, dynamic management of memory blocks is normally done
with the functions malloc, realloc, and free. Guile has additional
functions for dynamic memory allocation that are integrated into the
garbage collector and the error reporting system.
Memory blocks that are associated with Scheme objects (for example a
-smob) should be allocated and freed with @code{scm_gc_malloc} and
-@code{scm_gc_free}. The function @code{scm_gc_malloc} will either
-return a valid pointer or signal an error. It will also assume that
-the new memory can be freed by a garbage collection. The garbage
-collector uses this information to decide when to try to actually
-collect some garbage. Memory blocks allocated with
-@code{scm_gc_malloc} must be freed with @code{scm_gc_free}.
+smob) should be allocated and freed with @code{scm_gc_malloc} or
+@code{scm_gc_malloc_pointerless}. These two functions will either
+return a valid pointer or signal an error. Memory blocks allocated this
+way can be freed with @code{scm_gc_free}; however, this is not strictly
+needed: memory allocated with @code{scm_gc_malloc} or
+@code{scm_gc_malloc_pointerless} is automatically reclaimed when the
+garbage collector no longer sees any live reference to it@footnote{In
+Guile up to version 1.8, memory allocated with @code{scm_gc_malloc}
+@emph{had} to be freed with @code{scm_gc_free}.}.
+
+Memory allocated with @code{scm_gc_malloc} is scanned for live pointers.
+This means that if @code{scm_gc_malloc}-allocated memory contains a
+pointer to some other part of the memory, the garbage collector notices
+it and prevents it from being reclaimed@footnote{In Guile up to 1.8,
+memory allocated with @code{scm_gc_malloc} was @emph{not} scanned.
+Consequently, the GC had to be told explicitly about pointers to live
+objects contained in the memory block, e.g., @i{via} SMOB mark functions
+(@pxref{Smobs, @code{scm_set_smob_mark}})}. Conversely, memory
+allocated with @code{scm_gc_malloc_pointerless} is assumed to be
+``pointer-less'' and is not scanned.
For memory that is not associated with a Scheme object, you can use
@code{scm_malloc} instead of @code{malloc}. Like
@code{scm_gc_malloc}, it will either return a valid pointer or signal
an error. However, it will not assume that the new memory block can
-be freed by a garbage collection. The memory can be freed with
-@code{free}.
+be freed by a garbage collection. The memory must be explicitly freed
+with @code{free}.
There is also @code{scm_gc_realloc} and @code{scm_realloc}, to be used
-in place of @code{realloc} when appropriate, @code{scm_gc_calloc} and
-@code{scm_calloc}, to be used in place of @code{calloc} when
+in place of @code{realloc} when appropriate, and @code{scm_gc_calloc}
+and @code{scm_calloc}, to be used in place of @code{calloc} when
appropriate.
-For really specialized needs, take at look at
-@code{scm_gc_register_collectable_memory} and
-@code{scm_gc_unregister_collectable_memory}.
+The function @code{scm_dynwind_free} can be useful when memory should be
+freed with libc's @code{free} when leaving a dynwind context,
+@xref{Dynamic Wind}.
@deftypefn {C Function} {void *} scm_malloc (size_t @var{size})
@deftypefnx {C Function} {void *} scm_calloc (size_t @var{size})
The memory is allocated by the libc @code{malloc} function and can be
freed with @code{free}. There is no @code{scm_free} function to go
with @code{scm_malloc} to make it easier to pass memory back and forth
-between different modules.
+between different modules.
The function @code{scm_calloc} is similar to @code{scm_malloc}, but
initializes the block of memory to zero as well.
+@deftypefn {C Function} {void *} scm_gc_malloc (size_t @var{size}, const char *@var{what})
+@deftypefnx {C Function} {void *} scm_gc_malloc_pointerless (size_t @var{size}, const char *@var{what})
+@deftypefnx {C Function} {void *} scm_gc_realloc (void *@var{mem}, size_t @var{old_size}, size_t @var{new_size}, const char *@var{what});
+@deftypefnx {C Function} {void *} scm_gc_calloc (size_t @var{size}, const char *@var{what})
+Allocate @var{size} bytes of automatically-managed memory. The memory
+is automatically freed when no longer referenced from any live memory
+block.
+
+Memory allocated with @code{scm_gc_malloc} or @code{scm_gc_calloc} is
+scanned for pointers. Memory allocated by
+@code{scm_gc_malloc_pointerless} is not scanned.
+
+The @code{scm_gc_realloc} call preserves the ``pointerlessness'' of the
+memory area pointed to by @var{mem}. Note that you need to pass the old
+size of a reallocated memory block as well. See below for a motivation.
+@end deftypefn
+
+
+@deftypefn {C Function} void scm_gc_free (void *@var{mem}, size_t @var{size}, const char *@var{what})
+Explicitly free the memory block pointed to by @var{mem}, which was
+previously allocated by one of the above @code{scm_gc} functions.
+
+Note that you need to explicitly pass the @var{size} parameter. This
+is done since it should normally be easy to provide this parameter
+(for memory that is associated with GC controlled objects) and help keep
+the memory management overhead very low. However, in Guile 2.x,
+@var{size} is always ignored.
+@end deftypefn
+
+
@deftypefn {C Function} void scm_gc_register_collectable_memory (void *@var{mem}, size_t @var{size}, const char *@var{what})
Informs the GC that the memory at @var{mem} of size @var{size} can
potentially be freed during a GC. That is, announce that @var{mem} is
much bytes of memory are associated with GC controlled objects and the
memory system figures this into its decisions when to run a GC.
-@var{mem} does not need to come from @code{scm_malloc}. You can only
-call this function once for every memory block.
-
The @var{what} argument is used for statistical purposes. It should
describe the type of object that the memory will be used for so that
users can identify just what strange objects are eating up their
memory.
+
+In Guile 2.x, this function has no effect.
@end deftypefn
@deftypefn {C Function} void scm_gc_unregister_collectable_memory (void *@var{mem}, size_t @var{size})
a call to @code{scm_gc_unregister_collectable_memory}. If you don't do
this, the GC might have a wrong impression of what is going on and run
much less efficiently than it could.
-@end deftypefn
-@deftypefn {C Function} {void *} scm_gc_malloc (size_t @var{size}, const char *@var{what})
-@deftypefnx {C Function} {void *} scm_gc_realloc (void *@var{mem}, size_t @var{old_size}, size_t @var{new_size}, const char *@var{what});
-@deftypefnx {C Function} {void *} scm_gc_calloc (size_t @var{size}, const char *@var{what})
-Like @code{scm_malloc}, @code{scm_realloc} or @code{scm_calloc}, but
-also call @code{scm_gc_register_collectable_memory}. Note that you
-need to pass the old size of a reallocated memory block as well. See
-below for a motivation.
+In Guile 2.x, this function has no effect.
@end deftypefn
-@deftypefn {C Function} void scm_gc_free (void *@var{mem}, size_t @var{size}, const char *@var{what})
-Like @code{free}, but also call @code{scm_gc_unregister_collectable_memory}.
-
-Note that you need to explicitely pass the @var{size} parameter. This
-is done since it should normally be easy to provide this parameter
-(for memory that is associated with GC controlled objects) and this
-frees us from tracking this value in the GC itself, which will keep
-the memory management overhead very low.
+@deftypefn {C Function} void scm_frame_free (void *mem)
+Equivalent to @code{scm_frame_unwind_handler (free, @var{mem},
+SCM_F_WIND_EXPLICITLY)}. That is, the memory block at @var{mem} will
+be freed when the current frame is left.
@end deftypefn
@deffn {Scheme Procedure} malloc-stats
@var{what} is the second argument to @code{scm_gc_malloc},
@var{n} is the number of objects of that type currently
allocated.
+
+This function is only available if the @code{GUILE_DEBUG_MALLOC}
+preprocessor macro was defined when Guile was compiled.
@end deffn
they constitute a doubly-weak table has to be used.
@menu
-* Weak key hashes::
+* Weak hash tables::
* Weak vectors::
@end menu
-@node Weak key hashes
-@subsubsection Weak key hashes
+@node Weak hash tables
+@subsubsection Weak hash tables
@deffn {Scheme Procedure} make-weak-key-hash-table size
@deffnx {Scheme Procedure} make-weak-value-hash-table size
nor a weak value hash table.
@end deffn
-@deffn {Scheme Procedure} make-weak-value-hash-table k
-@end deffn
-
-@deffn {Scheme Procedure} weak-value-hash-table? x
-@end deffn
-
-@deffn {Scheme Procedure} make-doubly-weak-hash-table k
-@end deffn
-
-@deffn {Scheme Procedure} doubly-weak-hash-table? x
-@end deffn
-
-
@node Weak vectors
@subsubsection Weak vectors
@node Guardians
@subsection Guardians
-@deffn {Scheme Procedure} make-guardian [greedy?]
-@deffnx {C Function} scm_make_guardian (greedy_p)
-Create a new guardian.
-A guardian protects a set of objects from garbage collection,
-allowing a program to apply cleanup or other actions.
-
-@code{make-guardian} returns a procedure representing the guardian.
-Calling the guardian procedure with an argument adds the
-argument to the guardian's set of protected objects.
-Calling the guardian procedure without an argument returns
-one of the protected objects which are ready for garbage
-collection, or @code{#f} if no such object is available.
-Objects which are returned in this way are removed from
-the guardian.
-
-@code{make-guardian} takes one optional argument that says whether the
-new guardian should be greedy or sharing. If there is any chance
-that any object protected by the guardian may be resurrected,
-then you should make the guardian greedy (this is the default).
+Guardians provide a way to be notified about objects that would
+otherwise be collected as garbage. Guarding them prevents the objects
+from being collected and cleanup actions can be performed on them, for
+example.
-See R. Kent Dybvig, Carl Bruggeman, and David Eby (1993)
-"Guardians in a Generation-Based Garbage Collector".
-ACM SIGPLAN Conference on Programming Language Design
-and Implementation, June 1993.
+See R. Kent Dybvig, Carl Bruggeman, and David Eby (1993) "Guardians in
+a Generation-Based Garbage Collector". ACM SIGPLAN Conference on
+Programming Language Design and Implementation, June 1993.
-(the semantics are slightly different at this point, but the
-paper still (mostly) accurately describes the interface).
-@end deffn
-
-@deffn {Scheme Procedure} destroy-guardian! guardian
-@deffnx {C Function} scm_destroy_guardian_x (guardian)
-Destroys @var{guardian}, by making it impossible to put any more
-objects in it or get any objects from it. It also unguards any
-objects guarded by @var{guardian}.
-@end deffn
+@deffn {Scheme Procedure} make-guardian
+@deffnx {C Function} scm_make_guardian ()
+Create a new guardian. A guardian protects a set of objects from
+garbage collection, allowing a program to apply cleanup or other
+actions.
-@deffn {Scheme Procedure} guardian-greedy? guardian
-@deffnx {C Function} scm_guardian_greedy_p (guardian)
-Return @code{#t} if @var{guardian} is a greedy guardian, otherwise @code{#f}.
-@end deffn
+@code{make-guardian} returns a procedure representing the guardian.
+Calling the guardian procedure with an argument adds the argument to
+the guardian's set of protected objects. Calling the guardian
+procedure without an argument returns one of the protected objects
+which are ready for garbage collection, or @code{#f} if no such object
+is available. Objects which are returned in this way are removed from
+the guardian.
-@deffn {Scheme Procedure} guardian-destroyed? guardian
-@deffnx {C Function} scm_guardian_destroyed_p (guardian)
-Return @code{#t} if @var{guardian} has been destroyed, otherwise @code{#f}.
+You can put a single object into a guardian more than once and you can
+put a single object into more than one guardian. The object will then
+be returned multiple times by the guardian procedures.
+
+An object is eligible to be returned from a guardian when it is no
+longer referenced from outside any guardian.
+
+There is no guarantee about the order in which objects are returned
+from a guardian. If you want to impose an order on finalization
+actions, for example, you can do that by keeping objects alive in some
+global data structure until they are no longer needed for finalizing
+other objects.
+
+Being an element in a weak vector, a key in a hash table with weak
+keys, or a value in a hash table with weak values does not prevent an
+object from being returned by a guardian. But as long as an object
+can be returned from a guardian it will not be removed from such a
+weak vector or hash table. In other words, a weak link does not
+prevent an object from being considered collectable, but being inside
+a guardian prevents a weak link from being broken.
+
+A key in a weak key hash table can be thought of as having a strong
+reference to its associated value as long as the key is accessible.
+Consequently, when the key is only accessible from within a guardian,
+the reference from the key to the value is also considered to be
+coming from within a guardian. Thus, if there is no other reference
+to the value, it is eligible to be returned from a guardian.
@end deffn
HCoop / bpt / guile.git / blobdiff