Cross-referencing rank assumptions in response to review <#214 (comment)

>.
Ravenbrook · Jun 17, 2023 · 7cddef5 · 7cddef5
1 parent 8b169cf
commit 7cddef5
Show file tree

Hide file tree

Showing 2 changed files with 7 additions and 5 deletions.
diff --git a/code/trans.c b/code/trans.c
@@ -222,9 +222,9 @@ static Res transformFix(Seg seg, ScanState ss, Ref *refIO)
 
     if (TableLookup(&refNew, transform->oldToNew, (Word)ref)) {
       if (ss->rank == RankAMBIG) {
-        /* We rely on the fact that ambiguous references are fixed
-           first, so that no exact references have been transformed
-           yet. */
+        /* .rank-order: We rely on the fact that ambiguous references
+           are fixed first, so that no exact references have been
+           transformed yet.  See design.mps.trace.rank. */
         transform->aborted = TRUE;
       } else {
         /* NOTE: We could fix refNew in the table before copying it,

diff --git a/design/trace.txt b/design/trace.txt
@@ -236,8 +236,10 @@ 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.
+.rank: 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.  [TODO: Explain how ordering is also required for transforms.
+See impl.c.trans.rank-order.  RB 2023-06-16]
 
 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