From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Aaron VanDevender Newsgroups: gmane.lisp.guile.user Subject: PATCH: docs GC protection functions Date: Thu, 4 Sep 2003 20:48:58 -0400 Sender: guile-user-bounces+guile-user=m.gmane.org@gnu.org Message-ID: <20030904204858.H24327@netdot.net> NNTP-Posting-Host: deer.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: sea.gmane.org 1062748312 27456 80.91.224.253 (5 Sep 2003 07:51:52 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Fri, 5 Sep 2003 07:51:52 +0000 (UTC) Original-X-From: guile-user-bounces+guile-user=m.gmane.org@gnu.org Fri Sep 05 09:51:51 2003 Return-path: Original-Received: from monty-python.gnu.org ([199.232.76.173]) by deer.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 19vBNm-00012S-00 for ; Fri, 05 Sep 2003 09:51:50 +0200 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.22) id 19vBMM-0002ve-1a for guile-user@m.gmane.org; Fri, 05 Sep 2003 03:50:22 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.22) id 19v4mv-00053A-MV for guile-user@gnu.org; Thu, 04 Sep 2003 20:49:21 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.22) id 19v4mp-0004yz-N7 for guile-user@gnu.org; Thu, 04 Sep 2003 20:49:18 -0400 Original-Received: from [18.228.0.154] (helo=roxanne.bos.netdot.net) by monty-python.gnu.org with esmtp (Exim 4.22) id 19v4mX-0004rP-8U for guile-user@gnu.org; Thu, 04 Sep 2003 20:48:57 -0400 Original-Received: (from sig@localhost) by roxanne.bos.netdot.net (8.11.6/8.11.6) id h850mw106190 for guile-user@gnu.org; Thu, 4 Sep 2003 20:48:58 -0400 Original-To: guile-user@gnu.org Content-Disposition: inline User-Agent: Mutt/1.2.5.1i X-BeenThere: guile-user@gnu.org X-Mailman-Version: 2.1.2 Precedence: list List-Id: General Guile related discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guile-user-bounces+guile-user=m.gmane.org@gnu.org Xref: main.gmane.org gmane.lisp.guile.user:2229 X-Report-Spam: http://spam.gmane.org/gmane.lisp.guile.user:2229 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