Struct memmap2::MmapMut [−][src]
pub struct MmapMut { /* fields omitted */ }Expand description
A handle to a mutable memory mapped buffer.
A file-backed MmapMut buffer may be used to read from or write to a file. An anonymous
MmapMut buffer may be used any place that an in-memory byte buffer is needed. Use
MmapMut::map_mut() and MmapMut::map_anon() to create a mutable memory map of the
respective types, or MmapOptions::map_mut() and MmapOptions::map_anon() if non-default
options are required.
A file backed MmapMut is created by &File reference, and will remain valid even after the
File is dropped. In other words, the MmapMut handle is completely independent of the File
used to create it. For consistency, on some platforms this is achieved by duplicating the
underlying file handle. The memory will be unmapped when the MmapMut handle is dropped.
Dereferencing and accessing the bytes of the buffer may result in page faults (e.g. swapping the mapped pages into physical memory) though the details of this are platform specific.
See Mmap for the immutable version.
Safety
All file-backed memory map constructors are marked unsafe because of the potential for
Undefined Behavior (UB) using the map if the underlying file is subsequently modified, in or
out of process. Applications must consider the risk and take appropriate precautions when using
file-backed maps. Solutions such as file permissions, locks or process-private (e.g. unlinked)
files exist but are platform specific and limited.
Implementations
Creates a writeable memory map backed by a file.
This is equivalent to calling MmapOptions::new().map_mut(file).
Errors
This method returns an error when the underlying system call fails, which can happen for a variety of reasons, such as when the file is not open with read and write permissions.
Example
use std::fs::OpenOptions; use std::path::PathBuf; use memmap2::MmapMut; let path: PathBuf = /* path to file */ let file = OpenOptions::new() .read(true) .write(true) .create(true) .open(&path)?; file.set_len(13)?; let mut mmap = unsafe { MmapMut::map_mut(&file)? }; mmap.copy_from_slice(b"Hello, world!");
Creates an anonymous memory map.
This is equivalent to calling MmapOptions::new().len(length).map_anon().
Errors
This method returns an error when the underlying system call fails.
Flushes outstanding memory map modifications to disk.
When this method 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.
Example
use std::fs::OpenOptions; use std::io::Write; use std::path::PathBuf; use memmap2::MmapMut; let path: PathBuf = /* path to file */ let file = OpenOptions::new().read(true).write(true).create(true).open(&path)?; file.set_len(128)?; let mut mmap = unsafe { MmapMut::map_mut(&file)? }; (&mut mmap[..]).write_all(b"Hello, world!")?; mmap.flush()?;
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.
Flushes outstanding memory map modifications in the range to disk.
The offset and length must be in the bounds of the memory map.
When this method 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 memory map may be flushed as well.
Asynchronously flushes outstanding memory map modifications in the range to disk.
The offset and length must be in the bounds of the memory map.
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 memory map may be flushed as well.
Returns an immutable version of this memory mapped buffer.
If the memory map is file-backed, the file must have been opened with read permissions.
Errors
This method returns an error when the underlying system call fails, which can happen for a variety of reasons, such as when the file has not been opened with read permissions.
Example
use std::io::Write; use std::path::PathBuf; use memmap2::{Mmap, MmapMut}; let mut mmap = MmapMut::map_anon(128)?; (&mut mmap[..]).write(b"Hello, world!")?; let mmap: Mmap = mmap.make_read_only()?;
Transition the memory map to be readable and executable.
If the memory map is file-backed, the file must have been opened with execute permissions.
Errors
This method returns an error when the underlying system call fails, which can happen for a variety of reasons, such as when the file has not been opened with execute permissions.