Struct vmap::MapMut

pub struct MapMut { /* fields omitted */ }

Allocation of one or more read-write sequential pages.

Methods

impl MapMut

pub fn new(hint: usize) -> Result<Self>

Create a new anonymous mapping at least as large as the hint.

Example

use vmap::MapMut;
use std::io::Write;

let mut map = MapMut::new(200)?;
{
    let mut data = &mut map[..];
    assert!(data.len() >= 200);
    data.write_all(b"test")?;
}
assert_eq!(b"test", &map[..4]);

pub fn file(f: &File, offset: usize, length: usize) -> Result<Self>

Create a new mutable map object from a range of a file.

pub unsafe fn file_unchecked(
    f: &File,
    offset: usize,
    length: usize
) -> Result<Self>

Create a new mutable map object from a range of a file without bounds checking.

Safety

This does not verify that the requsted range is valid for the file. This can be useful in a few scenarios:

1. When the range is already known to be valid.
2. When a valid sub-range is known and not exceeded.
3. When the range will become valid and is not used until then.

pub fn copy(f: &File, offset: usize, length: usize) -> Result<Self>

Create a new private map object from a range of a file.

Initially, the mapping will be shared with other processes, but writes will be kept private.

Example

use vmap::MapMut;
use std::io::Write;
use std::fs::OpenOptions;

let file = OpenOptions::new().read(true).open("src/lib.rs")?;
let mut map = MapMut::copy(&file, 33, 30)?;
assert_eq!(map.is_empty(), false);
assert_eq!(b"fast and safe memory-mapped IO", &map[..]);
{
    let mut data = &mut map[..];
    data.write_all(b"slow")?;
}
assert_eq!(b"slow and safe memory-mapped IO", &map[..]);

pub unsafe fn copy_unchecked(
    f: &File,
    offset: usize,
    length: usize
) -> Result<Self>

Create a new private map object from a range of a file without bounds checking.

Initially, the mapping will be shared with other processes, but writes will be kept private.

Safety

This does not verify that the requsted range is valid for the file. This can be useful in a few scenarios:

1. When the range is already known to be valid.
2. When a valid sub-range is known and not exceeded.
3. When the range will become valid before any write occurs.

pub unsafe fn from_ptr(ptr: *mut u8, len: usize) -> Self

Constructs a new map object from an existing mapped pointer.

Safety

This does not know or care if ptr or len are valid. That is, it may be null, not at a proper page boundary, point to a size different from len, or worse yet, point to a properly mapped pointer from some other allocation system.

Generally don't use this unless you are entirely sure you are doing so correctly.

Example

use vmap::{MapMut, Protect};
use std::fs::{self, OpenOptions};
use std::path::PathBuf;

let path: PathBuf = /* path to file */
let file = OpenOptions::new().read(true).open("src/lib.rs")?;
let page = unsafe {
    let len = vmap::allocation_size();
    let ptr = vmap::os::map_file(&file, 0, len, Protect::ReadOnly)?;
    MapMut::from_ptr(ptr, len)
};
assert_eq!(b"fast and safe memory-mapped IO", &page[33..63]);

pub fn make_read_only(self) -> Result<Map>

Transfer ownership of the map into a mutable map.

This will change the protection of the mapping. If the original file was not opened with write permissions, this will error.

Example

use vmap::MapMut;
use std::io::Write;
use std::fs::OpenOptions;
use std::path::PathBuf;

let path: PathBuf = /* path to file */
let file = OpenOptions::new().read(true).write(true).open(&path)?;

let mut map = MapMut::file(&file, 0, 14)?;
assert_eq!(b"this is a test", &map[..]);
{
    let mut data = &mut map[..];
    data.write_all(b"that")?;
}

let map = map.make_read_only()?;
assert_eq!(b"that is a test", &map[..]);

pub fn flush(&self, file: &File, mode: Flush) -> Result<()>

Writes modifications back to the filesystem.

Flushes will happen automatically, but this will invoke a flush and return any errors with doing so.

pub fn len(&self) -> usize

Get the length of the allocated region.

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

Get the pointer to the start of the allocated region.

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

Get a mutable pointer to the start of the allocated region.

pub fn advise(&self, access: AdviseAccess, usage: AdviseUsage) -> Result<()>

Updates the advise for the entire mapped region..

pub fn advise_range(
    &self,
    off: usize,
    len: usize,
    access: AdviseAccess,
    usage: AdviseUsage
) -> Result<()>

Updates the advise for a specific range of the mapped region.

Trait Implementations

impl Drop for MapMut

fn drop(&mut self)

Executes the destructor for this type.

impl AsMut<[u8]> for MapMut

fn as_mut(&mut self) -> &mut [u8]

Performs the conversion.

impl AsRef<[u8]> for MapMut

fn as_ref(&self) -> &[u8]

Performs the conversion.

impl DerefMut for MapMut

fn deref_mut(&mut self) -> &mut [u8]

Mutably dereferences the value.

impl Deref for MapMut

type Target = [u8]

The resulting type after dereferencing.

fn deref(&self) -> &[u8]

Dereferences the value.

impl Debug for MapMut

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

Formats the value using the given formatter.