basis/compiler/codegen/gc-maps/gc-maps-docs.factor

   1 USING: bit-arrays byte-arrays compiler.cfg.instructions help.markup help.syntax
   2 kernel math ;
   3 IN: compiler.codegen.gc-maps
   4
   5 ARTICLE: "compiler.codegen.gc-maps" "GC maps"
   6 "The " { $vocab-link "compiler.codegen.gc-maps" } " handles generating code for keeping track of garbage collection maps. Every code block either ends with:"
   7 { $list "uint 0" }
   8 "or"
   9 { $list
  10   {
  11       "bitmap, byte aligned, five subsequences:"
  12       { $list
  13         "scrubbed data stack locations"
  14         "scrubbed retain stack locations"
  15         "GC root spill slots"
  16       }
  17   }
  18   "uint[] base pointers"
  19   "uint[] return addresses"
  20   "uint largest scrubbed data stack location"
  21   "uint largest scrubbed retain stack location"
  22   "uint largest GC root spill slot"
  23   "uint largest derived root spill slot"
  24   "int number of return addresses"
  25 } ;
  26
  27 HELP: emit-gc-info-bitmaps
  28 { $values { "counts" "counts of the three different types of gc checks" } }
  29 { $description "Emits the scrub location data in all gc-maps registered in the " { $link gc-maps } " variable to the make sequence being created. The result is a concatenation of all datastack scrub locations, retainstack scrub locations and gc root locations converted into a byte-array. Given that byte-array and knowledge of the number of scrub locations, the original gc-map can be reconstructed."  } ;
  30
  31 HELP: emit-scrub
  32 { $values
  33   { "seqs" "a sequence of sequences of 0/1" }
  34   { "n" "length of the longest sequence" }
  35 }
  36 { $description "Emits a space-efficient " { $link bit-array } " to the make sequence being created. The outputted array will be of length n times the number of sequences given. Each group of n elements in the array contains true values if the stack location should be scrubbed, and false if it shouldn't." }
  37 { $examples
  38   { $example
  39     "USING: bit-arrays byte-arrays compiler.codegen.gc-maps make prettyprint ;"
  40     "[ { B{ 0 } B{ 0 } B{ 1 1 1 0 } } emit-scrub ] ?{ } make . ."
  41     "?{ t f f f t f f f f f f t }\n4"
  42   }
  43 } ;
  44
  45 { emit-gc-info-bitmaps emit-scrub } related-words
  46
  47 HELP: emit-uint
  48 { $values { "n" integer } }
  49 { $description "Emits an unsigned 32 bit integer to the make sequence being created. The word takes care of ensuring that the byte order is correct for the current machine." }
  50 { $examples
  51   { $example
  52     "USING: compiler.codegen.gc-maps make prettyprint ;"
  53     "[ 0xffff emit-uint ] B{ } make ."
  54     "B{ 255 255 0 0 }"
  55   }
  56 } ;
  57
  58 HELP: gc-maps
  59 { $var-description "Variable that holds a sequence of " { $link gc-map } " tuples." } ;
  60
  61 HELP: gc-map-needed?
  62 { $values { "gc-map/f" "a " { $link gc-map } " or f" } { "?" "a boolean" } }
  63 { $description "If all slots in the gc-map are empty, then it doesn't need to be emitted." } ;
  64
  65 HELP: serialize-gc-maps
  66 { $values { "byte-array" byte-array } }
  67 { $description "Serializes the gc-maps that have been registered in the " { $link gc-maps } " variable into a byte-array." } ;
  68
  69 HELP: gc-map-here
  70 { $values { "gc-map" gc-map } }
  71 { $description "Registers the gc map in the " { $link gc-maps } " dynamic variable at the current compiled offset." } ;
  72
  73 ABOUT: "compiler.codegen.gc-maps"