diff options
author | Andy Wingo <wingo@pobox.com> | 2016-06-24 08:56:21 +0200 |
---|---|---|
committer | Andy Wingo <wingo@pobox.com> | 2016-06-24 08:56:21 +0200 |
commit | f84006c5644997ce9854df9070ec2f1fb8acd420 (patch) | |
tree | 09d3d61b70687a0d695912b470a8e0fd9e686698 /doc/ref/libguile-concepts.texi | |
parent | f23dfc0fb582e2cd2894e9019b66bee53cecf2f9 (diff) | |
download | guile-f84006c5644997ce9854df9070ec2f1fb8acd420.tar.gz |
Clarify use of the term "scanning" in the manual
* doc/ref/api-memory.texi (Garbage Collection Functions):
* doc/ref/libguile-concepts.texi (Garbage Collection): Attempt to be
clear that scanning is a thing that happens in the mark phase. Fixes
#20907 I think.
Diffstat (limited to 'doc/ref/libguile-concepts.texi')
-rw-r--r-- | doc/ref/libguile-concepts.texi | 48 |
1 files changed, 32 insertions, 16 deletions
diff --git a/doc/ref/libguile-concepts.texi b/doc/ref/libguile-concepts.texi index 9785f4d6f..e93d98711 100644 --- a/doc/ref/libguile-concepts.texi +++ b/doc/ref/libguile-concepts.texi @@ -203,22 +203,38 @@ 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. +In Guile, garbage collection has two logical phases: the @dfn{mark +phase}, in which the collector discovers the set of all live objects, +and the @dfn{sweep phase}, in which the collector reclaims the resources +associated with dead objects. The mark phase pauses the program and +traces all @code{SCM} object references, starting with the root set. +The sweep phase actually runs concurrently with the main program, +incrementally reclaiming memory as needed by allocation. + +In the mark phase, the garbage collector traces the Scheme stack and +heap @dfn{precisely}. Because the Scheme stack and heap are managed by +Guile, Guile can know precisely where in those data structures it might +find references to other heap objects. This is not the case, +unfortunately, for pointers on the C stack and static data segment. +Instead of requiring the user to inform Guile about all variables in C +that might point to heap objects, Guile traces the C stack and static +data segment @dfn{conservatively}. That is to say, Guile just treats +every word on the C stack and every C global variable as a potential +reference in to the Scheme heap@footnote{Note that Guile does not scan +the C heap for references, so a reference to a @code{SCM} object from a +memory segment allocated with @code{malloc} will have to use some other +means to keep the @code{SCM} object alive. @xref{Garbage Collection +Functions}.}. 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 |