core/memory/memory-docs.factor

   1 USING: help.markup help.syntax debugger sequences kernel
   2 quotations math ;
   3 IN: memory
   4
   5 HELP: begin-scan ( -- )
   6 { $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."
   7 $nl
   8 "This word must always be paired with a call to " { $link end-scan } "." }
   9 { $notes "This is a low-level facility and can be dangerous. Use the " { $link each-object } " combinator instead." } ;
  10
  11 HELP: next-object ( -- obj )
  12 { $values { "obj" object } }
  13 { $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." }
  14 { $errors "Throws a " { $link heap-scan-error. } " if called outside a " { $link begin-scan } "/" { $link end-scan } " pair." }
  15 { $notes "This is a low-level facility and can be dangerous. Use the " { $link each-object } " combinator instead." } ;
  16
  17 HELP: end-scan ( -- )
  18 { $description "Finishes a heap iteration by re-enabling the garbage collector. This word must always be paired with a call to " { $link begin-scan } "." }
  19 { $notes "This is a low-level facility and can be dangerous. Use the " { $link each-object } " combinator instead." } ;
  20
  21 HELP: each-object
  22 { $values { "quot" "a quotation with stack effect " { $snippet "( obj -- )" } } }
  23 { $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." }
  24 { $notes "This word is the low-level facility used to implement the " { $link instances } " word." } ;
  25
  26 HELP: instances
  27 { $values { "quot" "a quotation with stack effect " { $snippet "( obj -- ? )" } } { "seq" "a fresh sequence" } }
  28 { $description "Outputs a sequence of all objects in the heap which satisfy the quotation." }
  29 { $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." } ;
  30
  31 HELP: gc ( -- )
  32 { $description "Performs a full garbage collection." } ;
  33
  34 HELP: data-room ( -- cards generations )
  35 { $values { "cards" "number of bytes reserved for card marking" } { "generations" "array of free/total bytes pairs" } }
  36 { $description "Queries the runtime for memory usage information." } ;
  37
  38 HELP: code-room ( -- code-free code-total )
  39 { $values { "code-free" "bytes free in the code heap" } { "code-total" "total bytes in the code heap" } }
  40 { $description "Queries the runtime for memory usage information." } ;
  41
  42 HELP: size ( obj -- n )
  43 { $values { "obj" "an object" } { "n" "a size in bytes" } }
  44 { $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." } ;
  45
  46 HELP: save-image ( path -- )
  47 { $values { "path" "a pathname string" } }
  48 { $description "Saves a snapshot of the heap to the given file, overwriting the file if it already exists." } ;
  49
  50 HELP: save-image-and-exit ( path -- )
  51 { $values { "path" "a pathname string" } }
  52 { $description "Saves a snapshot of the heap to the given file, overwriting the file if it already exists. This word compacts the code heap and immediately exits Factor, since the Factor VM cannot continue executing after compiled code blocks have been moved around." } ;
  53
  54 { save save-image save-image-and-exit } related-words
  55
  56 HELP: save
  57 { $description "Saves a snapshot of the heap to the current image file." } ;
  58
  59 HELP: count-instances
  60 { $values
  61      { "quot" quotation }
  62      { "n" integer } }
  63 { $description "Applies the predicate quotation to each object in the heap and returns the number of objects that match. Since this word uses " { $link each-object } " with the garbage collector switched off, avoid allocating too much memory in the quotation." }
  64 { $examples { $unchecked-example
  65     "USING: memory words prettyprint ;"
  66     "[ word? ] count-instances ."
  67     "24210"
  68 } } ;
  69
  70 ARTICLE: "images" "Images"
  71 "The current image can be saved; the image contains a complete dump of all data and code in the current Factor instance:"
  72 { $subsection save }
  73 { $subsection save-image }
  74 { $subsection save-image-and-exit }
  75 "To start Factor with a custom image, use the " { $snippet "-i=" { $emphasis "image" } } " command line switch; see " { $link "runtime-cli-args" } "."
  76 $nl
  77 "New images can be created from scratch:"
  78 { $subsection "bootstrap.image" }
  79 { $see-also "tools.memory" "tools.deploy" } ;
  80
  81 ABOUT: "images"