core/layouts/layouts-docs.factor

   1 USING: help.markup help.syntax math kernel.private classes
   2 classes.builtin ;
   3 IN: layouts
   4
   5 HELP: tag-bits
   6 { $var-description "Number of least significant bits reserved for a type tag in a tagged pointer." }
   7 { $see-also tag } ;
   8
   9 HELP: tag-mask
  10 { $var-description "Taking the bitwise and of a tagged pointer with this mask leaves the tag." } ;
  11
  12 HELP: num-types
  13 { $var-description "Number of distinct built-in types. This is one more than the maximum value from the " { $link tag } " primitive." } ;
  14
  15 HELP: type-number
  16 { $values { "class" class } { "n" { $maybe integer } } }
  17 { $description "Outputs the built-in type number instances of " { $link class } ". Will output " { $link f } " if this is not a built-in class." }
  18 { $see-also builtin-class } ;
  19
  20 HELP: tag-fixnum
  21 { $values { "n" integer } { "tagged" integer } }
  22 { $description "Outputs a tagged fixnum." } ;
  23
  24 HELP: fixnum-bits
  25 { $values { "n" "number of bits in a fixnum" } } ;
  26
  27 HELP: first-bignum
  28 { $values { "n" "smallest positive integer not representable by a fixnum" } } ;
  29
  30 HELP: most-positive-fixnum
  31 { $values { "n" "largest positive integer representable by a fixnum" } } ;
  32
  33 HELP: most-negative-fixnum
  34 { $values { "n" "smallest negative integer representable by a fixnum" } } ;
  35
  36 HELP: bootstrap-first-bignum
  37 { $values { "n" "smallest positive integer not representable by a fixnum" } }
  38 { $description "Outputs the value for the target architecture when bootstrapping." } ;
  39
  40 HELP: bootstrap-most-positive-fixnum
  41 { $values { "n" "largest positive integer representable by a fixnum" } }
  42 { $description "Outputs the value for the target architecture when bootstrapping." } ;
  43
  44 HELP: bootstrap-most-negative-fixnum
  45 { $values { "n" "smallest negative integer representable by a fixnum" } }
  46 { $description "Outputs the value for the target architecture when bootstrapping." } ;
  47
  48 HELP: cell
  49 { $values { "n" "a positive integer" } }
  50 { $description "Outputs the pointer size in bytes of the current CPU architecture." } ;
  51
  52 HELP: cells
  53 { $values { "m" integer } { "n" integer } }
  54 { $description "Computes the number of bytes used by " { $snippet "m" } " CPU operand-sized cells." } ;
  55
  56 HELP: cell-bits
  57 { $values { "n" integer } }
  58 { $description "Outputs the number of bits in one CPU operand-sized cell." } ;
  59
  60 HELP: bootstrap-cell
  61 { $values { "n" "a positive integer" } }
  62 { $description "Outputs the pointer size in bytes for the target image (if bootstrapping) or the current CPU architecture (otherwise)." } ;
  63
  64 HELP: bootstrap-cells
  65 { $values { "m" integer } { "n" integer } }
  66 { $description "Computes the number of bytes used by " { $snippet "m" } " cells in the target image (if bootstrapping) or the current CPU architecture (otherwise)." } ;
  67
  68 HELP: bootstrap-cell-bits
  69 { $values { "n" integer } }
  70 { $description "Outputs the number of bits in one cell in the target image (if bootstrapping) or the current CPU architecture (otherwise)." } ;
  71
  72 HELP: immediate
  73 { $class-description "Union class of all values that the Factor VM can store immediately, all others are stored as references (pointer) to them." } ;
  74
  75 ARTICLE: "layouts-types" "Type numbers"
  76 "Corresponding to every built-in class is a built-in type number. An object can be asked for its built-in type number:"
  77 { $subsections tag }
  78 "Built-in type numbers can be converted to classes, and vice versa:"
  79 { $subsections
  80     type>class
  81     type-number
  82     num-types
  83 }
  84 { $see-also "builtin-classes" } ;
  85
  86 ARTICLE: "layouts-tags" "Tagged pointers"
  87 "Every pointer stored on the stack or in the heap has a " { $emphasis "tag" } ", which is a small integer identifying the type of the pointer. If the tag is not equal to one of the two special tags, the remaining bits contain the memory address of a heap-allocated object. The two special tags are the " { $link fixnum } " tag and the " { $link f } " tag."
  88 $nl
  89 "Words for working with tagged pointers:"
  90 { $subsections
  91     tag-bits
  92     tag-mask
  93 }
  94 "The Factor VM does not actually expose any words for working with tagged pointers directly. The above words operate on integers; they are used in the bootstrap image generator and the optimizing compiler." ;
  95
  96 ARTICLE: "layouts-limits" "Sizes and limits"
  97 "Processor cell size:"
  98 { $subsections
  99     cell
 100     cells
 101     cell-bits
 102 }
 103 "Range of integers representable by " { $link fixnum } "s:"
 104 { $subsections
 105     most-negative-fixnum
 106     most-positive-fixnum
 107 }
 108 "Maximum array size:"
 109 { $subsections max-array-capacity } ;
 110
 111 ARTICLE: "layouts-bootstrap" "Bootstrap support"
 112 "Processor cell size for the target architecture:"
 113 { $subsections
 114     bootstrap-cell
 115     bootstrap-cells
 116     bootstrap-cell-bits
 117 }
 118 "Range of integers representable by " { $link fixnum } "s of the target architecture:"
 119 { $subsections
 120     bootstrap-most-negative-fixnum
 121     bootstrap-most-positive-fixnum
 122 }
 123 "Maximum array size for the target architecture:"
 124 { $subsections bootstrap-max-array-capacity } ;
 125
 126 ARTICLE: "layouts" "VM memory layouts"
 127 "The words documented in this section do not ever need to be called by user code. They are documented for the benefit of those wishing to explore the internals of Factor's implementation."
 128 { $subsections
 129     "layouts-types"
 130     "layouts-tags"
 131     "layouts-limits"
 132     "layouts-bootstrap"
 133 } ;
 134
 135 ABOUT: "layouts"