core/memory/memory-docs.factor

   1 USING: help.markup help.syntax debugger sequences kernel
   2 quotations math ;
   3 IN: memory
   4
   5 HELP: instances
   6 { $values { "quot" { $quotation "( obj -- ? )" } } { "seq" "a fresh sequence" } }
   7 { $description "Outputs a sequence of all objects in the heap which satisfy the quotation." } ;
   8
   9 HELP: gc ( -- )
  10 { $description "Performs a full garbage collection." } ;
  11
  12 HELP: data-room ( -- data-room )
  13 { $values { "data-room" data-room } }
  14 { $description "Queries the VM for memory usage information." } ;
  15
  16 HELP: code-room ( -- code-room )
  17 { $values { "code-room" code-room } }
  18 { $description "Queries the VM for memory usage information." } ;
  19
  20 HELP: size ( obj -- n )
  21 { $values { "obj" "an object" } { "n" "a size in bytes" } }
  22 { $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." } ;
  23
  24 HELP: save-image ( path -- )
  25 { $values { "path" "a pathname string" } }
  26 { $description "Saves a snapshot of the heap to the given file, overwriting the file if it already exists." } ;
  27
  28 HELP: save-image-and-exit ( path -- )
  29 { $values { "path" "a pathname string" } }
  30 { $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." } ;
  31
  32 { save save-image save-image-and-exit } related-words
  33
  34 HELP: save
  35 { $description "Saves a snapshot of the heap to the current image file." } ;
  36
  37 ARTICLE: "images" "Images"
  38 "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."
  39 { $subsections
  40     save
  41     save-image
  42     save-image-and-exit
  43 }
  44 "To start Factor with a custom image, use the " { $snippet "-i=" { $emphasis "image" } } " command line switch; see " { $link "runtime-cli-args" } "."
  45 $nl
  46 "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."
  47 $nl
  48 "For example, to save an image with the web framework loaded,"
  49 { $code "USE: furnace" "save" }
  50 "New images can be created from scratch:"
  51 { $subsections "bootstrap.image" }
  52 "The " { $link "tools.deploy" } " tool creates stripped-down images containing just enough code to run a single application."
  53 { $see-also "tools.memory" } ;
  54
  55 ABOUT: "images"