compiler.*: Remove the scrubbing part of the GC maps

[factor.git] / basis / compiler / cfg / stacks / clearing / clearing-docs.factor

diff --git a/basis/compiler/cfg/stacks/clearing/clearing-docs.factor b/basis/compiler/cfg/stacks/clearing/clearing-docs.factor
index ce51872e1cf5a16c7f1419b7ecbf82e4530ce7d8..a136d4c1851632403f99f999c4ab579a5153eab3 100644 (file)
--- a/basis/compiler/cfg/stacks/clearing/clearing-docs.factor
+++ b/basis/compiler/cfg/stacks/clearing/clearing-docs.factor
@@ -3,22 +3,34 @@ help.syntax kernel sequences strings ;
 IN: compiler.cfg.stacks.clearing
 
 ARTICLE: "compiler.cfg.stacks.clearing" "Uninitialized stack location clearing"
-"A compiler pass that inserts " { $link ##replace-imm } " instructions front of unsafe " { $link ##peek } " instructions in the " { $link cfg } ". Consider the following sequence of instructions."
+"A compiler pass that inserts " { $link ##clear } " instructions front of instructions which requires the whole stack to be initialized. Consider the following sequence of instructions:"
 { $code
   "##inc D: 2"
-  "##peek RCX D: 2"
+  "..."
+  "##allot"
+  "##replace ... D: 0"
+  "##replace ... D: 1"
 }
-"The ##peek can cause a stack underflow and then there will be two uninitialized locations on the data stack that can't be traced. To counteract that, this pass modifies the instruction sequence so that it becomes:"
+"The GC check runs before stack locations 0 and 1 have been initialized, so they need to be cleared as they can contain garbage data which could crash Factor if it tries to trace them. This is achieved by computing uninitialized locations with a dataflow analysis (see " { $vocab-link "compiler.cfg.stacks.padding" } ") and then inserting clears so that the instruction sequence becomes:"
+{ $code
+  "##inc D: 2"
+  "..."
+  "##clear D: 0"
+  "##clear D: 1"
+  "##allot"
+  "##replace ... D: 0"
+  "##replace ... D: 1"
+}
+"Similar dangerous stack 'holes' needs to be padded in the same way to guard unsafe " { $link ##peek } " instructions. E.g:"
 { $code
   "##inc D: 2"
-  "##replace-imm 17 D: 0"
-  "##replace-imm 17 D: 1"
   "##peek RCX D: 2"
-} ;
+}
+"Here the ##peek can cause a stack underflow and then there will be two uninitialized locations on the captured data stack that can't be traced. As in the previous example, ##clears are inserted on locations D: 0 and D: 1." ;
 
 HELP: dangerous-insn?
 { $values { "state" "a stack state" } { "insn" insn } { "?" boolean } }
-{ $description "Checks if the instruction is dangerous (can cause a stack underflow). " }
+{ $description "Checks if the instruction is dangerous, meaning that the holes in the stack must be filled before it is executed." }
 { $examples
   { $example
     "USING: compiler.cfg.instructions compiler.cfg.registers compiler.cfg.stacks.clearing prettyprint ;"
@@ -30,6 +42,11 @@ HELP: dangerous-insn?
     "{ { 0 { } } { 2 { } } } T{ ##peek { loc R: 0 } } dangerous-insn? ."
     "f"
   }
+  { $example
+    "USING: compiler.cfg.instructions compiler.cfg.registers compiler.cfg.stacks.clearing prettyprint ;"
+    "{ { 0 { } } { 3 { } } } T{ ##call-gc } dangerous-insn?"
+    "t"
+  }
 } ;