basis/io/mmap/mmap-docs.factor

   1 USING: help.markup help.syntax alien math continuations
   2 destructors ;
   3 IN: io.mmap
   4
   5 HELP: mapped-file
   6 { $class-description "The class of memory-mapped files, opened by " { $link <mapped-file> } " and closed by " { $link close-mapped-file } ". The following two slots are of interest to users:"
   7     { $list
   8         { { $snippet "length" } " - the length of the mapped file area, in bytes" }
   9         { { $snippet "address" } " - an " { $link alien } " pointing at the file's memory area" }
  10     }
  11 } ;
  12
  13 HELP: <mapped-file>
  14 { $values { "path" "a pathname string" } { "length" integer } { "mmap" mapped-file } }
  15 { $contract "Opens a file and maps the first " { $snippet "length" } " bytes into memory. The length is permitted to exceed the length of the file on disk, in which case the remaining space is padded with zero bytes." }
  16 { $notes "You must call " { $link close-mapped-file } " when you are finished working with the returned object, to reclaim resources. The " { $link with-mapped-file } " provides an abstraction which can close the mapped file for you." }
  17 { $errors "Throws an error if a memory mapping could not be established." } ;
  18
  19 HELP: with-mapped-file
  20 { $values { "path" "a pathname string" } { "length" integer } { "quot" "a quotation with stack effect " { $snippet "( mmap -- )" } } }
  21 { $contract "Opens a file and maps its contents into memory, passing the " { $link mapped-file } " instance to the quotation. The mapped file is disposed of when the quotation returns, or if an error is thrown." }
  22 { $errors "Throws an error if a memory mapping could not be established." } ;
  23
  24 HELP: close-mapped-file
  25 { $values { "mmap" mapped-file } }
  26 { $contract "Releases system resources associated with the mapped file. This word should not be called by user code; use " { $link dispose } " instead." }
  27 { $errors "Throws an error if a memory mapping could not be established." } ;
  28
  29 ARTICLE: "io.mmap" "Memory-mapped files"
  30 "The " { $vocab-link "io.mmap" } " vocabulary implements support for memory-mapped files."
  31 { $subsection <mapped-file> }
  32 "Memory-mapped files are disposable and can be closed with " { $link dispose } " or " { $link with-disposal } "."
  33 $nl
  34 "A utility combinator which wraps the above:"
  35 { $subsection with-mapped-file }
  36 "Memory mapped files implement the " { $link "sequence-protocol" } " and present themselves as a sequence of bytes. The underlying memory area can also be accessed directly with the " { $snippet "address" } " slot." $nl
  37 "Data can be read and written from the memory area using alien words. See " { $link "reading-writing-memory" } "." ;
  38
  39 ABOUT: "io.mmap"