[svn:parrot] r36618 - in trunk/docs: . book dev pdds pdds/draft
cotto at svn.parrot.org
cotto at svn.parrot.org
Thu Feb 12 06:59:38 UTC 2009
Author: cotto
Date: Thu Feb 12 06:59:37 2009
New Revision: 36618
URL: https://trac.parrot.org/parrot/changeset/36618
Log:
[gc] replace most references to "DOD" in the docs
Modified:
trunk/docs/book/ch13_reference.pod
trunk/docs/debugger.pod
trunk/docs/dev/infant.pod
trunk/docs/dev/pmc_freeze.pod
trunk/docs/memory_internals.pod
trunk/docs/pdds/draft/pdd06_pasm.pod
trunk/docs/pdds/draft/pdd11_extending.pod
trunk/docs/pdds/pdd09_gc.pod
trunk/docs/pdds/pdd17_pmc.pod
trunk/docs/pmc.pod
trunk/docs/running.pod
Modified: trunk/docs/book/ch13_reference.pod
==============================================================================
--- trunk/docs/book/ch13_reference.pod Thu Feb 12 06:10:36 2009 (r36617)
+++ trunk/docs/book/ch13_reference.pod Thu Feb 12 06:59:37 2009 (r36618)
@@ -1267,7 +1267,7 @@
=cell C<2>
-=cell Number of DOD sweeps performed.
+=cell Number of GC mark runs performed.
=row
@@ -1303,7 +1303,7 @@
=cell C<8>
-=cell Number of new PMC or buffer headers allocated since last DOD run.
+=cell Number of new PMC or buffer headers allocated since last mark run.
=row
@@ -2017,7 +2017,7 @@
register R<PMC>
Register the given PMC in the interpreter's root set, so that it's
-visible during DOD.
+visible during the mark phase.
I<Arguments: P>
@@ -2535,8 +2535,8 @@
sweep R<LAZY>
-Trigger a dead object detection (DOD) sweep. If R<LAZY> is set to 1,
-only objects that need timely destruction may be destroyed.
+Trigger a GC mark run. If R<LAZY> is set to 1, only objects that need timely
+destruction may be destroyed.
I<Arguments: IC>
@@ -2546,7 +2546,7 @@
sweepoff
-Disable DOD sweeps (nestable).
+Disable GC mark runs (nestable).
=head3 sweepon
@@ -2554,7 +2554,7 @@
sweepon
-Re-enable DOD sweeps.
+Re-enable GC mark runs.
=head3 sysinfo
@@ -3618,7 +3618,7 @@
=item -G,--no-gc
-Turn off DOD/GC. This is for debugging only.
+Turn off GC. This is for debugging only.
=item -.,--wait
Modified: trunk/docs/debugger.pod
==============================================================================
--- trunk/docs/debugger.pod Thu Feb 12 06:10:36 2009 (r36617)
+++ trunk/docs/debugger.pod Thu Feb 12 06:59:37 2009 (r36618)
@@ -354,8 +354,8 @@
(pdb) info
Total memory allocated = 81936
- DOD runs = 6
- Collect runs = 0
+ GC mark runs = 6
+ GC collect runs = 0
Active PMCs = 8197
Active buffers = 7
Total PMCs = 21840
Modified: trunk/docs/dev/infant.pod
==============================================================================
--- trunk/docs/dev/infant.pod Thu Feb 12 06:10:36 2009 (r36617)
+++ trunk/docs/dev/infant.pod Thu Feb 12 06:59:37 2009 (r36618)
@@ -8,23 +8,23 @@
=head1 Overview
We have a garbage collector that needs to detect all dead objects (the process
-is called DOD, for Dead Object Detection). Any Parrot operation that might
-allocate memory can potentially trigger a DOD run (if not enough memory is
+is called the mark phase of GC). Any Parrot operation that might allocate
+memory can potentially trigger a GC mark run (if not enough memory is
available, we need to free up some unused objects to give us enough room to
allocate our new object. But in order to know what can be freed up, we need to
-know what's alive, so we do a DOD pass.)
+know what's alive, so we do a GC mark run.)
-The DOD pass begins with a "root set" of objects that are known to be in use --
-the PMC and String registers, the Parrot stack, the global symbol table, etc.
-Each of these objects is scanned for references to other objects, recursively.
-All objects found during this search are regarded as live. Everything else is
-considered dead and so is available for reclamation.
+The GC mark run pass begins with a "root set" of objects that are known to be
+in use -- the PMC and String registers, the Parrot stack, the global symbol
+table, etc. Each of these objects is scanned for references to other objects,
+recursively. All objects found during this search are regarded as live.
+Everything else is considered dead and so is available for reclamation.
The question of what should be in the root set is problematic. Consider the
case where you've created a PMC. If you immediately stuff it into a register,
then you're all set. But what if you're putting it into an aggregate? If the
aggregate isn't large enough, you'll need to resize it, which might allocate
-memory, which might trigger a DOD run. And that DOD run may free your
+memory, which might trigger a GC mark run. And that run may free your
freshly-created PMC.
In this case, the solution is simple: resize the array, if necessary, before
@@ -45,10 +45,10 @@
must also scan through all processor registers, and for some processors there
may be a separate backing store for those registers (eg the Sparc's register
windows). Uninitialized data on the stack and high alignment requirements for
-stackframes can fool the DOD system with left over pointers from previous
+stackframes can fool the GC system with left over pointers from previous
calls. This is especially a problem for objects which need early destruction.
- + No slowdown in the common case of no DOD
+ + No slowdown in the common case of no dead objects
+ Convenient: the programmer does not need to code differently to
accommodate the garbage collection system.
- Unportable. Different processors need different code for scanning
@@ -57,7 +57,7 @@
find all the pointers, while on others you must NOT scan every
possible offset or you'll get a bus error due to a misaligned
access.
- - Slow DOD. A full stack walk takes quite a while, and this time
+ - Slow mark phase. A full stack walk takes quite a while, and this time
grows with nested interpreter calls, external code's stack usage, etc.
- Complex. The stack walk is necessarily conservative, in that it
must consider every valid pointer on the stack to potentially be a
@@ -77,7 +77,7 @@
There are several possible variants of the neonate flag, but the basic idea is
to set a flag on newly created objects that prevents them from being collected.
At some point, this flag is cleared -- either as the newborn object is anchored
-to the root set, or during the first DOD pass after it was anchored, or
+to the root set, or during the first mark pass after it was anchored, or
explicitly when the object is no longer needed.
+ Portable
@@ -100,7 +100,7 @@
The flag is always explicitly cleared by the coder.
+ Very simple
- + Fast DOD
+ + Fast mark phase
- Slow for unanchored temporaries
- Slow for anchored objects
- Easy to forget to clear the flag for unanchored temporaries
@@ -113,7 +113,7 @@
to the root set also clear the flag.
+ Simple
- + Fast DOD
+ + Fast mark phase
- Slow for unanchored temporaries
- Slow for anchored objects
- Easy to forget to clear the flag for unanchored temporaries
@@ -121,15 +121,15 @@
direct assignment into a PMC register, for example)
- longjmp() can bypass the clearing
-=head2 Variant 3: clear during DOD
+=head2 Variant 3: clear during mark phase
-The neonate flag is cleared during DOD when an object is encountered during the
-recursive root set traversal. (Leopold Toetsch's trick of setting the live_FLAG
-during creation is equivalent to this variation, I think.)
+The neonate flag is cleared during the mark phase when an object is encountered
+during the recursive root set traversal. (Leopold Toetsch's trick of setting
+the live_FLAG during creation is equivalent to this variation, I think.)
+ Simple
- + Fast DOD (DOD already manipulates the flags)
- - If there are multiple DOD runs before the object is anchored or
+ + Fast mark phase (GC already manipulates the flags)
+ - If there are multiple mark runs before the object is anchored or
dies, it will be prematurely freed
=head2 Variant 4: generation count
@@ -139,7 +139,7 @@
The generation is incremented only at major control points such between
opcodes, so that there is no chance of unanchored temporaries.
- + Fast DOD (DOD already manipulates the flags)
+ + Fast mark phase (GC already manipulates the flags)
- Generation count must be maintained
- Disallows recursive opcode calls (necessary for eg implementing
vtable methods in pasm)
@@ -158,12 +158,12 @@
whether the current generation is _different_ from an object's creation
generation (which eliminates wraparound problems, too.) So rather than testing
against a single "current" generation, allow a stack of multiple "current"
-generations. An object encountered during DOD will have its neonate flag
-cleared only if it doesn't match any of the "current" generation ids. This
+generations. An object encountered during the mark phase will have its neonate
+flag cleared only if it doesn't match any of the "current" generation ids. This
check can be optimized using a conservative bit mask as a preliminary test.
- + Still faster DOD than stackwalking, though slower than the
- other neonate variants
+ + Still faster mark phase than stackwalking, though slower than the other
+ neonate variants
- Generation count must be maintained
- Generation stack must be maintained
- Disallows longjmp()'ing out of recursive opcode calls
@@ -175,7 +175,7 @@
Another similar idea is to use a generational system, with the "current
generation" as a value on the C stack, passed as an extra argument after the
interpreter. If a function creates temporary objects it calls other functions
-with an increased generational count. During a DOD run, any PMC with a
+with an increased generational count. During a mark run, any PMC with a
generation less than the current generation is considered live. Any PMC with a
generation greater than the current generation is considered free. This works
through longjmps and recursive run_cores.
@@ -185,7 +185,7 @@
+ Works through longjmps and recursive run_cores
+ No explicit setting and clearing of flags
- Needs to change to change the signature of every Parrot function
- - Nested temporaries can survive if there is no DOD-run between two
+ - Nested temporaries can survive if there is no mark run between two
function calls with increased generation count
=head1 Solution 3: Explicit root set augmentation
@@ -198,7 +198,7 @@
advantages and disadvantages of explicit neonate flag setting:
+ Simple
- + Fast DOD
+ + Fast mark phase
- Slow for unanchored temporaries
- Sometimes slow for anchored objects (depending on whether they need
to be temporarily anchored before the final anchoring)
@@ -214,15 +214,15 @@
=head2 Variant 2: Anchor early, anchor often
First place a new PMC in the root set (e.g. a register), then initialise it. If
-that's too cumbersome, disable DOD; if that's suboptimal, use active anchoring
+that's too cumbersome, disable GC; if that's suboptimal, use active anchoring
to some root set linked list for temporary PMCs.
+ Simple
- + Fast DOD (No stack-walking)
- - DOD might be turned off for a long time (Maybe a recursive run_core
+ + Fast mark phase (No stack-walking)
+ - GC might be turned off for a long time (Maybe a recursive run_core
is called)
- - Easy to forget to reenable DOD
- - longjmp() can bypass reenabling of DOD (this might be hidden in the
+ - Easy to forget to reenable GC
+ - longjmp() can bypass reenabling of GC (this might be hidden in the
wrapper functions as only one value needs to be restored)
=head2 Variant 3: Use a linked list of frames
@@ -230,11 +230,11 @@
The signature of every Parrot function is extended with an extra parameter
which is a parameter to a frame structure. All temporary PMCs needs to put into
such a frame structure. The first parameter of this frame structure is a link
-to the previously used frame structure. If a function that can do a DOD run is
+to the previously used frame structure. If a function that can do a mark run is
called a pointer to the current frame is applied. The linked list of frames
represents always an exact list of the active temporaries on the C-stack.
- + Fast DOD-runs (only the known PMC-pointers are walked)
+ + Fast mark runs (only the known PMC-pointers are walked)
+ Exact
+ works through recursive run_cores and longjmp()
- signature of every Parrot function changes
Modified: trunk/docs/dev/pmc_freeze.pod
==============================================================================
--- trunk/docs/dev/pmc_freeze.pod Thu Feb 12 06:10:36 2009 (r36617)
+++ trunk/docs/dev/pmc_freeze.pod Thu Feb 12 06:59:37 2009 (r36618)
@@ -58,10 +58,10 @@
=item mark
-Mark all objects as being live by calling B<pobject_lives> called from DOD.
+Mark all objects as being live by calling B<pobject_lives> called from GC.
While the functionality is the same, it will not be implemented on top of this
general scheme for performance reasons. This leads to some code duplication,
-but DOD is run permanently and deserves all the speed it can get.
+but GC is run permanently and deserves all the speed it can get.
=back
@@ -96,8 +96,8 @@
prepending) the current PMC to a B<mark_ptr>, which then points to the current
PMC, forming a linked list of items.
-This pointer is also used during DOD's B<mark()> functionality, so that DOD has
-to be turned off during operations using this scheme.
+This pointer is also used during GC's B<mark()> functionality, so that
+GC has to be turned off during operations using this scheme.
As the B<next_for_GC> pointer is inside the PMC, this scheme isn't thread-safe
at low-level, because shared PMCs also would share this pointer, so that there
@@ -106,7 +106,7 @@
=item todo list
A B<List> called B<todo> holds items still to be worked on. This method is
-slower and consumes more resources, but doesn't interfere with DOD runs and is
+slower and consumes more resources, but doesn't interfere with GC runs and is
thread-safe.
=back
@@ -162,7 +162,7 @@
B<next_for_GC> pointer. This is an optimization reducing the size of scalars
and increasing performance considerably.
-Second, the B<next_for_GC> pointers have to be cleared beforehand. DOD uses
+Second, the B<next_for_GC> pointers have to be cleared beforehand. GC uses
only a nibble-sized flag area located inside the PMCs arena to manage, if a PMC
was seen already by checking the live bit. The B<next_for_GC> pointer is just
set and never cleared to avoid touching a PMCs memory and polluting caches when
Modified: trunk/docs/memory_internals.pod
==============================================================================
--- trunk/docs/memory_internals.pod Thu Feb 12 06:10:36 2009 (r36617)
+++ trunk/docs/memory_internals.pod Thu Feb 12 06:59:37 2009 (r36618)
@@ -132,15 +132,19 @@
=head2 GC-related PObj flags
-Only three flags need to be checked during a DOD run: C<PObj_live_FLAG>,
+Only three flags need to be checked during a mark run: C<PObj_live_FLAG>,
C<PObj_on_free_list_FLAG>, and C<PObj_is_special_PMC_FLAG>. Normally these
flags are stored in C<PObj-E<gt>flags>, meaning that each PMC must be accessed
-during the DOD run.
+during the mark run.
-An alternative approach is to store the DOD-Flags together somewhere, such as
+An alternative approach is to store the GC-Flags together somewhere, such as
in the individual arenas, as a packed array of bits. This approach, called
cardmarking, should be indicated by defining the preprocessor variable
-C<ARENA_DOD_FLAGS> to 1.
+C<ARENA_GC_FLAGS> to 1.
+
+{{ ARENA_GC_FLAGS (nee ARENA_DOD_FLAGS) seems to have been deprecated or
+changed without concomitant update to this document. Someone should figure out
+what this macro used to be and whether it's still relevant. -cotto }}
F<pobj.h> provides macros to facilitate referencing individual object flags:
C<gc_flag_SET>, C<gc_flag_CLEAR> and C<gc_flag_TEST>. They make up a portable
@@ -186,11 +190,11 @@
Using this allocator, all variable sized items are just allocated via a plain
C<malloc()> call, or resized with C<realloc()>, and after they lose their
-existence (ie when DOD detects that the managing buffer header is no longer in
-use) they are C<free()>ed. That's all. The underlying allocator collects these
-pieces, coalesces them if possible to form bigger pieces, and then puts them on
-free lists, sorted by size. Eventually, when a new allocation request arrives,
-it may give them back to Parrot.
+existence (ie when the mark phase detects that the managing buffer header is no
+longer in use) they are C<free()>ed. That's all. The underlying allocator
+collects these pieces, coalesces them if possible to form bigger pieces, and
+then puts them on free lists, sorted by size. Eventually, when a new
+allocation request arrives, it may give them back to Parrot.
So here, the variable length C<memory_pool> is unused. You can consider this
pool to live inside the allocator. Buffers allocated this way don't move
@@ -224,9 +228,10 @@
in the buffer header, so other users of this string can be updated to reuse the
same string (RT#47764 one or all other users?).
-The C<malloc()>/C<free()> approach stores a refcount at C<bufstart>. During DOD
-all dead users increment the refcount, living users set it to an huge value.
-When freeing the buffer, the string is only freed if the refcount reaches zero.
+The C<malloc()>/C<free()> approach stores a refcount at C<bufstart>. During the
+mark phase all dead users increment the refcount, living users set it to an
+huge value. When freeing the buffer, the string is only freed if the refcount
+reaches zero.
=head1 Simplified Figure
Modified: trunk/docs/pdds/draft/pdd06_pasm.pod
==============================================================================
--- trunk/docs/pdds/draft/pdd06_pasm.pod Thu Feb 12 06:10:36 2009 (r36617)
+++ trunk/docs/pdds/draft/pdd06_pasm.pod Thu Feb 12 06:59:37 2009 (r36618)
@@ -700,17 +700,17 @@
Buffers. Doesn't include any housekeeping memory, memory for Buffer or PMC
structs, or things of that nature.
-=item 2 GC_RUNS
+=item 2 GC_MARK_RUNS
-The total number of garbage collection runs that have been made.
+The total number of garbage collection mark runs that have been made.
-=item 3 COLLECT_RUNS
+=item 3 GC_COLLECT_RUNS
-The total number of memory collection runs that have been made.
+The total number of garbage collection sweep runs that have been made.
=item 4 ACTIVE_PMCS
-The number of PMCs considered active. This means the DOD scan hasn't noted
+The number of PMCs considered active. This means the GC scan hasn't noted
them as dead.
=item 5 ACTIVE_BUFFERS
@@ -730,7 +730,7 @@
=item 8 HEADERS_ALLOC_SINCE_COLLECT
The number of new Buffer header block allocations that have been made since
-the last DOD run. (Buffers, when allocated, are allocated in chunks)
+the last GC mark run. (Buffers, when allocated, are allocated in chunks)
=item 9 MEM_ALLOCS_SINCE_COLLECT
Modified: trunk/docs/pdds/draft/pdd11_extending.pod
==============================================================================
--- trunk/docs/pdds/draft/pdd11_extending.pod Thu Feb 12 06:10:36 2009 (r36617)
+++ trunk/docs/pdds/draft/pdd11_extending.pod Thu Feb 12 06:59:37 2009 (r36618)
@@ -258,13 +258,13 @@
=item C<Parrot_register_pmc(interp, pmc)>
-Add a reference to the PMC to the interpreter's DOD registry. This prevents
-PMCs known only to extensions from getting destroyed during DOD runs.
+Add a reference to the PMC to the interpreter's GC registry. This prevents
+PMCs known only to extensions from getting destroyed during GC runs.
=item C<Parrot_unregister_pmc(interp, pmc)>
-Remove a reference to the PMC from the interpreter's DOD registry. If the
-reference count reaches zero, the PMC will be destroyed during the next DOD
+Remove a reference to the PMC from the interpreter's GC registry. If the
+reference count reaches zero, the PMC will be destroyed during the next GC
run.
=back
Modified: trunk/docs/pdds/pdd09_gc.pod
==============================================================================
--- trunk/docs/pdds/pdd09_gc.pod Thu Feb 12 06:10:36 2009 (r36617)
+++ trunk/docs/pdds/pdd09_gc.pod Thu Feb 12 06:59:37 2009 (r36618)
@@ -166,7 +166,7 @@
"sweep" phase). The sweep phase is also known as the collection phase. The
trace phase is also known as the "mark phase" and less frequently as the
"dead object detection" phase. The use of the term "dead object detection"
-and it's acronym DOD has been deprecated.
+and its acronym DOD has been deprecated.
=head3 Initial Marking
Modified: trunk/docs/pdds/pdd17_pmc.pod
==============================================================================
--- trunk/docs/pdds/pdd17_pmc.pod Thu Feb 12 06:10:36 2009 (r36617)
+++ trunk/docs/pdds/pdd17_pmc.pod Thu Feb 12 06:59:37 2009 (r36618)
@@ -513,18 +513,18 @@
void mark(INTERP, PMC *self)
-Called when the DOD is tracing live PMCs. If this method is called then the
+Called when the GC is tracing live PMCs. If this method is called then the
code must mark all strings and PMCs that it contains as live, otherwise they
may be collected.
-This method is only called if the DOD has detected that this PMC is both alive
+This method is only called if the GC has detected that this PMC is both alive
and has a custom mark routine as indicated by the custom mark PMC flag. (Most
normal PMCs don't need a custom mark routine.)
If a PMC has this flag set, then it is responsible for marking all buffers and
PMCs under its control as alive. If it does not, those PMCs or buffers may be
collected later. This method does I<not> have to call the C<mark> method on
-any PMCs it marks--the DOD system takes care of that. (So no need to recurse
+any PMCs it marks--the GC system takes care of that. (So no need to recurse
into aggregate PMCs or anything of the sort).
This method may allocate no memory from Parrot, nor may it alter Parrot's
@@ -535,7 +535,7 @@
void destroy(INTERP, PMC *self)
-Called when the PMC is destroyed. This method is called by the DOD when it
+Called when the PMC is destroyed. This method is called by the GC when it
determines that a PMC is dead and that the PMC has marked itself as having a
destroy method (an active finalizer).
Modified: trunk/docs/pmc.pod
==============================================================================
--- trunk/docs/pmc.pod Thu Feb 12 06:10:36 2009 (r36617)
+++ trunk/docs/pmc.pod Thu Feb 12 06:59:37 2009 (r36618)
@@ -41,16 +41,16 @@
Each PMC has 8 private flags B<PObj_private0_FLAG> - B<PObj_private7_FLAG>,
which can be used for storing 8 bits.
-=head1 PMCs and DOD
+=head1 PMCs and GC
=head2 Overview
-The DOD system doesn't make any assumptions about your PMC's layout. Whenever a
+The GC system doesn't make any assumptions about your PMC's layout. Whenever a
PMC is found in the root set, B<pobject_lives()> is called with that PMC. The
PMC is responsible to mark all contained or referenced active Parrot objects
(Buffers or other PMCs).
-=head2 DOD related flags
+=head2 GC related flags
=over 4
@@ -83,7 +83,7 @@
=item PObj_active_destroy_FLAG
The PMC's B<destroy> vtable is called, when this PMC is found to be dead during
-DOD.
+GC.
=item PObj_needs_early_gc_FLAG
Modified: trunk/docs/running.pod
==============================================================================
--- trunk/docs/running.pod Thu Feb 12 06:10:36 2009 (r36617)
+++ trunk/docs/running.pod Thu Feb 12 06:59:37 2009 (r36618)
@@ -203,9 +203,9 @@
=item -G, --no-gc
-This turns off DOD (Dead Object Detection) and GC. This may be useful to find
-GC related bugs. Don't use this option for longer running programs: as memory
-is no longer recycled, it may quickly become exhausted.
+This turns off GC. This may be useful to find GC related bugs. Don't use this
+option for longer running programs: as memory is no longer recycled, it may
+quickly become exhausted.
=item --leak-test, --destroy-at-end
More information about the parrot-commits
mailing list