{ $values { "obj" "an object" } { "n" "a memory address" } }
{ $description "Outputs the address where " { $snippet "obj" } " is located in memory. Objects can be moved around by the GC and there is almost never any reason for user code to need to know object addresses." } ;
HELP: gc "( n -- )"
{ $values { "n" "a positive integer" } }
{ $description "Collects all generations up to and including the " { $snippet "n" } "th generation. The nursery where new objects are allocated is generation 0, and tenured space is generation " { $snippet "g-1" } " where " { $snippet "g" } " is the value output by " { $link generations } "." } ;
HELP: gc-time "( -- n )"
{ $values { "n" "a timestamp in milliseconds" } }
{ $description "Outputs the total time spent in garbage collection during this Factor session." }
{ $examples "This word is used by " { $link time } " to measure the time spent in garbage collection during the execution of a quotation." } ;
{ $values { "code-free" "bytes free in the code heap" } { "code-total" "total bytes in the code heap" } { "cards" "number of bytes reserved for card marking" } { "semi" "number of bytes reserved for tenured semi-space" } { "generations" "array of free/total bytes pairs" } }
{ $description "Queries the runtime for memory usage information. To see this in a human-readable form, call " { $link room. } " instead." } ;
HELP: size "( obj -- n )"
{ $values { "obj" "an object" } { "n" "a size in bytes" } }
{ $description "Outputs the size of the object in memory, in bytes. Tagged immediate objects such as fixnums and " { $link f } " will yield a size of 0." } ;
{ $description "Moves all objects to tenured space, disables the garbage collector, and resets the heap scan pointer to point at the first object in the heap. The " { $link next-object } " word can then be called to advance the heap scan pointer and return successive objects."
$terpri
"This word must always be paired with a call to " { $link end-scan } "." }
{ $notes "This is a low-level facility and can be dangerous. Use the " { $link each-object } " combinator instead." } ;
HELP: next-object "( -- obj )"
{ $description "Outputs the object at the heap scan pointer, and then advances the heap scan pointer. If the end of the heap has been reached, outputs " { $link f } ". This is unambiguous since the " { $link f } " object is tagged immediate and not actually stored in the heap." }
{ $errors "Throws an error if called outside a " { $link begin-scan } "/" { $link end-scan } " pair." }
{ $notes "This is a low-level facility and can be dangerous. Use the " { $link each-object } " combinator instead." } ;
HELP: end-scan "( -- )"
{ $description "Finishes a heap iteration by re-enabling the garbage collector. This word must always be paired with a call to " { $link begin-scan } "." }
{ $notes "This is a low-level facility and can be dangerous. Use the " { $link each-object } " combinator instead." } ;
{ $values { "quot" "a quotation with stack effect " { $snippet "( obj -- )" } } }
{ $description "Applies a quotation to each object in the heap. The garbage collector is switched off while this combinator runs, so the given quotation must not allocate too much memory." }
{ $notes "This word is the low-level facility used to implement the " { $link instances } ", " { $link references } " and " { $link heap-stats. } " words." } ;
HELP: instances "( quot -- seq )"
{ $values { "quot" "a quotation with stack effect " { $snippet "( obj -- ? )" } } { "seq" "a fresh sequence" } }
{ $description "Outputs a sequence of all objects in the heap which satisfy the quotation." }
{ $notes "This word relies on " { $link each-object } ", so in particular the garbage collector is switched off while it runs and the given quotation must not allocate too much memory." } ;
