Struct memmap2::MmapRaw

source ·
pub struct MmapRaw { /* private fields */ }
Expand description

A handle to a raw memory mapped buffer.

This struct never hands out references to its interior, only raw pointers. This can be helpful when creating shared memory maps between untrusted processes.

Implementations§

source§

impl MmapRaw

source

pub fn map_raw<T: MmapAsRawDesc>(file: T) -> Result<MmapRaw>

Creates a writeable memory map backed by a file.

This is equivalent to calling MmapOptions::new().map_raw(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.

source

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

Returns a raw pointer to the memory mapped file.

Before dereferencing this pointer, you have to make sure that the file has not been truncated since the memory map was created. Avoiding this will not introduce memory safety issues in Rust terms, but will cause SIGBUS (or equivalent) signal.

source

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

Returns an unsafe mutable pointer to the memory mapped file.

Before dereferencing this pointer, you have to make sure that the file has not been truncated since the memory map was created. Avoiding this will not introduce memory safety issues in Rust terms, but will cause SIGBUS (or equivalent) signal.

source

pub fn len(&self) -> usize

Returns the length in bytes of the memory map.

Note that truncating the file can cause the length to change (and render this value unusable).

source

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

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 std::slice;

use memmap2::MmapRaw;

let tempdir = tempfile::tempdir()?;
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 { MmapRaw::map_raw(&file)? };

let mut memory = unsafe { slice::from_raw_parts_mut(mmap.as_mut_ptr(), 128) };
memory.write_all(b"Hello, world!")?;
mmap.flush()?;
source

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.

source

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 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.

source

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 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.

source

pub fn advise(&self, advice: Advice) -> Result<()>

Advise OS how this memory map will be accessed.

Only supported on Unix.

See madvise() map page.

source

pub unsafe fn unchecked_advise(&self, advice: UncheckedAdvice) -> Result<()>

Advise OS how this memory map will be accessed.

Used with the unchecked flags. Only supported on Unix.

See madvise() map page.

source

pub fn advise_range( &self, advice: Advice, offset: usize, len: usize ) -> Result<()>

Advise OS how this range of memory map will be accessed.

The offset and length must be in the bounds of the memory map.

Only supported on Unix.

See madvise() map page.

source

pub unsafe fn unchecked_advise_range( &self, advice: UncheckedAdvice, offset: usize, len: usize ) -> Result<()>

Advise OS how this range of memory map will be accessed.

Used with the unchecked flags. Only supported on Unix.

The offset and length must be in the bounds of the memory map.

See madvise() map page.

source

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

Lock the whole memory map into RAM. Only supported on Unix.

See mlock() map page.

source

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

Unlock the whole memory map. Only supported on Unix.

See munlock() map page.

source

pub unsafe fn remap( &mut self, new_len: usize, options: RemapOptions ) -> Result<()>

Adjust the size of the memory mapping.

This will try to resize the memory mapping in place. If RemapOptions::may_move is specified it will move the mapping if it could not resize in place, otherwise it will error.

Only supported on Linux.

See the mremap(2) man page.

Safety

Resizing the memory mapping beyond the end of the mapped file will result in UB should you happen to access memory beyond the end of the file.

Trait Implementations§

source§

impl Debug for MmapRaw

source§

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
source§

impl From<Mmap> for MmapRaw

source§

fn from(value: Mmap) -> Self

Converts to this type from the input type.
source§

impl From<MmapMut> for MmapRaw

source§

fn from(value: MmapMut) -> Self

Converts to this type from the input type.

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.