Struct memmap::Mmap

pub struct Mmap { /* fields omitted */ }

A memory-mapped buffer.

A file-backed Mmap buffer may be used to read or write data to a file. Use Mmap::open(..) to create a file-backed memory map. An anonymous Mmap buffer may be used any place that an in-memory byte buffer is needed, and gives the added features of a memory map. Use Mmap::anonymous(..) to create an anonymous memory map.

Changes written to a memory-mapped file are not guaranteed to be durable until the memory map is flushed, or it is dropped.

use std::io::Write;
use memmap::{Mmap, Protection};

let file_mmap = Mmap::open_path("README.md", Protection::Read).unwrap();
let bytes: &[u8] = unsafe { file_mmap.as_slice() };
assert_eq!(b"# memmap", &bytes[0..8]);

let mut anon_mmap = Mmap::anonymous(4096, Protection::ReadWrite).unwrap();
unsafe { anon_mmap.as_mut_slice() }.write(b"foo").unwrap();
assert_eq!(b"foo\0\0", unsafe { &anon_mmap.as_slice()[0..5] });

Methods

impl Mmap

pub fn open(file: &File, prot: Protection) -> Result<Mmap>

Opens a file-backed memory map.

The file must be opened with read permissions, and write permissions if the supplied protection is ReadWrite. The file must not be empty.

pub fn open_path<P>(path: P, prot: Protection) -> Result<Mmap> where
    P: AsRef<Path>, 

Opens a file-backed memory map.

The file must not be empty.

pub fn open_with_offset(
    file: &File,
    prot: Protection,
    offset: usize,
    len: usize
) -> Result<Mmap>

Opens a file-backed memory map with the specified offset and length.

The file must be opened with read permissions, and write permissions if the supplied protection is ReadWrite. The file must not be empty. The length must be greater than zero.

pub fn anonymous(len: usize, prot: Protection) -> Result<Mmap>

Opens an anonymous memory map.

The length must be greater than zero.

pub fn anonymous_with_options(
    len: usize,
    prot: Protection,
    options: MmapOptions
) -> Result<Mmap>

Opens an anonymous memory map with the provided options.

The length must be greater than zero.

pub fn flush(&self) -> Result<()>

Flushes outstanding memory map modifications to disk.

When this returns with a non-error result, all outstanding changes to a file-backed memory map are guaranteed to be durably stored. The file's metadata (including last modification timestamp) may not be updated.

pub fn flush_async(&self) -> Result<()>

Asynchronously flushes outstanding memory map modifications to disk.

This method initiates flushing modified pages to durable storage, but it will not wait for the operation to complete before returning. The file's metadata (including last modification timestamp) may not be updated.

pub fn flush_range(&self, offset: usize, len: usize) -> Result<()>

Flushes outstanding memory map modifications in the range to disk.

The offset and length must be in the bounds of the mmap.

When this returns with a non-error result, all outstanding changes to a file-backed memory in the range are guaranteed to be durable stored. The file's metadata (including last modification timestamp) may not be updated. It is not guaranteed the only the changes in the specified range are flushed; other outstanding changes to the mmap may be flushed as well.

pub fn flush_async_range(&self, offset: usize, len: usize) -> Result<()>

Asynchronously flushes outstanding memory map modifications in the range to disk.

The offset and length must be in the bounds of the mmap.

This method initiates flushing modified pages to durable storage, but it will not wait for the operation to complete before returning. The file's metadata (including last modification timestamp) may not be updated. It is not guaranteed that the only changes flushed are those in the specified range; other outstanding changes to the mmap may be flushed as well.

pub fn set_protection(&mut self, prot: Protection) -> Result<()>

Change the Protection this mapping was created with.

If you create a read-only file-backed mapping, you can not use this method to make the mapping writeable. Remap the file instead.

pub fn len(&self) -> usize

Returns the length of the memory map.

pub fn ptr(&self) -> *const u8

Returns a pointer to the mapped memory.

See Mmap::as_slice for invariants that must hold when dereferencing the pointer.

pub fn mut_ptr(&mut self) -> *mut u8

Returns a pointer to the mapped memory.

See Mmap::as_mut_slice for invariants that must hold when dereferencing the pointer.

pub unsafe fn as_slice(&self) -> &[u8]

Returns the memory mapped file as an immutable slice.

Unsafety

The caller must ensure that the file is not concurrently modified.

pub unsafe fn as_mut_slice(&mut self) -> &mut [u8]

Returns the memory mapped file as a mutable slice.

Unsafety

The caller must ensure that the file is not concurrently accessed.

pub fn into_view(self) -> MmapView

Creates a splittable mmap view from the mmap.

pub fn into_view_sync(self) -> MmapViewSync

Creates a thread-safe splittable mmap view from the mmap.

Trait Implementations

impl Debug for Mmap

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.