PATCH: docs GC protection functions

[Aaron VanDevender]

I wrote some documentation for the
scm_gc_protect/unprotect_object and scm_permanent_object.

Would anyone care to commit it (or comment on it)? I submitted
something earlier as a patch to scheme-memory.texi, but I think
it fits better in data-rep.texi.

cya
.sig


--- data-rep.texi       29 Aug 2003 23:32:21 -0000      1.14
+++ data-rep.texi       5 Sep 2003 00:17:51 -0000
@@ -1397,6 +1397,7 @@
 * Creating Instances::          
 * Type checking::                
 * Garbage Collecting Smobs::    
+* Protecting Smobs from Garbage Collection::    
 * A Common Mistake In Allocating Smobs::  
 * Garbage Collecting Simple Smobs::  
 * Remembering During Operations::  
@@ -1793,8 +1794,44 @@
 very simple.  Since collections occur at unpredictable times, it is easy
 for any unusual activity to interfere with normal code.
 
address@hidden Protecting Smobs from Garbage Collection
address@hidden Protecting Smobs from Garbage Collection
 
address@hidden A Common Mistake In Allocating Smobs, Garbage Collecting Simple 
Smobs, Garbage Collecting Smobs, Defining New Types (Smobs)
+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. These functions let you tell the garbage
+collector that they should not be freed, even though they are not on
+the stack.
+
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.  @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
+
address@hidden A Common Mistake In Allocating Smobs
 @subsection A Common Mistake In Allocating Smobs
 
 When constructing new objects, you must be careful that the garbage