core/memory/memory-docs.factor

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