PATCH: docs GC protection functions

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.
 
+@node Protecting Smobs from Garbage Collection
+@subsection Protecting Smobs from Garbage Collection
 
-@node 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.
+
+@deftypefn {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.
+@end deftypefn
+
+@deftypefn {C Function} SCM scm_gc_unprotect_object (SCM @var{obj})
+Unprotects an object from the garbage collector which was protected by
+@code{scm_gc_unprotect_object}. Returns the SCM object it was passed.
+@end deftypefn
+
+@deftypefn {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.
+@end deftypefn
+
+@node A Common Mistake In Allocating Smobs
 @subsection A Common Mistake In Allocating Smobs
 
 When constructing new objects, you must be careful that the garbage


_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: PATCH: docs GC protection functions

[Kevin Ryde]

Aaron VanDevender <sig@netdot.net> writes:
>
> +* Protecting Smobs from Garbage Collection::    

I don't think this applies specifically smobs, but to all objects.
And smobs would protect their internals with the mark function rather
than scm_gc_protect_object I think.

Somewhere under the "Memory Management" node looks like a better spot
to me (maybe that's where you had it before).

> +@deftypefn {C Function} SCM scm_gc_protect_object (SCM @var{obj})

Could probably put scm_gc_unprotect_object together here
(ie. @deftypefnx).

> +@deftypefn {C Function} SCM scm_permanent_object (SCM @var{obj})
> +Similar to @code{scm_gc_protect_object}

I'd be inclined to give this an independent description, rather than
referring to another function.

Could mention the typical use of scm_permanent_object in creating
globals for use by C code (either constants like symbols or strings,
or variables like hash tables or whatever).


_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user

Re: PATCH: docs GC protection functions

[Neil Jerram]

>>>>> "Aaron" == Aaron VanDevender <sig@netdot.net> writes:

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

    Aaron> Would anyone care to commit it (or comment on it)?

Don't worry; it won't be lost.  I'm a bit busy but will take a look in the next few days,
if no one else does first.

    Aaron> I submitted something earlier as a patch to
    Aaron> scheme-memory.texi, but I think it fits better in
    Aaron> data-rep.texi.

So, just to be clear, this patch replaces the scheme-memory.texi one,
right?

        Neil



_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-user