From cd3370bac1cfd4b01dd7a9865e2ece5c2696db2b Mon Sep 17 00:00:00 2001 From: Andy Wingo Date: Thu, 12 Jan 2012 00:09:39 +0100 Subject: [PATCH] add docs for scm_gc_register_allocation * doc/ref/api-memory.texi: Update for scm_gc_register_allocation. Remove docs for scm_gc_{un,}register_collectable_memory. --- doc/ref/api-memory.texi | 52 +++++++++++++++++------------------------ 1 file changed, 22 insertions(+), 30 deletions(-) diff --git a/doc/ref/api-memory.texi b/doc/ref/api-memory.texi index 375686d98..6dca7a270 100644 --- a/doc/ref/api-memory.texi +++ b/doc/ref/api-memory.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Guile Reference Manual. -@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2010 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2010, 2012 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -163,6 +163,9 @@ between different modules. The function @code{scm_calloc} is similar to @code{scm_malloc}, but initializes the block of memory to zero as well. + +These functions will (indirectly) call +@code{scm_gc_register_allocation}. @end deftypefn @deftypefn {C Function} {void *} scm_realloc (void *@var{mem}, size_t @var{new_size}) @@ -174,6 +177,8 @@ 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. + +This function will call @code{scm_gc_register_allocation}. @end deftypefn @@ -209,39 +214,26 @@ the memory management overhead very low. However, in Guile 2.x, @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. - -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_register_allocation (size_t @var{size}) +Informs the garbage collector that @var{size} bytes have been allocated, +which the collector would otherwise not have known about. -@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. +In general, Scheme will decide to collect garbage only after some amount +of memory has been allocated. Calling this function will make the +Scheme garbage collector know about more allocation, and thus run more +often (as appropriate). -In Guile 2.x, this function has no effect. +It is especially important to call this function when large unmanaged +allocations, like images, may be freed by small Scheme allocations, like +SMOBs. @end deftypefn -@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. +@deftypefn {C Function} void scm_dynwind_free (void *mem) +Equivalent to @code{scm_dynwind_unwind_handler (free, @var{mem}, +SCM_F_WIND_EXPLICITLY)}. That is, the memory block at @var{mem} will be +freed (using @code{free} from the C library) when the current dynwind is +left. @end deftypefn @deffn {Scheme Procedure} malloc-stats @@ -272,7 +264,7 @@ 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_gc_register_allocation}. 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. -- 2.20.1