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


-- | Memory mapped files for POSIX and Windows
--   
--   This library provides a wrapper to mmap(2) or MapViewOfFile, allowing
--   files or devices to be lazily loaded into memory as strict or lazy
--   ByteStrings, ForeignPtrs or plain Ptrs, using the virtual memory
--   subsystem to do on-demand loading. Modifications are also supported.
@package mmap
@version 0.3

module System.IO.MMap

-- | The <a>mmapFilePtr</a> function maps a file or device into memory,
--   returning a tripple containing pointer that accesses the mapped file,
--   the finalizer to run to unmap region and size of mmaped memory.
--   
--   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>System.Mem.performGC</tt> or <a>finalizeForeignPtr</a> to force an
--   unmap.
--   
--   File must be created with correct attributes prior to mapping it into
--   memory.
--   
--   If mode is <a>ReadWrite</a> or <a>WriteCopy</a>, the returned memory
--   region may be written to with <tt>Foreign.Storable.poke</tt> and
--   friends.
--   
--   Range specified may be <a>Nothing</a>, then whole file is mapped.
--   Otherwise range should be 'Just (offset,size)' where offsets is the
--   beginning byte of file region to map and size tells its length. There
--   are no alignment requirements.
--   
--   If range to map extends beyond end of file, it will be resized
--   accordingly.
mmapFilePtr :: FilePath -> Mode -> Maybe (Int64, Int) -> IO (Ptr a, IO (), Int)

-- | Maps region of file and returns it as <a>ForeignPtr</a>. See
--   <a>mmapFilePtr</a> for details.
mmapFileForeignPtr :: FilePath -> Mode -> Maybe (Int64, Int) -> IO (ForeignPtr a, Int)

-- | Maps region of file and returns it as
--   <tt>Data.ByteString.ByteString</tt>. File is mapped in in
--   <a>ReadOnly</a> mode. See <a>mmapFilePtr</a> for details
--   
--   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 <tt>Data.ByteString.ByteString</tt> may change.
mmapFileByteString :: FilePath -> Maybe (Int64, Int) -> IO ByteString

-- | The <a>mmapFilePtrLazy</a> function maps a file or device into memory,
--   returning a list of tripples containing pointer that accesses the
--   mapped file, the finalizer to run to unmap that region and size of
--   mapped memory.
--   
--   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>System.Mem.performGC</tt> or <a>finalizeForeignPtr</a> to force an
--   unmap.
--   
--   File must be created with correct attributes prior to mapping it into
--   memory.
--   
--   If mode is <a>ReadWrite</a> or <a>WriteCopy</a>, the returned memory
--   region may be written to with <tt>Foreign.Storable.poke</tt> and
--   friends.
--   
--   Range specified may be <a>Nothing</a>, then whole file is mapped.
--   Otherwise range should be 'Just (offset,size)' where offsets is the
--   beginning byte of file region to map and size tells its length. There
--   are no alignment requirements.
--   
--   If range to map extends beyond end of file, it will be resized
--   accordingly.
mmapFilePtrLazy :: FilePath -> Mode -> Maybe (Int64, Int64) -> IO [(Ptr a, IO (), Int)]

-- | Maps region of file and returns it as list of <a>ForeignPtr</a>s. See
--   <a>mmapFilePtr</a> for details. Each chunk is mapped in on demand
--   only.
mmapFileForeignPtrLazy :: FilePath -> Mode -> Maybe (Int64, Int64) -> IO [(ForeignPtr a, Int)]

-- | Maps region of file and returns it as
--   <tt>Data.ByteString.Lazy.ByteString</tt>. File is mapped in in
--   <a>ReadOnly</a> mode. See <a>mmapFilePtrLazy</a> for details. Chunks
--   are mapped in on demand.
--   
--   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 <tt>Data.ByteString.Lazy.ByteString</tt> may
--   change.
mmapFileByteStringLazy :: FilePath -> Maybe (Int64, Int64) -> IO ByteString

-- | Mode of mapping. Three cases are supported.
data Mode

-- | file is mapped read-only
ReadOnly :: Mode

-- | file is mapped read-write
ReadWrite :: Mode

-- | file is mapped read-write, but changes aren't propagated to disk
WriteCopy :: Mode
instance Eq Mode
instance Ord Mode
instance Enum Mode