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" }  { "mmap" mapped-file } }
  15 { $contract "Opens a file and maps its contents 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 dispose } " 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" } { "quot" { $quotation "( 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 { $notes "This is a low-level word, because " { $link mapped-file } " objects simply expose their base address and length. Most applications should use " { $link "io.mmap.arrays" } " instead." }
  23 { $errors "Throws an error if a memory mapping could not be established." } ;
  24
  25 HELP: close-mapped-file
  26 { $values { "mmap" mapped-file } }
  27 { $contract "Releases system resources associated with the mapped file. This word should not be called by user code; use " { $link dispose } " instead." }
  28 { $errors "Throws an error if a memory mapping could not be established." } ;
  29
  30 ARTICLE: "io.mmap.arrays" "Memory-mapped arrays"
  31 "Mapped file can be viewed as a sequence using the words in sub-vocabularies of " { $vocab-link "io.mmap" } ". For each primitive C type " { $snippet "T" } ", a set of words are defined in the vocabulary named " { $snippet "io.mmap.T" } ":"
  32 { $table
  33     { { $snippet "<mapped-T-array>" } { "Wraps a " { $link mapped-file } " in a sequence; stack effect " { $snippet "( mapped-file -- direct-array )" } } }
  34     { { $snippet "with-mapped-T-file" } { "Maps a file into memory and wraps it in a sequence by combining " { $link with-mapped-file } " and " { $snippet "<mapped-T-array>" } "; stack effect " { $snippet "( path quot -- )" } } }
  35 }
  36 "The primitive C types for which mapped arrays exist:"
  37 { $list
  38     { $snippet "char" }
  39     { $snippet "uchar" }
  40     { $snippet "short" }
  41     { $snippet "ushort" }
  42     { $snippet "int" }
  43     { $snippet "uint" }
  44     { $snippet "long" }
  45     { $snippet "ulong" }
  46     { $snippet "longlong" }
  47     { $snippet "ulonglong" }
  48     { $snippet "float" }
  49     { $snippet "double" }
  50     { $snippet "void*" }
  51     { $snippet "bool" }
  52 } ;
  53
  54 ARTICLE: "io.mmap.low-level" "Reading and writing mapped files directly"
  55 "Data can be read and written from the " { $link mapped-file } " by applying low-level alien words to the " { $slot "address" } " slot. See " { $link "reading-writing-memory" } "." ;
  56
  57 ARTICLE: "io.mmap.examples" "Memory-mapped file example"
  58 "Convert a file of 4-byte cells from little to big endian or vice versa, by directly mapping it into memory and operating on it with sequence words:"
  59 { $code
  60     "USING: accessors grouping io.files io.mmap.char kernel sequences ;"
  61     "\"mydata.dat\" ["
  62     "    4 <sliced-groups> [ reverse-here ] change-each"
  63     "] with-mapped-char-file"
  64 } ;
  65
  66 ARTICLE: "io.mmap" "Memory-mapped files"
  67 "The " { $vocab-link "io.mmap" } " vocabulary implements support for memory-mapped files."
  68 { $subsection <mapped-file> }
  69 "Memory-mapped files are disposable and can be closed with " { $link dispose } " or " { $link with-disposal } "."
  70 { $subsection "io.mmap.examples" }
  71 "A utility combinator which wraps the above:"
  72 { $subsection with-mapped-file }
  73 "Instances of " { $link mapped-file } " don't support any interesting operations in themselves. There are two facilities for accessing their contents:"
  74 { $subsection "io.mmap.arrays" }
  75 { $subsection "io.mmap.low-level" } ;
  76
  77 ABOUT: "io.mmap"