Public Documentation
Functions
The following functions are available on all Unix systems.
UnixMmap.mmap
— Functionmmap(file::Union{IO,AbstractString}[, ::Type{Array{T}}, dims]; kws...)
mmap(::Type{Array{T}}, dims; kws...)
Memory maps an Array
from a file file
of size dims
(either a scalar Integer
or a tuple of dimension lengths), or creates an anonymous mapping not backed by a file if no file is given.
If not specified, the array type defaults to Array{UInt8}
, and dim
defaults to a vector with length equal to the number of elements remaining in the file (accounting for a non-zero position in the file stream io
).
Extended help
This function provides a relatively simple wrapper around the underlying mmap
system call. In particular, it is the user's responsibility to ensure the combination(s) of stream state (e.g. read/write or read-only, file length), protection flags, and memory map flags must form a valid mmap
request, as they are not validated here.
See your system mmap
man page for details on the behaviors of each flag.
Keywords
The following keywords are available:
flags::MmapFlags
— any of theMAP_*
system-specific constants. For files, this defaults toMAP_SHARED
, and anonymous mappings default toMAP_SHARED | MAP_ANONYMOUS
.prot::MmapProtection
— any of thePROT_*
flags. The default isPROT_READ | PROT_WRITE
for all anonymous maps and memory maps of non-existent files (in which case the file will be created). If the file already exists, it is opened read-only and the default isPROT_READ
only.offset::Integer
— offset in bytes from the beginning of the file, defaulting to the current stream position. This keyword is not valid for anonymous maps.grow::Bool
— Whether to grow a file to accomodate the memory map, if the file is writable. Defaults totrue
. This keyword is not valid for anonymous maps.
UnixMmap.mincore
— Functionmincore(array::Array)
Returns a boolean array (of length fld1(sizeof(m), PAGESIZE)
) indicating whether the pages of the memory-mapped array
are resident in RAM. Pages corresponding to false
values will cause a fault if referenced.
Memory maps are always page-aligned, so an offset which is not a multiple of PAGESIZE
will result in a return array where the first element does not correspond to the first PAGESIZE ÷ sizeof(eltype(array))
elements of array
— i.e. the first page may cover memory addresses before the first element of array
.
UnixMmap.madvise!
— Functionmadvise!(array, flag::AdviseFlags = MADV_NORMAL)
Advises the kernel on the intended usage of the memory-mapped array
, with the intent flag
being one of the available MADV_*
constants.
UnixMmap.msync!
— Functionmsync!(array, flag::SyncFlags = MS_SYNC)
Synchronizes the memory-mapped array
and its backing file on disk.
OS-specific constants for use with mmap
and madvise!
are defined at (pre)compile time. The following systems are supported based on the available OS predicates via Julia's Base.Sys.KERNEL
and Base.Sys.is*
functions (some of which are only available for Julia v1.1+).
Constants — Linux
MmapProtection |
MmapFlags |
AdviseFlags |
SyncFlags |
|
|
|
|
Constants — Apple
MmapProtection |
MmapFlags |
AdviseFlags |
SyncFlags |
|
|
|
|
Constants — DragonFly BSD
MmapProtection |
MmapFlags |
AdviseFlags |
SyncFlags |
|
|
|
|
Constants — FreeBSD
MmapProtection |
MmapFlags |
AdviseFlags |
SyncFlags |
|
|
|
|
Constants — NetBSD
MmapProtection |
MmapFlags |
AdviseFlags |
SyncFlags |
|
|
|
|
Constants — OpenBSD
MmapProtection |
MmapFlags |
AdviseFlags |
SyncFlags |
|
|
|
|