summaryrefslogtreecommitdiff
path: root/doc/ref/libguile-concepts.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ref/libguile-concepts.texi')
-rw-r--r--doc/ref/libguile-concepts.texi78
1 files changed, 37 insertions, 41 deletions
diff --git a/doc/ref/libguile-concepts.texi b/doc/ref/libguile-concepts.texi
index 0103ad173..9e2eb7503 100644
--- a/doc/ref/libguile-concepts.texi
+++ b/doc/ref/libguile-concepts.texi
@@ -1,7 +1,7 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2010,
-@c 2011, 2013 Free Software Foundation, Inc.
+@c 2011, 2013, 2014 Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@node General Libguile Concepts
@@ -191,38 +191,34 @@ periodically free all blocks that have been allocated but are not used
by any active Scheme values. This activity is called @dfn{garbage
collection}.
-It is easy for Guile to remember all blocks of memory that it has
-allocated for use by Scheme values, but you need to help it with finding
-all Scheme values that are in use by C code.
-
-You do this when writing a SMOB mark function, for example
-(@pxref{Garbage Collecting Smobs}). By calling this function, the
-garbage collector learns about all references that your SMOB has to
-other @code{SCM} values.
-
-Other references to @code{SCM} objects, such as global variables of type
-@code{SCM} or other random data structures in the heap that contain
-fields of type @code{SCM}, can be made visible to the garbage collector
-by calling the functions @code{scm_gc_protect} or
-@code{scm_permanent_object}. You normally use these functions for long
-lived objects such as a hash table that is stored in a global variable.
-For temporary references in local variables or function arguments, using
-these functions would be too expensive.
-
-These references are handled differently: Local variables (and function
-arguments) of type @code{SCM} are automatically visible to the garbage
-collector. This works because the collector scans the stack for
-potential references to @code{SCM} objects and considers all referenced
-objects to be alive. The scanning considers each and every word of the
-stack, regardless of what it is actually used for, and then decides
-whether it could possibly be a reference to a @code{SCM} object. Thus,
-the scanning is guaranteed to find all actual references, but it might
-also find words that only accidentally look like references. These
-`false positives' might keep @code{SCM} objects alive that would
-otherwise be considered dead. While this might waste memory, keeping an
-object around longer than it strictly needs to is harmless. This is why
-this technique is called ``conservative garbage collection''. In
-practice, the wasted memory seems to be no problem.
+Guile's garbage collector will automatically discover references to
+@code{SCM} objects that originate in global variables, static data
+sections, function arguments or local variables on the C and Scheme
+stacks, and values in machine registers. Other references to @code{SCM}
+objects, such as those in other random data structures in the C heap
+that contain fields of type @code{SCM}, can be made visible to the
+garbage collector by calling the functions @code{scm_gc_protect} or
+@code{scm_permanent_object}. Collectively, these values form the ``root
+set'' of garbage collection; any value on the heap that is referenced
+directly or indirectly by a member of the root set is preserved, and all
+other objects are eligible for reclamation.
+
+The Scheme stack and heap are scanned precisely; that is to say, Guile
+knows about all inter-object pointers on the Scheme stack and heap.
+This is not the case, unfortunately, for pointers on the C stack and
+static data segment. For this reason we have to scan the C stack and
+static data segment @dfn{conservatively}; any value that looks like a
+pointer to a GC-managed object is treated as such, whether it actually
+is a reference or not. Thus, scanning the C stack and static data
+segment is guaranteed to find all actual references, but it might also
+find words that only accidentally look like references. These ``false
+positives'' might keep @code{SCM} objects alive that would otherwise be
+considered dead. While this might waste memory, keeping an object
+around longer than it strictly needs to is harmless. This is why this
+technique is called ``conservative garbage collection''. In practice,
+the wasted memory seems to be no problem, as the static C root set is
+almost always finite and small, given that the Scheme stack is separate
+from the C stack.
The stack of every thread is scanned in this way and the registers of
the CPU and all other memory locations where local variables or function
@@ -245,17 +241,17 @@ wanted.
There are situations, however, where a @code{SCM} object needs to be
around longer than its reference from a local variable or function
parameter. This happens, for example, when you retrieve some pointer
-from a smob and work with that pointer directly. The reference to the
-@code{SCM} smob object might be dead after the pointer has been
-retrieved, but the pointer itself (and the memory pointed to) is still
-in use and thus the smob object must be protected. The compiler does
-not know about this connection and might overwrite the @code{SCM}
-reference too early.
+from a foreign object and work with that pointer directly. The
+reference to the @code{SCM} foreign object might be dead after the
+pointer has been retrieved, but the pointer itself (and the memory
+pointed to) is still in use and thus the foreign object must be
+protected. The compiler does not know about this connection and might
+overwrite the @code{SCM} reference too early.
To get around this problem, you can use @code{scm_remember_upto_here_1}
and its cousins. It will keep the compiler from overwriting the
-reference. For a typical example of its use, see @ref{Remembering
-During Operations}.
+reference. @xref{Foreign Object Memory Management}.
+
@node Control Flow
@subsection Control Flow