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: size
  13 { $values { "obj" object } { "n" "a size in bytes" } }
  14 { $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." } ;
  15
  16 HELP: save-image
  17 { $values { "path" "a pathname string" } }
  18 { $description "Saves a snapshot of the heap to the given file, overwriting the file if it already exists." } ;
  19
  20 HELP: save-image-and-exit
  21 { $values { "path" "a pathname string" } }
  22 { $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." } ;
  23
  24 { save save-image save-image-and-exit } related-words
  25
  26 HELP: save
  27 { $description "Saves a snapshot of the heap to the current image file." } ;
  28
  29 ARTICLE: "images" "Images"
  30 "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."
  31 { $subsections
  32     save
  33     save-image
  34     save-image-and-exit
  35 }
  36 "To start Factor with a custom image, use the " { $snippet "-i=" { $emphasis "image" } } " command line switch; see " { $link "runtime-cli-args" } "."
  37 $nl
  38 "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."
  39 $nl
  40 "For example, to save an image with the web framework loaded,"
  41 { $code "USE: furnace" "save" }
  42 "New images can be created from scratch:"
  43 { $subsections "bootstrap.image" }
  44 "The " { $link "tools.deploy" } " tool creates stripped-down images containing just enough code to run a single application."
  45 { $see-also "tools.memory" } ;
  46
  47 ABOUT: "images"