System.IO.MMap
- mmapFilePtr :: FilePath -> Mode -> Maybe (Int64, Int) -> IO (Ptr a, IO (), Int)
- mmapFileForeignPtr :: FilePath -> Mode -> Maybe (Int64, Int) -> IO (ForeignPtr a, Int)
- mmapFileByteString :: FilePath -> Maybe (Int64, Int) -> IO ByteString
- mmapFilePtrLazy :: FilePath -> Mode -> Maybe (Int64, Int64) -> IO [(Ptr a, IO (), Int)]
- mmapFileForeignPtrLazy :: FilePath -> Mode -> Maybe (Int64, Int64) -> IO [(ForeignPtr a, Int)]
- mmapFileByteStringLazy :: FilePath -> Maybe (Int64, Int64) -> IO ByteString
- data Mode
Documentation
This module is an interface to mmap(2) system call under POSIX (Unix, Linux, Mac OS X) and CreateFileMapping,MapViewOfFile under Windows.
We can consider mmap as lazy IO pushed into the virtual memory subsystem.
It is only safe to mmap a file if you know you are the sole user.
For more details about mmap, and its consequences, see:
Memory mapped files strict interface
Arguments
| :: FilePath | name of file to mmap |
| -> Mode | access mode |
| -> Maybe (Int64, Int) | range to map, maps whole file if Nothing |
| -> IO (Ptr a, IO (), Int) | pointer, finalizer and size |
The mmapFilePtr 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 System.Mem.performGC or finalizeForeignPtr to force an unmap.
File must be created with correct attributes prior to mapping it into memory.
If mode is ReadWrite or WriteCopy, the returned memory region may
be written to with Foreign.Storable.poke and friends.
Range specified may be Nothing, 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.
Arguments
| :: FilePath | name of file to map |
| -> Mode | access mode |
| -> Maybe (Int64, Int) | range to map, maps whole file if Nothing |
| -> IO (ForeignPtr a, Int) | foreign pointer to beginning of region and size |
Maps region of file and returns it as ForeignPtr. See mmapFilePtr for details.
Arguments
| :: FilePath | name of file to map |
| -> Maybe (Int64, Int) | range to map, maps whole file if Nothing |
| -> IO ByteString | bytestring with file content |
Maps region of file and returns it as Data.ByteString.ByteString.
File is mapped in in ReadOnly mode. See mmapFilePtr 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 Data.ByteString.ByteString may change.
Memory mapped files lazy interface
Arguments
| :: FilePath | name of file to mmap |
| -> Mode | access mode |
| -> Maybe (Int64, Int64) | range to map, maps whole file if Nothing |
| -> IO [(Ptr a, IO (), Int)] | list of pointer, finalizer and size |
The mmapFilePtrLazy 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 System.Mem.performGC or finalizeForeignPtr to force an unmap.
File must be created with correct attributes prior to mapping it into memory.
If mode is ReadWrite or WriteCopy, the returned memory region may
be written to with Foreign.Storable.poke and friends.
Range specified may be Nothing, 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.
Arguments
| :: FilePath | name of file to map |
| -> Mode | access mode |
| -> Maybe (Int64, Int64) | range to map, maps whole file if Nothing |
| -> IO [(ForeignPtr a, Int)] | foreign pointer to beginning of region and size |
Maps region of file and returns it as list of ForeignPtrs. See mmapFilePtr for details.
Each chunk is mapped in on demand only.
Arguments
| :: FilePath | name of file to map |
| -> Maybe (Int64, Int64) | range to map, maps whole file if Nothing |
| -> IO ByteString | bytestring with file content |
Maps region of file and returns it as Data.ByteString.Lazy.ByteString.
File is mapped in in ReadOnly mode. See mmapFilePtrLazy 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 Data.ByteString.Lazy.ByteString may change.