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 "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" { $quotation "( 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" { $quotation "( 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 "Factor has the ability to save the entire state of the system into an " { $emphasis "image file" } ". 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 "One reason to save a custom image is if you find yourself loading the same libraries in every Factor session; some libraries take a little while to compile, so saving an image with those libraries loaded can save you a lot of time."
  78 $nl
  79 "For example, to save an image with the web framework loaded,"
  80 { $code "USE: furnace" "save" }
  81 "New images can be created from scratch:"
  82 { $subsection "bootstrap.image" }
  83 "The " { $link "tools.deploy" } " tool creates stripped-down images containing just enough code to run a single application."
  84 { $see-also "tools.memory" } ;
  85
  86 ABOUT: "images"