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 { $subsection hi-tag }
  80 "Built-in type numbers can be converted to classes, and vice versa:"
  81 { $subsection type>class }
  82 { $subsection type-number }
  83 { $subsection num-types }
  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 "Getting the tag of an object:"
  90 { $link tag }
  91 "Words for working with tagged pointers:"
  92 { $subsection tag-bits }
  93 { $subsection num-tags }
  94 { $subsection tag-mask }
  95 { $subsection tag-number }
  96 "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." ;
  97
  98 ARTICLE: "layouts-limits" "Sizes and limits"
  99 "Processor cell size:"
 100 { $subsection cell }
 101 { $subsection cells }
 102 { $subsection cell-bits }
 103 "Range of integers representable by " { $link fixnum } "s:"
 104 { $subsection most-negative-fixnum }
 105 { $subsection most-positive-fixnum }
 106 "Maximum array size:"
 107 { $subsection max-array-capacity } ;
 108
 109 ARTICLE: "layouts-bootstrap" "Bootstrap support"
 110 "Processor cell size for the target architecture:"
 111 { $subsection bootstrap-cell }
 112 { $subsection bootstrap-cells }
 113 { $subsection bootstrap-cell-bits }
 114 "Range of integers representable by " { $link fixnum } "s of the target architecture:"
 115 { $subsection bootstrap-most-negative-fixnum }
 116 { $subsection bootstrap-most-positive-fixnum }
 117 "Maximum array size for the target architecture:"
 118 { $subsection bootstrap-max-array-capacity } ;
 119
 120 ARTICLE: "layouts" "VM memory layouts"
 121 "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."
 122 { $subsection "layouts-types" }
 123 { $subsection "layouts-tags" }
 124 { $subsection "layouts-limits" }
 125 { $subsection "layouts-bootstrap" } ;
 126
 127 ABOUT: "layouts"