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         "checked data stack locations"
  16         "checked retain stack locations"
  17         "GC root spill slots"
  18       }
  19   }
  20   "uint[] base pointers"
  21   "uint[] return addresses"
  22   "uint largest scrubbed data stack location"
  23   "uint largest scrubbed retain stack location"
  24   "uint largest checked data stack location"
  25   "uint largest checked retain stack location"
  26   "uint largest GC root spill slot"
  27   "uint largest derived root spill slot"
  28   "int number of return addresses"
  29 } ;
  30
  31 HELP: emit-gc-info-bitmaps
  32 { $values { "scrub-and-check-counts" "counts of the five different types of gc checks" } }
  33 { $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."  } ;
  34
  35 HELP: emit-scrub
  36 { $values
  37   { "seqs" "a sequence of sequences of 0/1" }
  38   { "n" "length of the longest sequence" }
  39 }
  40 { $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." }
  41 { $examples
  42   { $example
  43     "USING: bit-arrays byte-arrays compiler.codegen.gc-maps make prettyprint ;"
  44     "[ { B{ 0 } B{ 0 } B{ 1 1 1 0 } } emit-scrub ] ?{ } make . ."
  45     "?{ t f f f t f f f f f f t }\n4"
  46   }
  47 } ;
  48
  49 { emit-gc-info-bitmaps emit-scrub } related-words
  50
  51 HELP: emit-uint
  52 { $values { "n" integer } }
  53 { $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." }
  54 { $examples
  55   { $example
  56     "USING: compiler.codegen.gc-maps make prettyprint ;"
  57     "[ 0xffff emit-uint ] B{ } make ."
  58     "B{ 255 255 0 0 }"
  59   }
  60 } ;
  61
  62 HELP: gc-maps
  63 { $var-description "Variable that holds a sequence of " { $link gc-map } " tuples." } ;
  64
  65 HELP: gc-map-needed?
  66 { $values { "gc-map/f" "a " { $link gc-map } " or f" } { "?" "a boolean" } }
  67 { $description "If all slots in the gc-map are empty, then it doesn't need to be emitted." } ;
  68
  69 HELP: serialize-gc-maps
  70 { $values { "byte-array" byte-array } }
  71 { $description "Serializes the gc-maps that have been registered in the " { $link gc-maps } " variable into a byte-array." } ;
  72
  73 HELP: gc-map-here
  74 { $values { "gc-map" gc-map } }
  75 { $description "Registers the gc map in the " { $link gc-maps } " dynamic variable at the current compiled offset." } ;
  76
  77 ABOUT: "compiler.codegen.gc-maps"