core/kernel.facts

   1 IN: kernel
   2 USING: generic help kernel math memory namespaces sequences kernel-internals ;
   3
   4 HELP: eq? ( obj1 obj2 -- ? )
   5 { $values { "obj1" "an object" } { "obj2" "an object" } }
   6 { $description "Tests if two references point at the same object." } ;
   7
   8 HELP: drop  ( x -- )                 $shuffle ;
   9 HELP: 2drop ( x y -- )               $shuffle ;
  10 HELP: 3drop ( x y z -- )             $shuffle ;
  11 HELP: dup   ( x -- x x )             $shuffle ;
  12 HELP: 2dup  ( x y -- x y x y )       $shuffle ;
  13 HELP: 3dup  ( x y z -- x y z x y z ) $shuffle ;
  14 HELP: rot   ( x y z -- y z x )       $shuffle ;
  15 HELP: -rot  ( x y z -- z x y )       $shuffle ;
  16 HELP: dupd  ( x y -- x x y )         $shuffle ;
  17 HELP: swapd ( x y z -- y x z )       $shuffle ;
  18 HELP: nip   ( x y -- y )             $shuffle ;
  19 HELP: 2nip  ( x y z -- z )           $shuffle ;
  20 HELP: tuck  ( x y -- y x y )         $shuffle ;
  21 HELP: over  ( x y -- x y x )         $shuffle ;
  22 HELP: pick  ( x y z -- x y z x )     $shuffle ;
  23 HELP: swap  ( x y -- y x )           $shuffle ;
  24 HELP: 2swap ( x y z t -- z t x y )   $shuffle ;
  25
  26 HELP: >r ( x -- )
  27 { $values { "x" "an object" } } { $description "Moves the top of the data stack to the retain stack." } ;
  28
  29 HELP: r> ( -- x )
  30 { $values { "x" "an object" } } { $description "Moves the top of the retain stack to the data stack." } ;
  31
  32 HELP: datastack ( -- ds )
  33 { $values { "ds" "a vector" } }
  34 { $description "Outputs the a vector containing a copy of the data stack contents right before the call to this word, with the top of the stack at the end of the vector." } ;
  35
  36 HELP: set-datastack ( ds -- )
  37 { $values { "ds" "a vector" } }
  38 { $description "Replaces the data stack contents with a copy of a vector. The end of the vector becomes the top of the stack." } ;
  39
  40 HELP: retainstack ( -- rs )
  41 { $values { "rs" "a vector" } }
  42 { $description "Outputs the a vector containing a copy of the retain stack contents right before the call to this word, with the top of the stack at the end of the vector." } ;
  43
  44 HELP: set-retainstack ( rs -- )
  45 { $values { "rs" "a vector" } }
  46 { $description "Replaces the retain stack contents with a copy of a vector. The end of the vector becomes the top of the stack." } ;
  47
  48 HELP: callstack ( -- cs )
  49 { $values { "cs" "a vector" } }
  50 { $description "Outputs the a vector containing a copy of the call stack contents right before the call to this word, with the top of the stack at the end of the vector. The call frame of the caller word is " { $emphasis "not" } " included." } ;
  51
  52 HELP: set-callstack ( cs -- )
  53 { $values { "cs" "a vector" } }
  54 { $description "Replaces the call stack contents with a copy of a vector. The end of the vector becomes the top of the stack. The current quotation continues executing. The new callstack takes effect when the current quotation returns, resulting in a callframe being popped." } ;
  55
  56 HELP: clear
  57 { $description "Clears the data stack." } ;
  58
  59 HELP: hashcode
  60 { $values { "obj" "an object" } { "n" "a fixnum" } }
  61 { $contract "Outputs the hashcode of the object. The hashcode operation must satisfy the following properties:"
  62 { $list
  63     "the hashcode should be a fixnum, however returning a bignum will not cause any problems other than potential performance degradation."
  64     { "if two objects are equal under " { $link = } ", they must have equal hashcodes" }
  65     "the hashcode is only permitted to change if the object is mutated in some way"
  66 }
  67 "If mutable objects are used as hashtable keys, they must not be mutated in such a way that their hashcode changes. Doing so will violate bucket sorting invariants and result in undefined behavior." } ;
  68
  69 HELP: =
  70 { $values { "obj1" "an object" } { "obj2" "an object" } { "?" "a boolean" } }
  71 { $description
  72     "Tests if two objects are equal. If " { $snippet "obj1" } " and " { $snippet "obj2" } " point to the same object, outputs " { $link t } ". Otherwise, calls the " { $link equal? } " generic word."
  73 } ;
  74
  75 HELP: equal?
  76 { $values { "obj1" "an object" } { "obj2" "an object" } { "?" "a boolean" } }
  77 { $contract
  78     "Tests if two objects are equal."
  79     $terpri
  80     "Method definitions should ensure that this is an equality relation:"
  81     { $list
  82         { $snippet "a = a" }
  83         { { $snippet "a = b" } " implies " { $snippet "b = a" } }
  84         { { $snippet "a = b" } " and " { $snippet "b = c" } " implies " { $snippet "a = c" } }
  85     }
  86     "While user code can define methods for this generic word, it should not call it directly, since it is slightly less efficient than " { $link = } " in the case the two references point to the same object."
  87 }
  88 { $examples
  89     "The most common reason for defining a method for this generic word to ensure that instances of a specific tuple class are only ever equal to themselves, overriding the default implementation which checks slot values for equality."
  90     { $code "TUPLE: foo ;" "M: foo equal? eq? ;" }
  91 } ;
  92
  93 HELP: <=>
  94 { $values { "obj1" "an object" } { "obj2" "an object" } { "n" "an integer" } }
  95 { $contract
  96     "Compares two objects using an intrinsic partial order, for example, the natural order for real numbers and lexicographic order for strings."
  97     $terpri
  98     "The output value is one of the following:"
  99     { $list
 100         { "positive - indicating that " { $snippet "str1" } " follows " { $snippet "str2" } }
 101         { "zero - indicating that " { $snippet "str1" } " is equal to " { $snippet "str2" } }
 102         { "negative - indicating that " { $snippet "str1" } " precedes " { $snippet "str2" } }
 103     }
 104     "The default implementation treats the two objects as sequences, and recursively compares their elements. So no extra work is required to compare sequences lexicographically."
 105 }
 106 { $see-also natural-sort } ;
 107
 108 HELP: clone
 109 { $values { "obj" "an object" } { "cloned" "a new object" } }
 110 { $contract "Outputs a new object equal to the given object. This is not guaranteed to actually copy the object; it does nothing with immutable objects, and does not copy words either. However, sequences and tuples can be cloned to obtain a shallow copy of the original." } ;
 111
 112 HELP: set-boot
 113 { $values { "quot" "a quotation" } }
 114 { $description "Sets the initial quotation called by the runtime as the last stage of startup. The image must be saved for changes to the boot quotation to take effect. Usually the boot quotation should not be changed." } ;
 115
 116 HELP: num-types
 117 { $values { "n" "a postiive integer" } }
 118 { $description "Outputs one more than the maximum value from the " { $link type } " primitive." } ;
 119
 120 DEFER: type ( object -- n )
 121
 122 HELP: type
 123 { $values { "object" "an object" } { "n" "a type number" } }
 124 { $description "Outputs an object's type number, between zero and one less than " { $link num-types } ". This is implementation detail and user code should call " { $link class } " instead." }
 125 { $see-also type>class tag } ;
 126
 127 HELP: ?
 128 { $values { "cond" "a generalized boolean" } { "true" "an object" } { "false" "an object" } { "true/false" "one two input objects" } }
 129 { $description "Chooses between two values depending on the boolean value of " { $snippet "cond" } "." } ;
 130
 131 HELP: >boolean
 132 { $values { "obj" "a generalized boolean" } { "?" "a boolean" } }
 133 { $description "Convert a generalized boolean into a boolean. That is, " { $link f } " retains its value, whereas anything else becomes " { $link t } "." } ;
 134
 135 HELP: not ( obj -- ? )
 136 { $values { "obj" "a generalized boolean" } { "?" "a boolean" } }
 137 { $description "For " { $link f } " outputs " { $link t } " and for anything else outputs " { $link f } "." } ;
 138
 139 HELP: and
 140 { $values { "obj1" "a generalized boolean" } { "obj2" "a generalized boolean" } { "obj" "a generalized boolean" } }
 141 { $description "Tests if neither object is " { $link f } "." } ;
 142
 143 HELP: or
 144 { $values { "obj1" "a generalized boolean" } { "obj2" "a generalized boolean" } { "obj" "a generalized boolean" } }
 145 { $description "Tests if at least one object is not " { $link f } "." } ;
 146
 147 HELP: xor
 148 { $values { "obj1" "a generalized boolean" } { "obj2" "a generalized boolean" } { "obj" "a generalized boolean" } }
 149 { $description "Tests if at exactly one object is not " { $link f } "." } ;
 150
 151 HELP: cpu
 152 { $values { "cpu" "a string" } }
 153 { $description
 154     "Outputs a string descriptor of the current CPU architecture. Currently, this set of descriptors is:"
 155     { $code "amd64" "ppc" "x86" }
 156 } ;
 157
 158 HELP: os
 159 { $values { "os" "a string" } }
 160 { $description
 161     "Outputs a string descriptor of the current operating system family. Currently, this set of descriptors is:"
 162     { $code "freebsd" "linux" "macosx" "solaris" "win32" "unix" }
 163 } ;
 164
 165 HELP: windows?
 166 { $values { "?" "a boolean" } }
 167 { $description "Tests if Factor is running on Windows." } ;
 168
 169 HELP: macosx?
 170 { $values { "?" "a boolean" } }
 171 { $description "Tests if Factor is running on Mac OS X." } ;
 172
 173 HELP: call ( quot -- )
 174 { $values { "quot" "a quotation" } }
 175 { $description "Push the current callframe on the callstack, and set the callframe to the given quotation. Conceptually, calls the quotation, as if its definition was substituted at the location of the call." }
 176 { $examples
 177     "The following two lines are equivalent:"
 178     { $code "2 [ 2 + 3 * ] call" "2 2 + 3 *" }
 179 } ;
 180
 181 HELP: slip
 182 { $values { "quot" "a quotation" } { "x" "an object" } }
 183 { $description "Calls a quotation while hiding the top of the stack." } ;
 184
 185 HELP: 2slip
 186 { $values { "quot" "a quotation" } { "x" "an object" } { "y" "an object" } }
 187 { $description "Calls a quotation while hiding the top two stack elements." } ;
 188
 189 HELP: keep
 190 { $values { "quot" "a quotation with stack effect " { $snippet "( x -- )" } } { "x" "an object" } }
 191 { $description "Call a quotation with a value on the stack, restoring the value when the quotation returns." } ;
 192
 193 HELP: 2keep
 194 { $values { "quot" "a quotation with stack effect " { $snippet "( x y -- )" } } { "x" "an object" } { "y" "an object" } }
 195 { $description "Call a quotation with two values on the stack, restoring the values when the quotation returns." } ;
 196
 197 HELP: 3keep
 198 { $values { "quot" "a quotation with stack effect " { $snippet "( x y -- )" } } { "x" "an object" } { "y" "an object" } { "z" "an object" } }
 199 { $description "Call a quotation with three values on the stack, restoring the values when the quotation returns." } ;
 200
 201 HELP: 2apply
 202 { $values { "quot" "a quotation with stack effect " { $snippet "( obj -- )" } } { "x" "an object" } { "y" "an object" } }
 203 { $description "Applies the quotation to " { $snippet "x" } ", then to " { $snippet "y" } "." } ;
 204
 205 HELP: if ( cond true false -- )
 206 { $values { "cond" "a generalized boolean" } { "true" "a quotation" } { "false" "a quotation" } }
 207 { $description "If " { $snippet "cond" } " is " { $link f } ", calls the " { $snippet "false" } " quotation. Otherwise calls the " { $snippet "true" } " quotation."
 208 $terpri
 209 "The " { $snippet "cond" } " value is removed from the stack before either quotation is called." } ;
 210
 211 HELP: when
 212 { $values { "cond" "a generalized boolean" } { "true" "a quotation" } }
 213 { $description "If " { $snippet "cond" } " is not " { $link f } ", calls the " { $snippet "true" } " quotation."
 214 $terpri
 215 "The " { $snippet "cond" } " value is removed from the stack before the quotation is called." } ;
 216
 217 HELP: unless
 218 { $values { "cond" "a generalized boolean" } { "false" "a quotation" } }
 219 { $description "If " { $snippet "cond" } " is " { $link f } ", calls the " { $snippet "false" } " quotation."
 220 $terpri
 221 "The " { $snippet "cond" } " value is removed from the stack before the quotation is called." } ;
 222
 223 HELP: if*
 224 { $values { "cond" "a generalized boolean" } { "true" "a quotation with stack effect " { $snippet "( cond -- )" } } { "false" "a quotation" } }
 225 { $description "Alternative conditional form that preserves the " { $snippet "cond" } " value if it is true."
 226 $terpri
 227 "If the condition is true, it is retained on the stack before the " { $snippet "true" } " quotation is called. Otherwise, the condition is removed from the stack and the " { $snippet "false" } " quotation is called."
 228 $terpri
 229 "The following two lines are equivalent:"
 230 { $code "X [ Y ] [ Z ] if*" "X dup [ Y ] [ drop Z ] if" } } ;
 231
 232 HELP: when*
 233 { $values { "cond" "a generalized boolean" } { "true" "a quotation with stack effect " { $snippet "( cond -- )" } } }
 234 { $description "Variant of " { $link if* } " with no false quotation."
 235 $terpri
 236 "The following two lines are equivalent:"
 237 { $code "X [ Y ] when*" "X dup [ Y ] [ drop ] if" } } ;
 238
 239 HELP: unless*
 240 { $values { "cond" "a generalized boolean" } { "false" "a quotation " } }
 241 { $description "Variant of " { $link if* } " with no true quotation."
 242 $terpri
 243 "The following two lines are equivalent:"
 244 { $code "X [ Y ] unless*" "X dup [ ] [ drop Y ] if" } } ;
 245
 246 HELP: ?if
 247 { $values { "default" "an object" } { "cond" "a generalized boolean" } { "true" "a quotation with stack effect " { $snippet "( cond -- )" } } { "false" "a quotation with stack effect " { $snippet "( default -- )" } } }
 248 { $description "If the condition is " { $link f } ", the " { $snippet "false" } " quotation is called with the " { $snippet "default" } " value on the stack. Otherwise, the " { $snippet "true" } " quotation is called with the condition on the stack."
 249 $terpri
 250 "The following two lines are equivalent:"
 251 { $code "[ X ] [ Y ] ?if" "dup [ nip X ] [ drop Y ] if" } } ;
 252
 253 HELP: with
 254 { $values { "obj" "an object" } { "quot" "a quotation with stack effect " { $snippet "( obj elt -- )" } } { "elt" "an object" } }
 255 { $description "Utility word used to implement curried combinators such as " { $link each-with } " and " { $link map-with } "." } ;
 256
 257 HELP: keep-datastack
 258 { $values { "quot" "a quotation" } }
 259 { $description "Calls a quotation, saving the data stack before calling it and restoring it after it returns." } ;
 260
 261 HELP: die
 262 { $description "Starts the front-end processor (FEP), which is a low-level debugger which can inspect memory addresses and the like. The FEP is also entered when a critical error occurs." } ;
 263
 264 HELP: exit ( n -- )
 265 { $values { "n" "an integer exit code" } }
 266 { $description "Exits the Factor process." } ;
 267
 268 HELP: millis ( -- n )
 269 { $values { "n" "an integer" } }
 270 { $description "Outputs the number of milliseconds ellapsed since midnight January 1, 1970." } ;
 271
 272 HELP: os-env ( key -- value )
 273 { $values { "key" "a string" } { "value" "a string" } }
 274 { $description "Looks up the value of a shell environment variable." }
 275 { $examples
 276     "This is an operating system-specific feature. On Unix, you can do:"
 277     { $example "\"USER\" os-env print" "slava" }
 278 } ;
 279
 280 HELP: cell
 281 { $values { "n" "a positive integer" } }
 282 { $description "Outputs the pointer size in bytes of the current CPU architecture." } ;
 283
 284 HELP: win32?
 285 { $values { "?" "a boolean" } }
 286 { $description "Tests if Factor is running on 32-bit Windows." } ;
 287
 288 HELP: win64?
 289 { $values { "?" "a boolean" } }
 290 { $description "Tests if Factor is running on 64-bit Windows." } ;
 291
 292 IN: memory
 293
 294 HELP: generations
 295 { $values { "n" "a positive integer" } }
 296 { $description "Outputs the number of generations partitioning the heap." } ;
 297
 298 HELP: image
 299 { $values { "path" "a path name string" } }
 300 { $description "Outputs the path name of the currently running Factor image." } ;
 301
 302 HELP: save-image ( path -- )
 303 { $values { "path" "a path name string" } }
 304 { $description "Saves a snapshot of the heap to the given file, overwriting the file if it already exists." } ;
 305
 306 HELP: save
 307 { $description "Saves a snapshot of the heap to the current image file." } ;
 308
 309 IN: kernel-internals
 310
 311 HELP: (clone) ( obj -- newobj )
 312 { $values { "obj" "an object" } { "newobj" "a shallow copy" } }
 313 { $description "Outputs a byte-by-byte copy of the given object. User code should call " { $link clone } " instead." } ;
 314
 315 HELP: declare
 316 { $values { "spec" "an array of class words" } }
 317 { $description "Declares that the elements at the top of the stack are instances of the classes in " { $snippet "spec" } "." }
 318 { $warning "The compiler blindly trusts declarations, and false declarations can lead to crashes, memory corruption and other undesirable behavior." }
 319 { $examples
 320     "The optimizer cannot do anything with the below code as you can verify with " { $link "ui-dataflow" } ":"
 321     { $code "2 + 10 *" }
 322     "However, if we declare that the top of the stack is a " { $link float } ", then type checks and generic dispatch are eliminated, and the compiler can use unsafe intrinsics:"
 323     { $code "{ float } declare 2 + 10 *" }
 324 } ;
 325
 326 HELP: array-capacity
 327 { $values { "array" "an array" } { "n" "a non-negative fixnum" } }
 328 { $description "Low-level array length accessor." }
 329 { $warning "This word is in the " { $vocab-link "kernel-internals" } " vocabulary because it is unsafe. It does not check types, so improper use can corrupt memory." } ;
 330
 331 HELP: array-nth
 332 { $values { "n" "a non-negative fixnum" } { "array" "an array" }  { "elt" "an object" } }
 333 { $description "Low-level array element accessor." }
 334 { $warning "This word is in the " { $vocab-link "kernel-internals" } " vocabulary because it is unsafe. It does not check types or array bounds, and improper use can corrupt memory." } ;
 335
 336 HELP: set-array-nth
 337 { $values { "elt" "an object" } { "n" "a non-negative fixnum" } { "array" "an array" }  }
 338 { $description "Low-level array element mutator." }
 339 { $warning "This word is in the " { $vocab-link "kernel-internals" } " vocabulary because it is unsafe. It does not check types or array bounds, and improper use can corrupt memory." } ;
 340
 341 HELP: tag ( object -- n )
 342 { $values { "object" "an object" } { "n" "a tag number" } }
 343 { $description "Outputs an object's tag number, between zero and one less than " { $link num-tags } ". This is implementation detail and user code should call " { $link class } " instead." }
 344 { $see-also type } ;
 345
 346 HELP: dispatch ( n array -- )
 347 { $values { "n" "a fixnum" } { "array" "an array of quotations" } }
 348 { $description "Calls the " { $snippet "n" } "th quotation in the array." }
 349 { $warning "This word is in the " { $vocab-link "kernel-internals" } " vocabulary because it is an implementation detail used by the generic word system to accelerate method dispatch. It does not perform type or bounds checks, and user code should not need to call it directly." } ;
 350
 351 HELP: getenv ( n -- obj )
 352 { $values { "n" "a non-negative integer" } { "obj" "an object" } }
 353 { $description "Reads an object from the Factor runtime's environment table. User code never has to read the environment table directly; instead, use one of the callers of this word." } ;
 354
 355 HELP: setenv ( obj n -- )
 356 { $values { "n" "a non-negative integer" } { "obj" "an object" } }
 357 { $description "Writes an object to the Factor runtime's environment table. User code never has to write to the environment table directly; instead, use one of the callers of this word." } ;
 358
 359 HELP: slot ( obj m -- value )
 360 { $values { "obj" "an object" } { "m" "a non-negative fixnum" } { "value" "an object" } }
 361 { $description "Reads the object stored at the " { $snippet "n" } "th slot of " { $snippet "obj" } "." }
 362 { $warning "This word is in the " { $vocab-link "kernel-internals" } " vocabulary because it does not perform type or bounds checks, and slot numbers are implementation detail." } ;
 363
 364 HELP: set-slot ( value obj n -- )
 365 { $values { "value" "an object" } { "obj" "an object" } { "m" "a non-negative fixnum" } }
 366 { $description "Writes " { $snippet "value" } " to the " { $snippet "n" } "th slot of " { $snippet "obj" } "." }
 367 { $warning "This word is in the " { $vocab-link "kernel-internals" } " vocabulary because it does not perform type or bounds checks, and slot numbers are implementation detail." } ;