Struct fmmap::sync::MmapFile

#[repr(transparent)]
pub struct MmapFile { /* private fields */ }

Available on crate feature sync only.

A read-only memory map file.

There is 3 status of this struct:

• Disk: mmap to a real file
• Memory: use Bytes to mock a mmap, which is useful for test and in-memory storage engine
• Empty: a state represents null mmap, which is helpful for drop, close the MmapFile. This state cannot be constructed directly.

Implementations

impl MmapFile

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

Open a readable memory map backed by a file

Examples

use fmmap::{MmapFile, MmapFileExt};
use std::fs::{remove_file, File};
use std::io::Write;
# use scopeguard::defer;

# let mut file = File::create("open_test.txt").unwrap();
# defer!(remove_file("open_test.txt").unwrap());
# file.write_all("some data...".as_bytes()).unwrap();
# drop(file);

// open and mmap the file
let mut file = MmapFile::open("open_test.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_with_options<P: AsRef<Path>>(path: P, opts: Options) -> Result<Self>

Open a readable memory map backed by a file with Options

Examples

use fmmap::{Options, MmapFile, MmapFileExt};
# use scopeguard::defer;

# let mut file = std::fs::File::create("open_test_with_options.txt").unwrap();
# defer!(std::fs::remove_file("open_test_with_options.txt").unwrap());
# std::io::Write::write_all(&mut file, "sanity text".as_bytes()).unwrap();
# std::io::Write::write_all(&mut file, "some data...".as_bytes()).unwrap();
# drop(file);

// mmap the file with options
let opts = 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 and mmap the file
let mut file = MmapFile::open_with_options("open_test_with_options.txt", opts).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<P: AsRef<Path>>(path: P) -> Result<Self>

Open a readable memory map backed by a file

Examples

use fmmap::{MmapFile, MmapFileExt};
use std::fs::{remove_file, File};
use std::io::Write;
# use scopeguard::defer;

# let mut file = File::create("open_exec_test.txt").unwrap();
# defer!(remove_file("open_exec_test.txt").unwrap());
# file.write_all("some data...".as_bytes()).unwrap();
# drop(file);

// open and mmap the file
let mut file = MmapFile::open_exec("open_exec_test.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_with_options<P: AsRef<Path>>( path: P, opts: Options ) -> Result<Self>

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

Examples

use fmmap::{Options, MmapFile, MmapFileExt};
# use scopeguard::defer;

# let mut file = std::fs::File::create("open_exec_test_with_options.txt").unwrap();
# defer!(std::fs::remove_file("open_exec_test_with_options.txt").unwrap());
# std::io::Write::write_all(&mut file, "sanity text".as_bytes()).unwrap();
# std::io::Write::write_all(&mut file, "some data...".as_bytes()).unwrap();
# drop(file);

// mmap the file with options
let opts = Options::new()
    // allow read
    .read(true)
    // mmap content after the sanity text
    .offset("sanity text".as_bytes().len() as u64);
// open and mmap the file
let mut file = MmapFile::open_exec_with_options("open_exec_test_with_options.txt", opts).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());

impl MmapFile

pub fn memory<P: AsRef<Path>>(path: P, data: Bytes) -> Self

Create a in-memory MmapFile

Examples

use bytes::{BufMut, BytesMut};
use fmmap::sync::MmapFile;

let mut data = BytesMut::with_capacity(100);
data.put_slice("some data...".as_bytes());
MmapFile::memory("foo.mem", data.freeze());

pub fn memory_from_vec<P: AsRef<Path>>(path: P, src: Vec<u8>) -> Self

Create a in-memory MmapFile from Vec

Examples

use fmmap::sync::MmapFile;

let data = (0..=255u8).collect::<Vec<_>>();
MmapFile::memory_from_vec("foo.mem", data);

pub fn memory_from_string<P: AsRef<Path>>(path: P, src: String) -> Self

Create a in-memory MmapFile from String

Examples

use fmmap::sync::MmapFile;

let data: &'static str = "some data...";
MmapFile::memory_from_string("foo.mem", data.to_string());

pub fn memory_from_slice<P: AsRef<Path>>(path: P, src: &'static [u8]) -> Self

Create a in-memory MmapFile from static slice

Examples

use bytes::Bytes;
use fmmap::sync::MmapFile;

let data: &'static [u8] = "some data...".as_bytes();
MmapFile::memory_from_slice("foo.mem", data);

pub fn memory_from_str<P: AsRef<Path>>(path: P, src: &'static str) -> Self

Create a in-memory MmapFile from static str

Examples

use bytes::Bytes;
use fmmap::sync::MmapFile;

let data: &'static str = "some data...";
MmapFile::memory_from_str("foo.mem", data);

pub fn memory_copy_from_slice<P: AsRef<Path>>(path: P, src: &[u8]) -> Self

Create a in-memory MmapFile by copy from slice

Examples

use fmmap::sync::MmapFile;

MmapFile::memory_copy_from_slice("foo.mem", "some data...".as_bytes());

Trait Implementations

impl From<DiskMmapFile> for MmapFile

fn from(file: DiskMmapFile) -> Self

Converts to this type from the input type.

impl From<MemoryMmapFile> for MmapFile

fn from(file: MemoryMmapFile) -> Self

Converts to this type from the input type.

impl MmapFileExt for MmapFile

fn len(&self) -> usize

Returns the current mmap length

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

Returns the underlying slice of the mmap

fn path(&self) -> &Path

Returns the path of the inner file.

fn is_exec(&self) -> bool

Whether the mmap is executable.

fn metadata(&self) -> Result<MetaData>

Returns the metadata of file metadata

fn lock_exclusive(&self) -> Result<()>

Locks the file for shared usage, blocking if the file is currently locked exclusively.

fn lock_shared(&self) -> Result<()>

Locks the file for exclusive usage, blocking if the file is currently locked.

fn try_lock_exclusive(&self) -> Result<()>

Locks the file for shared usage, or returns a an error if the file is currently locked (see lock_contended_error).

fn try_lock_shared(&self) -> Result<()>

Locks the file for shared usage, or returns a an error if the file is currently locked (see lock_contended_error).Locks the file for shared usage, or returns a an error if the file is currently locked (see lock_contended_error).

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

Unlocks the file.

fn is_empty(&self) -> bool

Returns the mmap is empty of not.

fn slice(&self, offset: usize, sz: usize) -> &[u8]

slice returns data starting from offset off of size sz.

fn bytes(&self, offset: usize, sz: usize) -> Result<&[u8]>

bytes returns data starting from offset off of size sz.

fn path_buf(&self) -> PathBuf

Returns the path buf of the inner file.

fn path_lossy(&self) -> Cow<'_, str>

Returns the path lossy string of the inner file.

fn path_string(&self) -> String

Returns the path string of the inner file.

fn copy_all_to_vec(&self) -> Vec<u8>

Copy the content of the mmap file to Vec

fn copy_range_to_vec(&self, offset: usize, len: usize) -> Vec<u8>

Copy a range of content of the mmap file to Vec

fn write_all_to_new_file<P: AsRef<Path>>(&self, new_file_path: P) -> Result<()>

Write the content of the mmap file to a new file.

fn write_range_to_new_file<P: AsRef<Path>>( &self, new_file_path: P, offset: usize, len: usize ) -> Result<()>

Write a range of content of the mmap file to new file.

fn reader(&self, offset: usize) -> Result<MmapFileReader<'_>>

Returns a MmapFileReader which helps read data from mmap like a normal File.

fn range_reader(&self, offset: usize, len: usize) -> Result<MmapFileReader<'_>>

Returns a MmapFileReader base on the given offset and len, which helps read data from mmap like a normal File.

fn read(&self, dst: &mut [u8], offset: usize) -> usize

Read bytes to the dst buf from the offset, returns how many bytes read.

fn read_exact(&self, dst: &mut [u8], offset: usize) -> Result<()>

Read the exact number of bytes required to fill buf.

fn read_i8(&self, offset: usize) -> Result<i8>

Read a signed 8 bit integer from offset.

fn read_i16(&self, offset: usize) -> Result<i16>

Read a signed 16 bit integer from offset in big-endian byte order.

fn read_i16_le(&self, offset: usize) -> Result<i16>

Read a signed 16 bit integer from offset in little-endian byte order.

fn read_isize(&self, offset: usize) -> Result<isize>

Read a signed integer from offset in big-endian byte order.

fn read_isize_le(&self, offset: usize) -> Result<isize>

Read a signed integer from offset in little-endian byte order.

fn read_i32(&self, offset: usize) -> Result<i32>

Read a signed 32 bit integer from offset in big-endian byte order.

fn read_i32_le(&self, offset: usize) -> Result<i32>

Read a signed 32 bit integer from offset in little-endian byte order.

fn read_i64(&self, offset: usize) -> Result<i64>

Read a signed 64 bit integer from offset in big-endian byte order.

fn read_i64_le(&self, offset: usize) -> Result<i64>

Read a signed 64 bit integer from offset in little-endian byte order.

fn read_i128(&self, offset: usize) -> Result<i128>

Read a signed 128 bit integer from offset in big-endian byte order.

fn read_i128_le(&self, offset: usize) -> Result<i128>

Read a signed 128 bit integer from offset in little-endian byte order.

fn read_u8(&self, offset: usize) -> Result<u8>

Read an unsigned 8 bit integer from offset.

fn read_u16(&self, offset: usize) -> Result<u16>

Read an unsigned 16 bit integer from offset in big-endian.

fn read_u16_le(&self, offset: usize) -> Result<u16>

Read an unsigned 16 bit integer from offset in little-endian.

fn read_usize(&self, offset: usize) -> Result<usize>

Read an unsigned integer from offset in big-endian byte order.

fn read_usize_le(&self, offset: usize) -> Result<usize>

Read an unsigned integer from offset in little-endian byte order.

fn read_u32(&self, offset: usize) -> Result<u32>

Read an unsigned 32 bit integer from offset in big-endian.

fn read_u32_le(&self, offset: usize) -> Result<u32>

Read an unsigned 32 bit integer from offset in little-endian.

fn read_u64(&self, offset: usize) -> Result<u64>

Read an unsigned 64 bit integer from offset in big-endian.

fn read_u64_le(&self, offset: usize) -> Result<u64>

Read an unsigned 64 bit integer from offset in little-endian.

fn read_u128(&self, offset: usize) -> Result<u128>

Read an unsigned 128 bit integer from offset in big-endian.

fn read_u128_le(&self, offset: usize) -> Result<u128>

Read an unsigned 128 bit integer from offset in little-endian.

fn read_f32(&self, offset: usize) -> Result<f32>

Read an IEEE754 single-precision (4 bytes) floating point number from offset in big-endian byte order.

fn read_f32_le(&self, offset: usize) -> Result<f32>

Read an IEEE754 single-precision (4 bytes) floating point number from offset in little-endian byte order.

fn read_f64(&self, offset: usize) -> Result<f64>

Read an IEEE754 single-precision (8 bytes) floating point number from offset in big-endian byte order.

fn read_f64_le(&self, offset: usize) -> Result<f64>

Read an IEEE754 single-precision (8 bytes) floating point number from offset in little-endian byte order.