core/layouts/layouts-docs.factor

   1 USING: generic help.markup help.syntax kernel math
   2 memory namespaces sequences kernel.private classes
   3 classes.builtin sequences.private ;
   4 IN: layouts
   5
   6 HELP: tag-bits
   7 { $var-description "Number of least significant bits reserved for a type tag in a tagged pointer." }
   8 { $see-also tag } ;
   9
  10 HELP: num-tags
  11 { $var-description "Number of distinct pointer tags. This is one more than the maximum value from the " { $link tag } " primitive." } ;
  12
  13 HELP: tag-mask
  14 { $var-description "Taking the bitwise and of a tagged pointer with this mask leaves the tag." } ;
  15
  16 HELP: num-types
  17 { $var-description "Number of distinct built-in types. This is one more than the maximum value from the " { $link hi-tag } " primitive." } ;
  18
  19 HELP: tag-number
  20 { $values { "class" class } { "n" "an integer or " { $link f } } }
  21 { $description "Outputs the pointer tag for pointers to instances of " { $link class } ". Will output " { $link f } " if instances of this class are not identified by a distinct pointer tag." } ;
  22
  23 HELP: type-number
  24 { $values { "class" class } { "n" "an integer or " { $link f } } }
  25 { $description "Outputs the built-in type number instances of " { $link class } ". Will output " { $link f } " if this is not a built-in class." }
  26 { $see-also builtin-class } ;
  27
  28 HELP: tag-fixnum
  29 { $values { "n" integer } { "tagged" integer } }
  30 { $description "Outputs a tagged fixnum." } ;
  31
  32 HELP: first-bignum
  33 { $values { "n" "smallest positive integer not representable by a fixnum" } } ;
  34
  35 HELP: most-positive-fixnum
  36 { $values { "n" "largest positive integer representable by a fixnum" } } ;
  37
  38 HELP: most-negative-fixnum
  39 { $values { "n" "smallest negative integer representable by a fixnum" } } ;
  40
  41 HELP: bootstrap-first-bignum
  42 { $values { "n" "smallest positive integer not representable by a fixnum" } }
  43 { $description "Outputs the value for the target architecture when bootstrapping." } ;
  44
  45 HELP: bootstrap-most-positive-fixnum
  46 { $values { "n" "largest positive integer representable by a fixnum" } }
  47 { $description "Outputs the value for the target architecture when bootstrapping." } ;
  48
  49 HELP: bootstrap-most-negative-fixnum
  50 { $values { "n" "smallest negative integer representable by a fixnum" } }
  51 { $description "Outputs the value for the target architecture when bootstrapping." } ;
  52
  53 HELP: cell
  54 { $values { "n" "a positive integer" } }
  55 { $description "Outputs the pointer size in bytes of the current CPU architecture." } ;
  56
  57 HELP: cells
  58 { $values { "m" integer } { "n" integer } }
  59 { $description "Computes the number of bytes used by " { $snippet "m" } " CPU operand-sized cells." } ;
  60
  61 HELP: cell-bits
  62 { $values { "n" integer } }
  63 { $description "Outputs the number of bits in one CPU operand-sized cell." } ;
  64
  65 HELP: bootstrap-cell
  66 { $values { "n" "a positive integer" } }
  67 { $description "Outputs the pointer size in bytes for the target image (if bootstrapping) or the current CPU architecture (otherwise)." } ;
  68
  69 HELP: bootstrap-cells
  70 { $values { "m" integer } { "n" integer } }
  71 { $description "Computes the number of bytes used by " { $snippet "m" } " cells in the target image (if bootstrapping) or the current CPU architecture (otherwise)." } ;
  72
  73 HELP: bootstrap-cell-bits
  74 { $values { "n" integer } }
  75 { $description "Outputs the number of bits in one cell in the target image (if bootstrapping) or the current CPU architecture (otherwise)." } ;
  76
  77 ARTICLE: "layouts-types" "Type numbers"
  78 "Corresponding to every built-in class is a built-in type number. An object can be asked for its built-in type number:"
  79 { $subsections hi-tag }
  80 "Built-in type numbers can be converted to classes, and vice versa:"
  81 { $subsections
  82     type>class
  83     type-number
  84     num-types
  85 }
  86 { $see-also "builtin-classes" } ;
  87
  88 ARTICLE: "layouts-tags" "Tagged pointers"
  89 "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."
  90 $nl
  91 "Getting the tag of an object:"
  92 { $link tag }
  93 "Words for working with tagged pointers:"
  94 { $subsections
  95     tag-bits
  96     num-tags
  97     tag-mask
  98     tag-number
  99 }
 100 "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." ;
 101
 102 ARTICLE: "layouts-limits" "Sizes and limits"
 103 "Processor cell size:"
 104 { $subsections
 105     cell
 106     cells
 107     cell-bits
 108 }
 109 "Range of integers representable by " { $link fixnum } "s:"
 110 { $subsections
 111     most-negative-fixnum
 112     most-positive-fixnum
 113 }
 114 "Maximum array size:"
 115 { $subsections max-array-capacity } ;
 116
 117 ARTICLE: "layouts-bootstrap" "Bootstrap support"
 118 "Processor cell size for the target architecture:"
 119 { $subsections
 120     bootstrap-cell
 121     bootstrap-cells
 122     bootstrap-cell-bits
 123 }
 124 "Range of integers representable by " { $link fixnum } "s of the target architecture:"
 125 { $subsections
 126     bootstrap-most-negative-fixnum
 127     bootstrap-most-positive-fixnum
 128 }
 129 "Maximum array size for the target architecture:"
 130 { $subsections bootstrap-max-array-capacity } ;
 131
 132 ARTICLE: "layouts" "VM memory layouts"
 133 "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."
 134 { $subsections
 135     "layouts-types"
 136     "layouts-tags"
 137     "layouts-limits"
 138     "layouts-bootstrap"
 139 } ;
 140
 141 ABOUT: "layouts"