IN: memory
USING: help ;

HELP: full-gc "( -- )"
{ $description "Performs a full garbage collection." } ;

HELP: room. "( -- )"
{ $description "Prints an overview of memory usage broken down by generation and zone." } ;

HELP: each-object "( quot -- )"
{ $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." } ;

HELP: each-slot "( obj quot -- )"
{ $values { "obj" "an object" } { "quot" "a quotation with stack effect " { $snippet "( slot -- )" } } }
{ $description "Applies a quotation to the value of each one of an object's slots." } ;

HELP: refers? "( obj1 obj2 -- ? )"
{ $values { "obj1" "an object" } { "obj2" "an object" } { "?" "a boolean" } }
{ $description "Tests if any one of " { $snippet "obj2" } "'s slots point to " { $link "obj1" } "." } ;

HELP: references "( obj -- seq )"
{ $values { "obj" "an object" } { "seq" "a fresh sequence" } }
{ $description "Outputs a sequence of all objects in the heap which refer to the given object via one of their slots." }
{ $notes "The output sequence sometimes refers to temporary objects created by the execution of the " { $link references } " word itself." } ;

HELP: heap-stats "( -- counts sizes )"
{ $values { "counts" "a hashtable mapping class words to integers" } { "sizes" "a hashtable mapping class words to integers" } }
{ $description "Outputs a pair of hashtables, holding class instance counts and instance memory usage, respectively." } ;

HELP: heap-stats. "( -- )"
{ $description "For each class, prints the number of instances and total memory consumed by those instances." } ;