guile/doc/ref/scheme-memory.texi

@page
@node Memory Management
@chapter Memory Management and Garbage Collection

@menu
* Garbage Collection::
* Memory Blocks::
* Weak References::
* Guardians::
@end menu


@node Garbage Collection
@section Garbage Collection

@deffn {Scheme Procedure} gc
@deffnx {C Function} scm_gc ()
Scans all of SCM objects and reclaims for further use those that are
no longer accessible.  You normally don't need to call this function
explicitely.  It is called automatically when appropriate.
@end deffn

@deffn {Scheme Procedure} gc-stats
@deffnx {C Function} scm_gc_stats ()
Return an association list of statistics about Guile's current
use of storage.
@end deffn

@node Memory Blocks
@section Memory Blocks

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}.

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}.

There is also @code{scm_gc_realloc} and @code{scm_realloc}, to be used
in place of @code{realloc} when appropriate.

For really specialized needs, take at look at
@code{scm_gc_register_collectable_memory} and
@code{scm_gc_unregister_collectable_memory}.

@deftypefn {C Function} void *scm_malloc (size_t @var{size})
Allocate @var{size} bytes of memory and return a pointer to it.  When
@var{size} is 0, return @code{NULL}.  When not enough memory is
available, signal an error.  This function runs the GC to free up some
memory when it deems it appropriate.

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.
@end deftypefn

@deftypefn {C Function} void *scm_realloc (void *@var{mem}, size_t @var{new_size})
Change the size of the memory block at @var{mem} to @var{new_size} and
return its new location.  When @var{new_size} is 0, this is the same
as calling @code{free} on @var{mem} and @code{NULL} is returned.  When
@var{mem} is @code{NULL}, this function behaves like @code{scm_malloc}
and allocates a new block of size @var{new_size}.

When not enough memory is available, signal an error.  This function
runs the GC to free up some memory when it deems it appropriate.
@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
part of a GC controlled object and when the GC happens to free that
object, @var{size} bytes will be freed along with it.  The GC will
@strong{not} free the memory itself, it will just know that so-and-so
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.
@end deftypefn

@deftypefn {C Function} void scm_gc_unregister_collectable_memory (void *@var{mem}, size_t @var{size})
Informs the GC that the memory at @var{mem} of size @var{size} is no
longer associated with a GC controlled object.  You must take care to
match up every call to @code{scm_gc_register_collectable_memory} with
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});
Like @code{scm_malloc} or @code{scm_realloc}, 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.
@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.
@end deftypefn


@subsection Upgrading from scm_must_malloc et al

Version 1.6 of Guile and earlier did not have the functions from the
previous section.  In their place, it had the functions
@code{scm_must_malloc}, @code{scm_must_realloc} and
@code{scm_must_free}.  This section explains why we want you to stop
using them, and how to do this.

The functions @code{scm_must_malloc} and @code{scm_must_realloc}
behaved like @code{scm_gc_malloc} and @code{scm_gc_realloc} do now,
respectively.  They would inform the GC about the newly allocated
memory via the internal equivalent of
@code{scm_gc_register_collectable_memory}.  However,
@code{scm_must_free} did not unregister the memory it was about to
free.  The usual way to unregister memory was to return its size from
a smob free function.

This disconnectedness of the actual freeing of memory and reporting
this to the GC proved to be bad in practice.  It was easy to make
mistakes and report the wrong size because allocating and freeing was
not done with symmetric code, and because it is cumbersome to compute
the total size of nested data structures that were freed with multiple
calls to @code{scm_must_free}.  Additionally, there was no equivalent
to @code{scm_malloc}, and it was tempting to just use
@code{scm_must_malloc} and never to tell the GC that the memory has
been freed.

The effect was that the internal statistics kept by the GC drifted out
of sync with reality and could even overflow in long running programs.
When this happened, the result was a dramatic increase in (senseless)
GC activity which would effectively stop the program dead.

The functions @code{scm_done_malloc} and @code{scm_done_free} were
introduced to help restore balance to the force, but existing bugs did
not magically disappear, of course.

Therefore we decided to force everybody to review their code by
deprecating the existing functions and introducing new ones in their
place that are hopefully easier to use correctly.

For every use of @code{scm_must_malloc} you need to decide whether to
use @code{scm_malloc} or @code{scm_gc_malloc} in its place.  When the
memory block is not part of a smob or some other Scheme object whose
lifetime is ultimately managed by the garbage collector, use
@code{scm_malloc} and @code{free}.  When it is part of a smob, use
@code{scm_gc_malloc} and change the smob free function to use
@code{scm_gc_free} instead of @code{scm_must_free} or @code{free} and
make it return zero.

The important thing is to always pair @code{scm_malloc} with
@code{free}; and to always pair @code{scm_gc_malloc} with
@code{scm_gc_free}.

The same reasoning applies to @code{scm_must_realloc} and
@code{scm_realloc} versus @code{scm_gc_realloc}.

@node Weak References
@section Weak References

[FIXME: This chapter is based on Mikael Djurfeldt's answer to a
question by Michael Livshin. Any mistakes are not theirs, of course. ]

Weak references let you attach bookkeeping information to data so that
the additional information automatically disappears when the original
data is no longer in use and gets garbage collected. In a weak key hash,
the hash entry for that key disappears as soon as the key is no longer
referenced from anywhere else. For weak value hashes, the same happens
as soon as the value is no longer in use. Entries in a doubly weak hash
disappear when either the key or the value are not used anywhere else
anymore.

Property lists offer the same kind of functionality as weak key hashes
in many situations. (@pxref{Property Lists})

Here's an example (a little bit strained perhaps, but one of the
examples is actually used in Guile):

Assume that you're implementing a debugging system where you want to
associate information about filename and position of source code
expressions with the expressions themselves.

Hashtables can be used for that, but if you use ordinary hash tables
it will be impossible for the scheme interpreter to "forget" old
source when, for example, a file is reloaded.

To implement the mapping from source code expressions to positional
information it is necessary to use weak-key tables since we don't want
the expressions to be remembered just because they are in our table.

To implement a mapping from source file line numbers to source code
expressions you would use a weak-value table.

To implement a mapping from source code expressions to the procedures
they constitute a doubly-weak table has to be used.

@menu
* Weak key hashes::
* Weak vectors::
@end menu


@node Weak key hashes
@subsection Weak key hashes

@deffn {Scheme Procedure} make-weak-key-hash-table size
@deffnx {Scheme Procedure} make-weak-value-hash-table size
@deffnx {Scheme Procedure} make-doubly-weak-hash-table size
@deffnx {C Function} scm_make_weak_key_hash_table (size)
@deffnx {C Function} scm_make_weak_value_hash_table (size)
@deffnx {C Function} scm_make_doubly_weak_hash_table (size)
Return a weak hash table with @var{size} buckets. As with any
hash table, choosing a good size for the table requires some
caution.

You can modify weak hash tables in exactly the same way you
would modify regular hash tables. (@pxref{Hash Tables})
@end deffn

@deffn {Scheme Procedure} weak-key-hash-table? obj
@deffnx {Scheme Procedure} weak-value-hash-table? obj
@deffnx {Scheme Procedure} doubly-weak-hash-table? obj
@deffnx {C Function} scm_weak_key_hash_table_p (obj)
@deffnx {C Function} scm_weak_value_hash_table_p (obj)
@deffnx {C Function} scm_doubly_weak_hash_table_p (obj)
Return @code{#t} if @var{obj} is the specified weak hash
table. Note that a doubly weak hash table is neither a weak key
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
@subsection Weak vectors

Weak vectors are mainly useful in Guile's implementation of weak hash
tables.

@deffn {Scheme Procedure} make-weak-vector size [fill]
@deffnx {C Function} scm_make_weak_vector (size, fill)
Return a weak vector with @var{size} elements. If the optional
argument @var{fill} is given, all entries in the vector will be
set to @var{fill}. The default value for @var{fill} is the
empty list.
@end deffn

@deffn {Scheme Procedure} weak-vector . l
@deffnx {Scheme Procedure} list->weak-vector l
@deffnx {C Function} scm_weak_vector (l)
Construct a weak vector from a list: @code{weak-vector} uses
the list of its arguments while @code{list->weak-vector} uses
its only argument @var{l} (a list) to construct a weak vector
the same way @code{list->vector} would.
@end deffn

@deffn {Scheme Procedure} weak-vector? obj
@deffnx {C Function} scm_weak_vector_p (obj)
Return @code{#t} if @var{obj} is a weak vector. Note that all
weak hashes are also weak vectors.
@end deffn


@node Guardians
@section 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).

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} 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

@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}.
@end deffn


@page
@node Objects
@chapter Objects

@deffn {Scheme Procedure} entity? obj
@deffnx {C Function} scm_entity_p (obj)
Return @code{#t} if @var{obj} is an entity.
@end deffn

@deffn {Scheme Procedure} operator? obj
@deffnx {C Function} scm_operator_p (obj)
Return @code{#t} if @var{obj} is an operator.
@end deffn

@deffn {Scheme Procedure} set-object-procedure! obj proc
@deffnx {C Function} scm_set_object_procedure_x (obj, proc)
Set the object procedure of @var{obj} to @var{proc}.
@var{obj} must be either an entity or an operator.
@end deffn

@deffn {Scheme Procedure} make-class-object metaclass layout
@deffnx {C Function} scm_make_class_object (metaclass, layout)
Create a new class object of class @var{metaclass}, with the
slot layout specified by @var{layout}.
@end deffn

@deffn {Scheme Procedure} make-subclass-object class layout
@deffnx {C Function} scm_make_subclass_object (class, layout)
Create a subclass object of @var{class}, with the slot layout
specified by @var{layout}.
@end deffn


@c Local Variables:
@c TeX-master: "guile.texi"
@c End: