Struct fmmap::Options

pub struct Options { /* private fields */ }

A memory map builder, providing advanced options and flags for specifying memory map file behavior.

Implementations

impl Options

pub fn new() -> Self

Available on crate feature sync only.

Creates a new set of options for configuring and creating a memory map.

pub fn offset(self, offset: u64) -> Self

Available on crate feature sync only.

Configures the memory map to start at byte offset from the beginning of the file. This option has no effect on anonymous memory maps. By default, the offset is 0.

pub fn len(self, len: usize) -> Self

Available on crate feature sync only.

Configures the created memory mapped buffer to be len bytes long. This option is mandatory for anonymous memory maps. For file-backed memory maps, the length will default to the file length.

pub fn populate(self) -> Self

Available on crate feature sync only.

Populate (prefault) page tables for a mapping. For a file mapping, this causes read-ahead on the file. This will help to reduce blocking on page faults later. This option corresponds to the MAP_POPULATE flag on Linux. It has no effect on Windows

pub fn stack(self) -> Self

Available on crate feature sync only.

Configures the anonymous memory map to be suitable for a process or thread stack. This option corresponds to the MAP_STACK flag on Linux. It has no effect on Windows. This option has no effect on file-backed memory maps

pub fn max_size(self, max_sz: u64) -> Self

Available on crate feature sync only.

Configures the max size of the file.

This option only has effect when mmaping a real file in write mode.

This field is ignored when opening DiskMmapFile, AsyncDiskMmapFile, MmapFile and AsyncMmapFile.

pub fn read(self, val: bool) -> Self

Available on crate feature sync only.

Sets the option for read access. For details, please see std::fs::OpenOptions::read

pub fn write(self, val: bool) -> Self

Available on crate feature sync only.

Sets the option for write access. For details, please see std::fs::OpenOptions::write.

This field is ignored when opening DiskMmapFile, AsyncDiskMmapFile, MmapFile and AsyncMmapFile.

pub fn create(self, val: bool) -> Self

Available on crate feature sync only.

Sets the option to create a new file, or open it if it already exists. For details, please see std::fs::OpenOptions::create.

This field is ignored when opening DiskMmapFile, AsyncDiskMmapFile, MmapFile and AsyncMmapFile.

pub fn create_new(self, val: bool) -> Self

Available on crate feature sync only.

Sets the option to create a new file, failing if it already exists. For details, please see std::fs::OpenOptions::create_new

This field is ignored when opening DiskMmapFile, AsyncDiskMmapFile, MmapFile and AsyncMmapFile.

pub fn append(self, val: bool) -> Self

Available on crate feature sync only.

Sets the option for the append mode. For details, please see std::fs::OpenOptions::append

This field is ignored when opening DiskMmapFile, AsyncDiskMmapFile, MmapFile and AsyncMmapFile.

pub fn truncate(self, val: bool) -> Self

Available on crate feature sync only.

Sets the option for truncating a previous file. For details, please see std::fs::OpenOptions::truncate

This field is ignored when opening DiskMmapFile, AsyncDiskMmapFile, MmapFile and AsyncMmapFile.

impl Options

pub fn mode(self, mode: u32) -> Self

Available on crate feature sync only.

Sets the mode bits that a new file will be created with.

pub fn custom_flags(self, flags: i32) -> Self

Available on crate feature sync only.

Pass custom flags to the flags argument of open.

impl Options

pub fn create_mmap_file_mut<P: AsRef<Path>>(
    self,
    path: P
) -> Result<MmapFileMut, Error>

Available on crate feature sync only.

Create a new file and mmap this file with Options

Examples

use fmmap::{Options, MmapFileMut, MmapFileMutExt, MmapFileExt};

let mut file = Options::new().max_size(100).create_mmap_file_mut("create_with_options_test.txt").unwrap();
assert!(!file.is_empty());

file.write_all("some data...".as_bytes(), 0).unwrap();
file.flush().unwrap();

pub fn open_mmap_file<P: AsRef<Path>>(self, path: P) -> Result<MmapFile, Error>

Available on crate feature sync only.

Open a readable memory map backed by a file with Options

Examples

use fmmap::{Options, MmapFile, MmapFileExt};


// open and mmap the file
let file = Options::new()
    // allow read
    .read(true)
    // allow write
    .write(true)
    // allow append
    .append(true)
    // truncate to 100
    .max_size(100)
    // mmap content after the sanity text
    .offset("sanity text".as_bytes().len() as u64)
    .open_mmap_file("open_test_with_options.txt")
    .unwrap();

let mut buf = vec![0; "some data...".len()];
file.read_exact(buf.as_mut_slice(), 0);
assert_eq!(buf.as_slice(), "some data...".as_bytes());

pub fn open_exec_mmap_file<P: AsRef<Path>>(
    self,
    path: P
) -> Result<MmapFile, Error>

Available on crate feature sync only.

Open a readable and executable memory map backed by a file with Options.

Examples

use fmmap::{Options, MmapFile, MmapFileExt};


// open and mmap the file
let file = Options::new()
    // allow read
    .read(true)
    // mmap content after the sanity text
    .offset("sanity text".as_bytes().len() as u64)
    .open_exec_mmap_file("exec_mmap_file.txt")
    .unwrap();
let mut buf = vec![0; "some data...".len()];
file.read_exact(buf.as_mut_slice(), 0);
assert_eq!(buf.as_slice(), "some data...".as_bytes());

pub fn open_mmap_file_mut<P: AsRef<Path>>(
    self,
    path: P
) -> Result<MmapFileMut, Error>

Available on crate feature sync only.

Open or Create(if not exists) a file and mmap this file with Options.

Examples

File already exists

use fmmap::{MmapFileMut, MmapFileExt, MmapFileMutExt, Options};
use std::fs::File;
use std::io::{Read, Seek, SeekFrom, Write};


// mmap the file with options
let mut file = Options::new()
    // allow read
    .read(true)
    // allow write
    .write(true)
    // allow append
    .append(true)
    // truncate to 100
    .max_size(100)
    // mmap content after the sanity text
    .offset("sanity text".as_bytes().len() as u64)
    .open_mmap_file_mut("mmap_file_mut.txt")
    .unwrap();
let mut buf = vec![0; "some data...".len()];
file.read_exact(buf.as_mut_slice(), 0);
assert_eq!(buf.as_slice(), "some data...".as_bytes());

// modify the file data
file.truncate(("some modified data...".len() + "sanity text".len()) as u64).unwrap();
file.write_all("some modified data...".as_bytes(), 0).unwrap();
file.flush().unwrap();
drop(file);

// reopen to check content
let mut buf = vec![0; "some modified data...".len()];
let mut file = File::open("mmap_file_mut.txt").unwrap();
file.seek(SeekFrom::Start("sanity text".as_bytes().len() as u64)).unwrap();
file.read_exact(buf.as_mut_slice()).unwrap();
assert_eq!(buf.as_slice(), "some modified data...".as_bytes());

File does not exists

use fmmap::{MmapFileMut, MmapFileExt, MmapFileMutExt, Options};
use std::fs::File;
use std::io::{Read, Write};

// mmap the file with options
let mut file = Options::new()
    // allow read
    .read(true)
    // allow write
    .write(true)
    // allow append
    .append(true)
    // truncate to 100
    .max_size(100)
    .open_mmap_file_mut("mmap_file_mut.txt")
    .unwrap();

file.write_all("some data...".as_bytes(), 0).unwrap();

let mut buf = vec![0; "some data...".len()];
file.read_exact(buf.as_mut_slice(), 0);
assert_eq!(buf.as_slice(), "some data...".as_bytes());

// modify the file data
file.truncate("some modified data...".len() as u64).unwrap();
file.write_all("some modified data...".as_bytes(), 0).unwrap();
file.flush().unwrap();
drop(file);

// reopen to check content
let mut buf = vec![0; "some modified data...".len()];
let mut file = File::open("mmap_file_mut.txt").unwrap();
file.read_exact(buf.as_mut_slice()).unwrap();
assert_eq!(buf.as_slice(), "some modified data...".as_bytes());

pub fn open_exist_mmap_file_mut<P: AsRef<Path>>(
    self,
    path: P
) -> Result<MmapFileMut, Error>

Available on crate feature sync only.

Open an existing file and mmap this file with Options

Examples

use fmmap::{MmapFileMut, MmapFileExt, MmapFileMutExt, Options};
use std::fs::File;
use std::io::{Read, Seek, SeekFrom, Write};

// create a temp file
let mut file = File::create("exist_mmap_file_mut.txt").unwrap();
file.write_all("sanity text".as_bytes()).unwrap();
file.write_all("some data...".as_bytes()).unwrap();
drop(file);

// mmap the file with options
let mut file = Options::new()
    // truncate to 100
    .max_size(100)
    // mmap content after the sanity text
    .offset("sanity text".as_bytes().len() as u64)
    .open_exist_mmap_file_mut("exist_mmap_file_mut.txt")
    .unwrap();
let mut buf = vec![0; "some data...".len()];
file.read_exact(buf.as_mut_slice(), 0);
assert_eq!(buf.as_slice(), "some data...".as_bytes());

// modify the file data
file.truncate(("some modified data...".len() + "sanity text".len()) as u64).unwrap();
file.write_all("some modified data...".as_bytes(), 0).unwrap();
file.flush().unwrap();
drop(file);

// reopen to check content
let mut buf = vec![0; "some modified data...".len()];
let mut file = File::open("exist_mmap_file_mut.txt").unwrap();
file.seek(SeekFrom::Start("sanity text".as_bytes().len() as u64)).unwrap();
file.read_exact(buf.as_mut_slice()).unwrap();
assert_eq!(buf.as_slice(), "some modified data...".as_bytes());

pub fn open_cow_mmap_file_mut<P: AsRef<Path>>(
    self,
    path: P
) -> Result<MmapFileMut, Error>

Available on crate feature sync only.

Open and mmap an existing file in copy-on-write mode(copy-on-write memory map backed by a file) with Options. Data written to the memory map will not be visible by other processes, and will not be carried through to the underlying file.

Examples

use fmmap::{MmapFileMut, MmapFileExt, MmapFileMutExt, Options};
use std::fs::File;
use std::io::{Read, Seek, Write, SeekFrom};

// create a temp file
let mut file = File::create("cow_mmap_file_mut.txt").unwrap();
file.write_all("sanity text".as_bytes()).unwrap();
file.write_all("some data...".as_bytes()).unwrap();
drop(file);

// mmap the file with options
let mut file = Options::new()
    // mmap content after the sanity text
    .offset("sanity text".as_bytes().len() as u64)
    .open_cow_mmap_file_mut("cow_mmap_file_mut.txt")
    .unwrap();
assert!(file.is_cow());

let mut buf = vec![0; "some data...".len()];
file.read_exact(buf.as_mut_slice(), 0).unwrap();
assert_eq!(buf.as_slice(), "some data...".as_bytes());

// modify the file data
file.write_all("some data!!!".as_bytes(), 0).unwrap();
file.flush().unwrap();

// cow, change will only be seen in current caller
assert_eq!(file.as_slice(), "some data!!!".as_bytes());
drop(file);

// reopen to check content, cow will not change the content.
let mut file = File::open("cow_mmap_file_mut.txt").unwrap();
let mut buf = vec![0; "some data...".len()];
// skip the sanity text
file.seek(SeekFrom::Start("sanity text".as_bytes().len() as u64)).unwrap();
file.read_exact(buf.as_mut_slice()).unwrap();
assert_eq!(buf.as_slice(), "some data...".as_bytes());

Trait Implementations

impl Clone for Options

Available on crate feature sync only.

fn clone(&self) -> Options

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for Options

Available on crate feature sync only.

fn default() -> Self

Returns the “default value” for a type.