Struct vmap::Map

pub struct Map { /* fields omitted */ }

Allocation of one or more read-only sequential pages.

Example

use vmap::{Map, AdviseAccess, AdviseUsage};
use std::fs::OpenOptions;

let file = OpenOptions::new().read(true).open("README.md")?;
let page = Map::file(&file, 113, 30)?;
page.advise(AdviseAccess::Sequential, AdviseUsage::WillNeed)?;
assert_eq!(b"fast and safe memory-mapped IO", &page[..]);
assert_eq!(b"safe", &page[9..13]);

Implementations

impl Map

pub fn open<P: AsRef<Path>>(path: P) -> Result<Self>

Creates a new read-only map object using the full range of a file.

Example

use std::fs::OpenOptions;
use vmap::Map;

let map = Map::open("README.md")?;
assert_eq!(map.is_empty(), false);
assert_eq!(b"fast and safe memory-mapped IO", &map[113..143]);

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

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

Example

use std::fs::OpenOptions;
use vmap::Map;

let file = OpenOptions::new().read(true).open("README.md")?;
let map = Map::file(&file, 0, 143)?;
assert_eq!(map.is_empty(), false);
assert_eq!(b"fast and safe memory-mapped IO", &map[113..143]);

let map = Map::file(&file, 0, file.metadata()?.len() as usize + 1);
assert!(map.is_err());

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

Create a new 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.

Example

use std::fs::OpenOptions;
use vmap::Map;

let file = OpenOptions::new().read(true).open("README.md")?;
let map = unsafe {
    Map::file_unchecked(&file, 0, file.metadata()?.len() as usize + 1)?
};
// It is safe read the valid range of the file.
assert_eq!(b"fast and safe memory-mapped IO", &map[113..143]);

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

Constructs a new mutable 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::{Map, Protect};
use std::fs::OpenOptions;

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)?;
    Map::from_ptr(ptr, len)
};
assert_eq!(b"fast and safe memory-mapped IO", &page[33..63]);

pub fn make_mut(self) -> Result<MapMut>

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::Map;
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)?;

// Map the beginning of the file
let map = Map::file(&file, 0, 14)?;
assert_eq!(b"this is a test", &map[..]);

let mut map = map.make_mut()?;
{
    let mut data = &mut map[..];
    data.write_all(b"that")?;
}
assert_eq!(b"that is a test", &map[..]);

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

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

Lock all mapped physical pages into memory.

pub fn lock_range(&self, off: usize, len: usize) -> Result<()>

Lock a range of physical pages into memory.

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

Unlock all mapped physical pages into memory.

pub fn unlock_range(&self, off: usize, len: usize) -> Result<()>

Unlock a range of physical pages into memory.

Trait Implementations

impl AsRef<[u8]> for Map

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

Performs the conversion.

impl Debug for Map

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

Formats the value using the given formatter.

impl Deref for Map

type Target = [u8]

The resulting type after dereferencing.

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

Dereferences the value.