Mmap (Memory-mapped I/O) · The Julia Language
Description: Documentation for The Julia Language.

# Mmap (Memory-mapped I/O)

Low level module for mmap (memory mapping of files).

`Mmap.SharedMemory` — Type

    Mmap.SharedMemory

A `IO`-like object representing a shared memory region. It is used by `mmap` to support memory-mapping of shared memory.

This type should not be constructed directly; instead, use `open(SharedMemory, name, size; readonly, create)`, which opens a shared memory region and returns the corresponding `SharedMemory` object.

If `name` is empty, the region will be anonymous. If a name is provided and `create` is `true`, the attempt to open will fail if a shared memory region with the same name already exists.

SharedMemory size cannot be grown after creation, though smaller regions can be mmapped within it. Each SharedMemory may only be mmapped a single time.

MacOS does not guarantee allocation

On Windows and Linux, shared memory creation fails if the system does not have enough memory available. This is not possible on MacOS, which defers final allocation of memory until it is accessed. Therefore, on MacOS, creation of a large shared memory region will always succeed, but accessing it may trigger the system out-of-memory killer.

Mmapping a reopened named shared memory segments with larger size

Windows and MacOS shared memory segments are natively rounded up to multiples of the system page size. The SharedMemory object will not reflect this, but reopening a named shared memory segment with a size larger than initially requested but less than the page boundary will succeed. On Linux, the size is strictly enforced. Failure due to size will occur in `mmap`, not in `open`.

source
`Mmap.mmap` — Function

    mmap(io::Union{IOStream,AbstractString,Mmap.SharedMemory}[, type::Type{Array{T,N}}, dims, offset]; grow::Bool=true, shared::Bool=true)
    mmap(type::Type{Array{T,N}}, dims)

Create an `Array` whose values are linked to a file, using memory-mapping. This provides a convenient way of working with data too large to fit in the computer's memory.

The type is an `Array{T,N}` with a bits-type element of `T` and dimension `N` that determines how the bytes of the array are interpreted. Note that the file must be stored in binary format, and no format conversions are possible (this is a limitation of operating systems, not Julia).

`dims` is a tuple or single `Integer` specifying the size or length of the array.

The file is passed via the stream argument, either as an open `IOStream` or filename string. When you initialize the stream, use `"r"` for a "read-only" array, and `"w+"` to create a new array used to write values to disk.

If no `type` argument is specified, the default is `Vector{UInt8}`.

Optionally, you can specify an offset (in bytes) if, for example, you want to skip over a header in the file. The default value for the offset is the current stream position for an `IOStream`.

The `grow` keyword argument specifies whether the disk file should be grown to accommodate the requested size of array (if the total file size is < requested array size). Write privileges are required to grow the file.

The `shared` keyword argument specifies whether the resulting `Array` and changes made to it will be visible to other processes mapping the same file.

For example, the following code

    # Create a file for mmapping
    # (you could alternatively use mmap to do this step, too)
    using Mmap
    A = rand(1:20, 5, 30)
    s = open("/tmp/mmap.bin", "w+")
    # We'll write the dimensions of the array as the first two Ints in the file
    write(s, size(A,1))
    write(s, size(A,2))
    # Now write the data
    write(s, A)
    close(s)

    # Test by reading it back in
    s = open("/tmp/mmap.bin")   # default is read-only
    m = read(s, Int)
    n = read(s, Int)
    A2 = mmap(s, Matrix{Int}, (m,n))

creates a `m`-by-`n` `Matrix{Int}`, linked to the file associated with stream `s`.

A more portable file would need to encode the word size – 32 bit or 64 bit – and endianness information in the header. In practice, consider encoding binary data using standard formats like HDF5 (which can be used with memory-mapping).

source

    mmap(io, BitArray, [dims, offset])

Create a `BitArray` whose values are linked to a file, using memory-mapping; it has the same purpose, works in the same way, and has the same arguments, as `mmap`, but the byte representation is different.

Examples

    julia> using Mmap

    julia> io = open("mmap.bin", "w+");

    julia> B = mmap(io, BitArray, (25,30000));

    julia> B[3, 4000] = true;

    julia> Mmap.sync!(B);

    julia> close(io);

    julia> io = open("mmap.bin", "r+");

    julia> C = mmap(io, BitArray, (25,30000));

    julia> C[3, 4000]
    true

    julia> C[2, 4000]
    false

    julia> close(io)

    julia> rm("mmap.bin")

This creates a 25-by-30000 `BitArray`, linked to the file associated with stream `io`.

source
`Mmap.sync!` — Function

    Mmap.sync!(array)

Forces synchronization between the in-memory version of a memory-mapped `Array` or `BitArray` and the on-disk version.

source

Theme

This document was generated with Documenter.jl version 1.17.0 on Saturday 29 August 2026. Using Julia version 1.14.0-DEV.3067.