mmap-0.1: Memory mapped files for POSIX and Windows

System.IO.MMap

Contents

Synopsis

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

mmapFilePtrSource

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.

mmapFileForeignPtrSource

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.

mmapFileByteStringSource

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

mmapFilePtrLazySource

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.

mmapFileForeignPtrLazySource

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.

mmapFileByteStringLazySource

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.

Mapping mode

data Mode Source

Mode of mapping. Three cases are supported.

Constructors

ReadOnly

file is mapped read-only

ReadWrite

file is mapped read-write

WriteCopy

file is mapped read-write, but changes aren't propagated to disk

Instances