PATCH: scheme-memory.texi

[Aaron VanDevender]

This documents the scm_protect/unprotect_object and
scm_permanent_object functions. This diff is against the HEAD
branch in CVS.

cya
.sig

--- scheme-memory.texi  8 Aug 2003 22:08:25 -0000       1.15
+++ scheme-memory.texi  3 Sep 2003 16:41:12 -0000
@@ -153,12 +153,42 @@
 the memory management overhead very low.
 @end deftypefn
 
address@hidden {C Function} SCM scm_gc_protect_object (SCM @var{obj})
+Protects @var{obj} from being freed by the garbage collector, when it
+otherwise might be. Since the garbage collector traverses the stack
+looking for scheme objects to mark, if you have create a scheme object
+from C code, and there are no references to it on the stack (because
+they are all on the heap), then the garbage collector might free that
+object even though it is still in use. @code{scm_gc_protect_object}
+causes the collector to mark the object whenever it runs. When you are
+done with the object, call @code{scm_gc_unprotect_object} on the
+object. Calls to scm_gc_protect/unprotect_object can be nested, and
+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.
address@hidden deftypefn
+
address@hidden {C Function} SCM scm_gc_unprotect_object (SCM @var{obj})
+Unprotects an object from the garbage collector which was protected by
address@hidden Returns the SCM object it was passed.
address@hidden deftypefn
+
address@hidden {C Function} SCM scm_permanent_object (SCM @var{obj})
+Similar to @code{scm_gc_protect_object} in that it causes the
+collector to always mark the object, except that it should not be
+nested (only call @code{scm_permanent_object} on an object once), and
+it has no corresponding unpermanent function. Once an object is
+declared permanent, it will never be freed. Returns the SCM object it
+was passed.
address@hidden deftypefn
+
 @deffn {Scheme Procedure} malloc-stats
-Return an alist ((@var{what} . @var{n}) ...) describing number
-of malloced objects.
address@hidden is the second argument to @code{scm_gc_malloc},
address@hidden is the number of objects of that type currently
-allocated.
+Return an alist ((@var{what} . @var{n}) ...) describing number of
+malloced objects.  @var{what} is the second argument to
address@hidden, @var{n} is the number of objects of that type
+currently allocated. This function is only available if guile was
+built with @code{./configure --enable-debug-malloc}
 @end deffn