/[guile]/guile/guile-core/doc/ref/scheme-memory.texi
ViewVC logotype

Diff of /guile/guile-core/doc/ref/scheme-memory.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.15 by kryde, Fri Aug 8 22:08:25 2003 UTC revision 1.16 by mvo, Mon Oct 6 19:24:15 2003 UTC
# Line 6  Guile uses a @emph{garbage collector} to Line 6  Guile uses a @emph{garbage collector} to
6  This means that the memory used to store a Scheme string, say, is  This means that the memory used to store a Scheme string, say, is
7  automatically reclaimed when no one is using this string any longer.  automatically reclaimed when no one is using this string any longer.
8  This can work because Guile knows enough about its objects at run-time  This can work because Guile knows enough about its objects at run-time
9  to be able to trace all references between them.  Thus, it can find  to be able to trace all references between them.  Thus, it can find all
10  all 'live' objects (objects that are still in use) by starting from a  'live' objects (objects that are still in use) by starting from a known
11  known set of 'root' objects and following the links that these objects  set of 'root' objects and following the links that these objects have to
12  have to other objects, and so on.  The objects that are not reached by  other objects, and so on.  The objects that are not reached by this
13  this recursive process can be considered 'dead' and their memory can  recursive process can be considered 'dead' and their memory can be
14  be  reused for new objects.  reused for new objects.
   
 When you are programming in Scheme, you don't need to worry about the  
 garbage collector.  When programming in C, there are a few rules that  
 you must follow so that the garbage collector can do its job.  
15    
16  @menu  @menu
17  * Garbage Collection::  * Garbage Collection::
# Line 28  you must follow so that the garbage coll Line 24  you must follow so that the garbage coll
24  @node Garbage Collection  @node Garbage Collection
25  @section Garbage Collection  @section Garbage Collection
26    
27    The general process of collecting dead objects outlined above relies on
28    the fact that the garbage collector is able to find all references to
29    SCM objects that might be used by the program in the future.  When you
30    are programming in Scheme, you don't need to worry about this: The
31    collector is automatically aware of all objects in use by Scheme code.
32    
33    When programming in C, you must help the garbage collector a bit so that
34    it can find all objects that are accessible from C.  You do this when
35    writing a SMOB mark function, for example.  By calling this function,
36    the garbage collector learns about all references that your SMOB has to
37    other SCM objects.
38    
39    Other references to SCM objects, such as global variables of type SCM or
40    other random data structures in the heap that contain fields of type
41    SCM, can be made visible to the garbage collector by calling the
42    functions @code{scm_gc_protect} or @code{scm_permanent_object}.  You
43    normally use these funtions for long lived objects such as a hash table
44    that is stored in a global variable.  For temporary references in local
45    variables or function arguments, using these functions would be too
46    expensive.
47    
48    These references are handled differently: Local variables (and function
49    arguments) of type SCM are automatically visible to the garbage
50    collector.  This works because the collector scans the stack for
51    potential references to SCM objects and considers all referenced objects
52    to be alive.  The scanning considers each and every word of the stack,
53    regardless of what it is actually used for, and then decides whether it
54    could possible be a reference to a SCM object.  Thus, the scanning is
55    guaranteed to find all actual references, but it might also find words
56    that only accidentally look like references.  These `false positives'
57    might keep SCM objects alive that would otherwise be considered dead.
58    While this might waste memory, keeping an object around longer than it
59    strictly needs to is harmless.  This is why this technique is called
60    ``conservative garbage collection''.  In practice, the wasted memory
61    seems to be no problem.
62    
63    The stack of every thread is scanned in this way and the registers of
64    the CPU and all other memory locations where local variables or function
65    parameters might show up are included in this scan as well.
66    
67    The consequence of the conservative scanning is that you can just
68    declare local variables and function parameters of type SCM and be sure
69    that the garbage collector will not free the corresponding objects.
70    
71    However, a local variable or function parameter is only protected as
72    long as it is really on the stack (or in some register).  As an
73    optimization, the C compiler might reuse its location for some other
74    value and the SCM object would no longer be protected.  Normally, this
75    leads to exactly the right behabvior: the compiler will only overwrite a
76    reference when it is no longer needed and thus the object becomes
77    unprotected precisely when the reference disappears, just as wanted.
78    
79    There are situations, however, where a SCM object needs to be around
80    longer than its reference from a local variable or function parameter.
81    This happens, for example, when you retrieve the array of characters
82    from a Scheme string and work on that array directly.  The reference to
83    the SCM string object might be dead after the character array has been
84    retrieved, but the array itself is still in use and thus the string
85    object must be protected.  The compiler does not know about this
86    connection and might overwrite the SCM reference too early.
87    
88    To get around this problem, you can use @code{scm_remember_upto_here_1}
89    and its cousins.  It will keep the compiler from overwriting the
90    reference.  For an example of its use, see @ref{Remembering During
91    Operations}.
92    
93  @deffn {Scheme Procedure} gc  @deffn {Scheme Procedure} gc
94  @deffnx {C Function} scm_gc ()  @deffnx {C Function} scm_gc ()
95  Scans all of SCM objects and reclaims for further use those that are  Scans all of SCM objects and reclaims for further use those that are
# Line 35  no longer accessible.  You normally don' Line 97  no longer accessible.  You normally don'
97  explicitly.  It is called automatically when appropriate.  explicitly.  It is called automatically when appropriate.
98  @end deffn  @end deffn
99    
100    @deftypefn {C Function} SCM scm_gc_protect_object (SCM @var{obj})
101    Protects @var{obj} from being freed by the garbage collector, when it
102    otherwise might be.  When you are done with the object, call
103    @code{scm_gc_unprotect_object} on the object. Calls to
104    @code{scm_gc_protect}/@code{scm_gc_unprotect_object} can be nested, and
105    the object remains protected until it has been unprotected as many times
106    as it was protected. It is an error to unprotect an object more times
107    than it has been protected. Returns the SCM object it was passed.
108    @end deftypefn
109    
110    @deftypefn {C Function} SCM scm_gc_unprotect_object (SCM @var{obj})
111    
112    Unprotects an object from the garbage collector which was protected by
113    @code{scm_gc_unprotect_object}. Returns the SCM object it was passed.
114    @end deftypefn
115    
116    @deftypefn {C Function} SCM scm_permanent_object (SCM @var{obj})
117    
118    Similar to @code{scm_gc_protect_object} in that it causes the
119    collector to always mark the object, except that it should not be
120    nested (only call @code{scm_permanent_object} on an object once), and
121    it has no corresponding unpermanent function. Once an object is
122    declared permanent, it will never be freed. Returns the SCM object it
123    was passed.
124    @end deftypefn
125    
126    @c  NOTE: The varargs scm_remember_upto_here is deliberately not
127    @c  documented, because we don't think it can be implemented as a nice
128    @c  inline compiler directive or asm block.  New _3, _4 or whatever
129    @c  forms could certainly be added though, if needed.
130    
131    @deftypefn {C Macro} void scm_remember_upto_here_1 (SCM obj)
132    @deftypefnx {C Macro} void scm_remember_upto_here_2 (SCM obj1, SCM obj2)
133    Create a reference to the given object or objects, so they're certain
134    to be present on the stack or in a register and hence will not be
135    freed by the garbage collector before this point.
136    
137    Note that these functions can only be applied to ordinary C local
138    variables (ie.@: ``automatics'').  Objects held in global or static
139    variables or some malloced block or the like cannot be protected with
140    this mechanism.
141    @end deftypefn
142    
143  @deffn {Scheme Procedure} gc-stats  @deffn {Scheme Procedure} gc-stats
144  @deffnx {C Function} scm_gc_stats ()  @deffnx {C Function} scm_gc_stats ()
145  Return an association list of statistics about Guile's current  Return an association list of statistics about Guile's current

Legend:
Removed from v.1.15  
changed lines
  Added in v.1.16

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26