Struct AsyncOptions 

pub struct AsyncOptions { /* private fields */ }

Available on crate feature smol only.

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

Implementations

impl AsyncOptions

pub fn new() -> Self

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

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

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

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

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

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

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

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

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

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

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

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

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

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 AsyncOptions

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

Create a new file and mmap this file with AsyncOptions

Example

use fmmap::smol::{AsyncOptions, AsyncMmapFileMut, AsyncMmapFileExt, AsyncMmapFileMutExt};

 let mut file = AsyncOptions::new()
     // truncate to 100
     .max_size(100)
.create_mmap_file_mut("smol_async_create_with_options_test.txt").await.unwrap();
 assert!(!file.is_empty());
 file.write_all("some data...".as_bytes(), 0).unwrap();
 file.flush().unwrap();

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

Open a readable memory map backed by a file with [Options]

Example

use fmmap::smol::{AsyncOptions, AsyncMmapFile, AsyncMmapFileExt};


 // mmap the file
 let file = AsyncOptions::new()
     // mmap content after the sanity text
     .offset("sanity text".as_bytes().len() as u64)
.open_mmap_file("smol_async_open_with_options_test.txt").await.unwrap();
 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());

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

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

Examples

use fmmap::smol::{AsyncOptions, AsyncMmapFile, AsyncMmapFileExt};


 // mmap the file
 let file = AsyncOptions::new()
     // mmap content after the sanity text
     .offset("sanity text".as_bytes().len() as u64)
.open_exec_mmap_file("smol_async_open_exec_with_options_test.txt").await.unwrap();
 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());

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

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

Examples

File already exists

use fmmap::smol::{AsyncMmapFileMut, AsyncMmapFileExt, AsyncMmapFileMutExt, AsyncOptions};


let mut file = AsyncOptions::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("smol_async_open_with_options_test.txt").await.unwrap();
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.truncate(("some modified data...".len() + "sanity text".len()) as u64).await.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 = AsyncMmapFileMut::open("smol_async_open_with_options_test.txt").await.unwrap();
// skip the sanity text
file.read_exact(buf.as_mut_slice(), "sanity text".as_bytes().len()).unwrap();
assert_eq!(buf.as_slice(), "some modified data...".as_bytes());

File does not exists

use fmmap::smol::{AsyncMmapFileMut, AsyncMmapFileExt, AsyncMmapFileMutExt, AsyncOptions};

// mmap the file with options
let mut file = AsyncOptions::new()
    // allow read
    .read(true)
    // allow write
    .write(true)
    // allow append
    .append(true)
    // truncate to 100
    .max_size(100)
.open_mmap_file_mut("smol_async_open_with_options_test.txt").await.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).unwrap();
assert_eq!(buf.as_slice(), "some data...".as_bytes());

// modify the file data
file.truncate("some modified data...".len() as u64).await.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 = AsyncMmapFileMut::open("smol_async_open_with_options_test.txt").await.unwrap();
file.read_exact(buf.as_mut_slice(), 0).unwrap();
assert_eq!(buf.as_slice(), "some modified data...".as_bytes());

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

Open an existing file and mmap this file with AsyncOptions

Example

use fmmap::smol::{AsyncMmapFileMut, AsyncMmapFileExt, AsyncMmapFileMutExt, AsyncOptions};

// create a temp file
let mut file = AsyncMmapFileMut::create("smol_async_open_existing_test_with_options.txt").await.unwrap();
file.truncate(23).await.unwrap();
file.write_all("sanity text".as_bytes(), 0).unwrap();
file.write_all("some data...".as_bytes(), "sanity text".as_bytes().len()).unwrap();
file.flush().unwrap();
drop(file);

// mmap the file
let mut file = AsyncOptions::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("smol_async_open_existing_test_with_options.txt").await.unwrap();

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.truncate(("some modified data...".len() + "sanity text".len()) as u64).await.unwrap();
file.write_all("some modified data...".as_bytes(), 0).unwrap();
file.flush().unwrap();

// reopen to check content, cow will not change the content.
let mut file = AsyncMmapFileMut::open("smol_async_open_existing_test_with_options.txt").await.unwrap();
let mut buf = vec![0; "some modified data...".len()];
// skip the sanity text
file.read_exact(buf.as_mut_slice(), "sanity text".as_bytes().len()).unwrap();
assert_eq!(buf.as_slice(), "some modified data...".as_bytes());

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

Open and mmap an existing file in copy-on-write mode(copy-on-write memory map backed by a file) with AsyncOptions. 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::smol::{AsyncMmapFileMut, AsyncMmapFileExt, AsyncMmapFileMutExt, AsyncOptions};

 // create a temp file
let mut file = AsyncMmapFileMut::create("smol_async_open_cow_with_options_test.txt").await.unwrap();
 file.truncate(23).await.unwrap();
 file.write_all("sanity text".as_bytes(), 0).unwrap();
 file.write_all("some data...".as_bytes(), "sanity text".as_bytes().len()).unwrap();
 file.flush().unwrap();
 drop(file);

 // mmap the file
 let mut file = AsyncOptions::new()
     // mmap content after the sanity text
     .offset("sanity text".as_bytes().len() as u64)
.open_cow_mmap_file_mut("smol_async_open_cow_with_options_test.txt").await.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 = AsyncMmapFileMut::open("smol_async_open_cow_with_options_test.txt").await.unwrap();
 let mut buf = vec![0; "some data...".len()];
 // skip the sanity text
 file.read_exact(buf.as_mut_slice(), "sanity text".as_bytes().len()).unwrap();
 assert_eq!(buf.as_slice(), "some data...".as_bytes());

impl AsyncOptions

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

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

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

Pass custom flags to the flags argument of open.

Trait Implementations

impl Clone for AsyncOptions

fn clone(&self) -> AsyncOptions

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Default for AsyncOptions

fn default() -> Self

Returns the “default value” for a type.