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

   1 USING: compiler.cfg compiler.cfg.instructions compiler.cfg.stacks.padding
   2 help.markup help.syntax sequences strings ;
   3 IN: compiler.cfg.stacks.vacant
   4
   5 ARTICLE: "compiler.cfg.stacks.vacant" "Uninitialized/overinitialized stack location analysis"
   6 "Consider the following sequence of instructions:"
   7 { $code
   8   "##inc D: 2"
   9   "..."
  10   "##allot"
  11   "##replace ... D: 0"
  12   "##replace ... D: 1"
  13 }
  14 "The GC check runs before stack locations 0 and 1 have been initialized, and so the GC needs to scrub them so that they don't get traced. This is achieved by computing uninitialized locations with a dataflow analysis, and recording the information in GC maps. The call_frame_slot_visitor object in vm/slot_visitor.hpp reads this information from GC maps and performs the scrubbing." ;
  15
  16 HELP: fill-gc-maps
  17 { $values { "cfg" cfg } }
  18 { $description "Populates the scrub-d, check-d, scrub-r and check-r slots of all gc maps in the cfg." } ;
  19
  20 HELP: state>gc-data
  21 { $values { "state" sequence } { "gc-data" sequence } }
  22 { $description "Takes a stack state on the format given by " { $link trace-stack-state } " and emits an array containing two bit-patterns with locations on the data and retain stacks to scrub." } ;
  23
  24 HELP: vacant>bits
  25 { $values
  26   { "vacant" "sequence of uninitialized stack locations" }
  27   { "bits" "sequence of 1:s and 0:s" }
  28 }
  29 { $description "Converts a sequence of uninitialized stack locations to the pattern of 1:s and 0:s that can be put in the " { $slot "scrub-d" } " and " { $slot "scrub-r" } " slots of a " { $link gc-map } ". 0:s are uninitialized locations and 1:s are initialized." }
  30 { $examples
  31   { $example
  32     "USING: compiler.cfg.stacks.vacant prettyprint ;"
  33     "{ 0 1 3 } vacant>bits ."
  34     "{ 0 0 1 0 }"
  35   }
  36 } ;
  37
  38 ABOUT: "compiler.cfg.stacks.vacant"