compiler.cfg.stacks.*: new docs

Mostly from making comments into doc definitions

basis/compiler/cfg/stacks/global/global-docs.factor

@@ -0,0 +1,25 @@
+USING: compiler.cfg.instructions compiler.cfg.stacks.finalize
+help.markup help.syntax ;
+IN: compiler.cfg.stacks.global
+
+HELP: avail
+{ $class-description "A stack location is available at a location if all paths from the entry block to the location load the location into a register." } ;
+
+HELP: anticip
+{ $class-description "A stack location is anticipated at a location if every path from the location to an exit block will read the stack location before writing it." } ;
+
+HELP: dead
+{ $class-description "A stack location is dead at a location if no paths from the location to the exit block read the location before writing it." } ;
+
+HELP: live
+{ $class-description "A stack location is live at a location if some path from the location to an exit block will read the stack location before writing it." } ;
+
+HELP: pending
+{ $class-description "A stack location is pending at a location if all paths from the entry block to the location write the location." } ;
+
+ARTICLE: "compiler.cfg.stacks.global" "Global stack analysis"
+"This vocab defines a bunch of dataflow analysises:"
+{ $subsections avail anticip dead live pending }
+"The info they gather is used by " { $link finalize-stack-shuffling } " for optimal insertion of " { $link ##peek } " and " { $link ##replace } " instructions." ;
+
+ABOUT: "compiler.cfg.stacks.global"

basis/compiler/cfg/stacks/global/global.factor

@@ -15,41 +15,28 @@ IN: compiler.cfg.stacks.global
 : transfer-peeked-locs ( set bb -- set' )
     [ replace-set diff ] [ peek-set union ] bi ;
 
-! A stack location is anticipated at a location if every path from
-! the location to an exit block will read the stack location
-! before writing it.
 BACKWARD-ANALYSIS: anticip
 
 M: anticip transfer-set drop transfer-peeked-locs ;
 M: anticip join-sets 2drop refine ;
 
-! A stack location is live at a location if some path from
-! the location to an exit block will read the stack location
-! before writing it.
 BACKWARD-ANALYSIS: live
 
 M: live transfer-set drop transfer-peeked-locs ;
 M: live join-sets 2drop combine ;
 
-! A stack location is available at a location if all paths from
-! the entry block to the location load the location into a
-! register.
 FORWARD-ANALYSIS: avail
 
 M: avail transfer-set
     drop [ peek-set ] [ replace-set ] bi union union ;
 M: avail join-sets 2drop refine ;
 
-! A stack location is pending at a location if all paths from
-! the entry block to the location write the location.
 FORWARD-ANALYSIS: pending
 
 M: pending transfer-set
     drop replace-set union ;
 M: pending join-sets 2drop refine ;
 
-! A stack location is dead at a location if no paths from the
-! location to the exit block read the location before writing it.
 BACKWARD-ANALYSIS: dead
 
 M: dead transfer-set

basis/compiler/cfg/stacks/local/local-docs.factor

@@ -1,26 +1,60 @@
-USING: assocs compiler.cfg compiler.cfg.instructions compiler.cfg.registers
+USING: assocs compiler.cfg compiler.cfg.instructions
-help.markup help.syntax math sequences ;
+compiler.cfg.registers hash-sets hashtables help.markup help.syntax
+sequences ;
 IN: compiler.cfg.stacks.local
 
-HELP: replaces
+HELP: emit-changes
-{ $var-description "An " { $link assoc } " that maps from stack locations to virtual registers that were put on the stack." }
+{ $values { "replaces" sequence } { "state" sequence } }
-{ $see-also replace-loc } ;
+{ $description "Insert height and stack changes prior to the last instruction." } ;
+
+HELP: end-local-analysis
+{ $values { "basic-block" basic-block } }
+{ $description "Called to end the local analysis of a block. The word writes to the dynamic variables " { $link replace-sets } ", " { $link peek-sets } " and " { $link kill-sets } " what the blocks replaces, peeks and kill locations are." } ;
 
 HELP: height-state
 { $var-description "A two-tuple used to keep track of the heights of the data and retain stacks in a " { $link basic-block } " The idea is that if the stack change instructions are tracked, then multiple changes can be folded into one. The first item is the datastacks current height and queued up height change. The second item is the same for the retain stack." } ;
 
+HELP: height-state>insns
+{ $values { "state" sequence } { "insns" sequence } }
+{ $description "Converts a " { $link height-state } " tuple to 0-2 stack height change instructions." }
+{ $examples
+  "In this example the datastacks height is increased by 4 and the retainstacks decreased by 2."
+  { $example
+    "USING: compiler.cfg.stacks.local prettyprint ;"
+    "{ { 0 4 } { 0 -2 } } height-state>insns ."
+    "{ T{ ##inc { loc D: 4 } } T{ ##inc { loc R: -2 } } }"
+  }
+} ;
+
+HELP: inc-stack
+{ $values { "loc" loc } }
+{ $description "Increases or decreases the data or retain stack depending on if loc is a " { $link ds-loc } " or " { $link rs-loc } " instance. An " { $link ##inc } " instruction will later be inserted." } ;
+
+HELP: kill-sets
+{ $var-description "A " { $link hashtable } " that maps from " { $link basic-block } " to the stack locations that are killed in that block. Stack locations are deemed killed when the stack height is decreased." } ;
+
 HELP: loc>vreg
 { $values { "loc" loc } { "vreg" "virtual register" } }
 { $description "Maps a stack location to a virtual register." } ;
 
+HELP: local-peek-set
+{ $var-description "A " { $link hash-set } " used during local block analysis to keep track of peeked stack locations." } ;
+
+HELP: peek-loc
+{ $values { "loc" loc } { "vreg" "virtaul register" } }
+{ $description "Retrieves the virtual register at the given stack location." } ;
+
 HELP: replace-loc
 { $values { "vreg" "virtual register" } { "loc" loc } }
 { $description "Registers that the absolute stack location " { $snippet "loc" } " should be overwritten with the contents of the virtual register." }
 { $see-also replaces } ;
 
-HELP: peek-loc
+HELP: replace-sets
-{ $values { "loc" loc } { "vreg" "virtaul register" } }
+{ $var-description "An " { $link assoc } " that maps from basic blocks to stack locations." } ;
-{ $description "Retrieves the virtual register at the given stack location." } ;
+
+HELP: replaces
+{ $var-description "An " { $link assoc } " that maps from stack locations to virtual registers that were put on the stack." }
+{ $see-also replace-loc } ;
 
 HELP: translate-local-loc
 { $values { "loc" loc } { "state" "height state" }  { "loc'" loc } }
@@ -34,31 +68,13 @@ HELP: translate-local-loc
 }
 { $see-also height-state } ;
 
-HELP: height-state>insns
-{ $values { "state" sequence } { "insns" sequence } }
-{ $description "Converts a " { $link height-state } " tuple to 0-2 stack height change instructions." }
-{ $examples
-  { $example
-    "USING: compiler.cfg.stacks.local prettyprint ;"
-    "{ { 0 4 } { 0 -2 } } height-state>insns ."
-    "{ T{ ##inc { loc D: 4 } } T{ ##inc { loc R: -2 } } }"
-  }
-} ;
-
-HELP: emit-changes
-{ $values { "replaces" sequence } { "state" sequence } }
-{ $description "Insert height and stack changes prior to the last instruction." } ;
-
-HELP: inc-stack
-{ $values { "loc" loc } }
-{ $description "Increases or decreases the data or retain stack depending on if loc is a " { $link ds-loc } " or " { $link rs-loc } " instance. An " { $link ##inc } " instruction will later be inserted." } ;
-
 ARTICLE: "compiler.cfg.stacks.local" "Local stack analysis"
-"Local stack analysis. We build three sets for every basic block in the CFG:"
+"Local stack analysis. We build three sets for every basic block in the " { $link cfg } ":"
 { $list
   "peek-set: all stack locations that the block reads before writing"
-  "replace-set: all stack locations that the block writes"
+  { { $link replace-sets } " all stack locations that the block writes" }
-  "kill-set: all stack locations which become unavailable after the block ends because of the stack height being decremented" }
+  { { $link kill-sets } " all stack locations which become unavailable after the block ends because of the stack height being decremented" }
+}
 "This is done while constructing the CFG."
 $nl
 "Words for reading the stack state:"
@@ -71,6 +87,16 @@ $nl
   inc-stack
   modify-height
   replace-loc
+}
+"Beginning and ending analysis:"
+{ $subsections
+  begin-local-analysis
+  end-local-analysis
+}
+"Temporary variables that keeps track of the blocks read and written stack locations:"
+{ $subsections
+  local-peek-set
+  replaces
 } ;
 
 

basis/compiler/cfg/stacks/local/local.factor

@@ -1,9 +1,9 @@
 ! Copyright (C) 2009 Slava Pestov.
 ! See http://factorcode.org/license.txt for BSD license.
-USING: accessors arrays assocs combinators compiler.cfg
+USING: accessors assocs compiler.cfg.instructions
-compiler.cfg.instructions compiler.cfg.parallel-copy
+compiler.cfg.parallel-copy compiler.cfg.registers
-compiler.cfg.registers compiler.cfg.stacks.height
+compiler.cfg.stacks.height hash-sets kernel make math math.order
-fry hash-sets kernel make math math.order namespaces sequences sets ;
+namespaces sequences sets ;
 IN: compiler.cfg.stacks.local
 
 : current-height ( state -- ds rs )
@@ -84,8 +84,8 @@ SYMBOLS: local-peek-set replaces ;
 : end-local-analysis ( basic-block -- )
     [
         replaces get remove-redundant-replaces
-        dup height-state get emit-changes keys
+        [ height-state get emit-changes ]
-        swap replace-sets get set-at
+        [ keys swap replace-sets get set-at ] bi
     ]
     [ [ local-peek-set get ] dip peek-sets get set-at ]
     [ [ compute-local-kill-set ] keep kill-sets get set-at ] tri ;