diff options
author | Marius Vollmer <mvo@zagadka.de> | 2002-02-19 22:41:18 +0000 |
---|---|---|
committer | Marius Vollmer <mvo@zagadka.de> | 2002-02-19 22:41:18 +0000 |
commit | 0deb6826b97203d929c79729a70809fc67b2cd74 (patch) | |
tree | 038ad98730f3f5a66f6dc6762dd804b7360b4c84 /doc/ref/scheme-memory.texi | |
parent | 8121c27d3e84b1bd3da4a8f285d19190a50b8e98 (diff) | |
download | guile-0deb6826b97203d929c79729a70809fc67b2cd74.tar.gz |
(Memory Blocks): New section.
Diffstat (limited to 'doc/ref/scheme-memory.texi')
-rw-r--r-- | doc/ref/scheme-memory.texi | 116 |
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 |