summaryrefslogtreecommitdiff
path: root/doc/ref/scheme-memory.texi
diff options
context:
space:
mode:
authorMarius Vollmer <mvo@zagadka.de>2002-02-19 22:41:18 +0000
committerMarius Vollmer <mvo@zagadka.de>2002-02-19 22:41:18 +0000
commit0deb6826b97203d929c79729a70809fc67b2cd74 (patch)
tree038ad98730f3f5a66f6dc6762dd804b7360b4c84 /doc/ref/scheme-memory.texi
parent8121c27d3e84b1bd3da4a8f285d19190a50b8e98 (diff)
downloadguile-0deb6826b97203d929c79729a70809fc67b2cd74.tar.gz
(Memory Blocks): New section.
Diffstat (limited to 'doc/ref/scheme-memory.texi')
-rw-r--r--doc/ref/scheme-memory.texi116
1 files changed, 105 insertions, 11 deletions
diff --git a/doc/ref/scheme-memory.texi b/doc/ref/scheme-memory.texi
index 30dd2e122..45f0f883b 100644
--- a/doc/ref/scheme-memory.texi
+++ b/doc/ref/scheme-memory.texi
@@ -4,6 +4,7 @@
@menu
* Garbage Collection::
+* Memory Blocks::
* Weak References::
* Guardians::
@end menu
@@ -12,13 +13,11 @@
@node Garbage Collection
@section Garbage Collection
-[FIXME: this is pasted in from Tom Lord's original guile.texi and should
-be reviewed]
-
@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.
+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
@@ -27,18 +26,113 @@ Return an association list of statistics about Guile's current
use of storage.
@end deffn
-@deffn {Scheme Procedure} object-address obj
-@deffnx {C Function} scm_object_address (obj)
-Return an integer that for the lifetime of @var{obj} is uniquely
-returned by this function for @var{obj}
-@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
@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. ]
+[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