libghc-bytestring-mmap-doc 0.2.2-8 / usr / share / doc / libghc-bytestring-mmap-doc / html / bytestring-mmap.txt

-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | mmap support for strict ByteStrings
--   
--   This library provides a wrapper to mmap(2), allowing files or devices
--   to be lazily loaded into memory as strict or lazy ByteStrings, using
--   the virtual memory subsystem to do on-demand loading.
@package bytestring-mmap
@version 0.2.2


-- | Low level mmap access.
module System.IO.Posix.MMap.Internal

-- | Create a bytestring from a memory mapped Ptr. A finalizer will be
--   associated with the resource, that will call munmap when the storage
--   manager detects that the resource is no longer in use.
unsafePackMMapPtr :: Ptr Word8 -> CSize -> IO ByteString
c_mmap :: CSize -> CInt -> IO (Ptr Word8)
c_munmap :: Ptr Word8 -> CSize -> IO CInt


-- | Lazy, chunk-wise memory mapping.
--   
--   Memory map a file as a lazy ByteString. Finalisers are associated
--   cached-sized portions of the file, which will be deallocated as those
--   chunks go out of scope.
--   
--   Unlike strict Bytestrings, mmapFile for Lazy ByteStrings will
--   deallocate chunks of the file.
--   
--   The storage manager is used to free chunks of the mapped memory. When
--   the garbage collector notices there are no further references to a
--   chunk, a call to munmap is made.
--   
--   In effect, the file is mmapped once, lazily, then covered with
--   finalizers for each chunk. When any chunk goes out of scope, that part
--   is deallocated. We must allocate the spine of the structure strictly
--   though, to ensure finalizers are registered for the entire file.
--   
--   The Haskell garbage collector decides when to run based on heap
--   pressure, however the mmap stores memory outside the Haskell heap, so
--   those resources are not counted when deciding to run the garbage
--   collect. The result is that finalizers run less often than you might
--   expect, and it is possible to write a lazy bytestring mmap program
--   that never deallocates (and thus doesn't run in constant space).
--   <tt>performGC</tt> or <tt>finalizerForeignPtr</tt> can be used to
--   trigger collection at sensible points.
--   
--   Note: this operation may break referential transparency! If any other
--   process on the system changes the file when it is mapped into Haskell,
--   the contents of your <a>ByteString</a> will change.
module System.IO.Posix.MMap.Lazy

-- | The <a>unsafeMMapFile</a> function maps a file or device into memory
--   as a lazy ByteString, made of 64*pagesize unmappable chunks of bytes.
--   
--   Memory mapped files will behave as if they were read lazily -- pages
--   from the file will be loaded into memory on demand.
--   
--   The storage manager is used to free chunks that go out of scope, and
--   unlike strict bytestrings, memory mapped lazy ByteStrings will be
--   deallocated in chunks (so you can write traversals that run in
--   constant space).
--   
--   However, the size of the mmapped resource is not known by the Haskell
--   GC, it appears only as a small ForeignPtr. This means that the Haskell
--   GC may not not run as often as you'd like, leading to delays in
--   unmapping chunks.
--   
--   Appropriate use of performGC or finalizerForeignPtr may be required to
--   ensure deallocation, as resources allocated by mmap are not tracked by
--   the Haskell garbage collector.
--   
--   For example, when writing out a lazy bytestring allocated with mmap,
--   you may wish to finalizeForeignPtr when each chunk is written, as the
--   chunk goes out of scope, rather than relying on the garbage collector
--   to notice the chunk has gone.
--   
--   This operation is unsafe: if the file is written to by any other
--   process on the system, the <a>ByteString</a> contents will change in
--   Haskell.
unsafeMMapFile :: FilePath -> IO ByteString


-- | mmap a file or device into memory as a strict ByteString.
module System.IO.Posix.MMap

-- | The <a>unsafeMMapFile</a> function maps a file or device into memory,
--   returning a strict <a>ByteString</a> that accesses the mapped file. If
--   the mmap fails for some reason, an error is thrown.
--   
--   Memory mapped files will behave as if they were read lazily -- pages
--   from the file will be loaded into memory on demand.
--   
--   The storage manager is used to free the mapped memory. When the
--   garbage collector notices there are no further references to the
--   mapped memory, a call to munmap is made. It is not necessary to do
--   this yourself. In tight memory situations, it may be profitable to use
--   <tt>performGC</tt> or <tt>finalizeForeignPtr</tt> to force an unmap.
--   
--   Note: this operation may break referential transparency! If any other
--   process on the system changes the file when it is mapped into Haskell,
--   the contents of your <a>ByteString</a> will change.
unsafeMMapFile :: FilePath -> IO ByteString