This document is currently a mixture of very old design notes (the +preformatted section immediately following) and some newer stuff. It +doesn't yet form anything like a complete picture. +
+
TRACER
design.mps.trace
@@ -152,12 +159,80 @@ improvement [insert actual speed improvement here].
+Whilst a trace is alive every so often its
+traceQuantum method gets invoked (via
+TracePoll) in order to do a quantum of tracing work.
+traceQuantum is responsible for ticking through the trace's
+top-level state machine. Most of the interesting work, the tracing,
+happens in the TraceFLIPPED state.
+
+The trace transitions through its states in the following sequence:
+TraceINIT ->
+(TraceUNFLIPPED) -> TraceFLIPPED ->
+TraceRECLAIM -> TraceFINISHED.
+Whilst TraceUNFLIPPED appears in the code, no trace does
+any work in this state; all traces are immediately flipped to be in the
+TraceFLIPPED state (see above).
+
+Once the trace is in the TraceFINISHED state it performs
+no more work and it can be safely destroyed. Generally the callers of
+traceQuantum will destroy the trace.
+
+Making Progress - Scanning Grey Segments
+
+Most of the interesting work of a trace, the actual tracing, happens
+in the TraceFLIPPED state (work would happen in
+the TraceUNFLIPPED state, but that is not implemented).
+
+The tracer makes progress by choosing a grey segment to scan, and
+scanning it. The actual scanning is performed by pools.
+
+Note that at all times a reference partition is maintained.
+
+The order in which the trace scans things determines the semantics of
+certain types of references (in particular, weak and final references).
+Or, to put it another way the desired semantics of weak and final
+references impose certain restrictions on the order in which the trace
+can scan things.
+
+The tracer uses a system of reference ranks (or just
+ranks) so that it can impose an order on its scanning work. The ranks
+are ordered.
+
+The tracer proceeds band by band. The first band is all objects it
+can reach by following references of the first rank. The second band is
+all subsequent objects it can reach by following references of the
+second and first ranks. The third band is all subsequent objects it can
+reach by following references of the third, second, and first ranks.
+And so on. The description of the tracer working like this originated
+in an e-mail message from RHSK [RHSK
+2007-06-25].
+
+A trace keep track of which band it is tracing. This is returned by
+the TraceBand method. Keeping this band information helps
+it implement the semantics of finalization and weakness. The band used
+to not be explicitly stored, but this hindered the implementation of
+good finalization semantics (essentially in some circumstances
+finalization messages were delayed by at least one collection cycle, see
+job001568).
+
+The band is used when selecting a grey segment to scan (the selection
+occurs in traceFindGrey). The tracer attempts to first
+find segments whose rank is the current band, then segments whose rank
+is previous to the current band, and so on. If there are no seguments
+found then the current band is exhausted and the current band is
+incremented to the next rank. When the current band is moved through
+all the ranks in this fashion there is no more tracing to be done.
+
+
+
A. References
-
+
+ [RHSK 2007-06-25]
+
+ "the semantics of rank-based tracing";
+ RHSK;
+ <URL: http://info.ravenbrook.com/mail/2007/06/25/11-35-57/0.txt>;
+ 2007-06-25.
+
+
+
+
+
B. Document History
@@ -190,6 +276,12 @@ improvement [insert actual speed improvement here].
+
+ 2007-07-02
+ DRJ
+ Added notes on tracer progress
+
+