Crate fmmap

Expand description

fmmap

A flexible and convenient high-level mmap for zero-copy file I/O.

Design

The design of this crate is inspired by Dgraph’s mmap file implementation in Stretto.

All of file-backed memory map has the potential for Undefined Behavior (UB) if the underlying file is subsequently modified (e.g. the file is deleted by another process), in or out of process, this crate tries to avoid this situation by provide file lock APIs.

This crate supports std and popular async runtime(tokio, async-std, smol), and thanks to macro in Rust, it is super easy to support any new async runtime. For details, please see the implementation for tokio, async-std, smol of the source code.

Features

dozens of file I/O util functions
file-backed memory maps
synchronous and asynchronous flushing
copy-on-write memory maps
read-only memory maps
stack support (MAP_STACK on unix)
executable memory maps
file locks.
tokio
smol
async-std

Installation

std

[dependencies]
fmmap = 0.2

tokio

[dependencies]
fmmap = { version = "0.2", features = ["tokio-async"] }

async-std

[dependencies]
fmmap = { version = "0.2", features = ["std-async"] }

smol

[dependencies]
fmmap = { version = "0.2", features = ["smol-async"] }

Examples

This crate is 100% documented, see documents for examples.

TODO

add benchmarks

License

^{Licensed under either of Apache License, Version
2.0 or MIT license at your option.}
_{Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in this project by you, as defined in the Apache-2.0 license,
shall be dual licensed as above, without any additional terms or conditions.}

Modules

async_stdasync-std and async-trait

async_std based mmap file

error

Errors in this crate

raw

Components of mmap file.

smolsmol and async-trait

smol based mmap file

syncsync

std based mmap file

tokiotokio and async-trait

tokio based mmap file

utils

File I/O utils function

Macros

cfg_test

#[cfg(test)]

cfg_unix

#[cfg(unix)]

cfg_windows

#[cfg(windows)]

Structs

MetaData

Metadata information about a file. This structure is returned from the metadata or symlink_metadata function or method and represents known metadata about a file such as its permissions, size, modification times, etc

MmapFilesync

A read-only memory map file.

MmapFileMutsync

A writable memory map file.

MmapFileReadersync

MmapFileReader helps read data from mmap file like a normal file.

MmapFileWritersync

MmapFileWriter helps read or write data from mmap file like a normal file.

Optionssync

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