Integration Examples

Using with #![forbid(unsafe_code)] Crates

The primary use case for mmap-guard is enabling memory-mapped I/O in crates that forbid unsafe code.

Feature-gated mmap support

In your crate’s Cargo.toml:

[dependencies]
mmap-guard = { version = "0.1", optional = true }

[features]
mmap = ["dep:mmap-guard"]

In your source code:

#![forbid(unsafe_code)]

use std::path::Path;
use std::io;

fn load_file(path: &Path) -> io::Result<Vec<u8>> {
    #[cfg(feature = "mmap")]
    {
        let data = mmap_guard::map_file(path)?;
        // FileData derefs to &[u8], but we need owned data
        // if the caller expects Vec<u8>. For zero-copy, pass
        // the FileData directly.
        Ok(data.to_vec())
    }

    #[cfg(not(feature = "mmap"))]
    {
        std::fs::read(path)
    }
}

Zero-copy pipeline

For best performance, pass FileData through your pipeline instead of converting to Vec<u8>:

#![forbid(unsafe_code)]

use mmap_guard::FileData;
use std::path::Path;
use std::io;

fn process_bytes(data: &[u8]) {
    // Works with both Mapped and Loaded variants
    println!("processing {} bytes", data.len());
}

fn run(path: &Path) -> io::Result<()> {
    let data: FileData = mmap_guard::map_file(path)?;
    process_bytes(&data); // zero-copy — no allocation
    Ok(())
}

CLI tool with stdin support

load handles "-" internally, so a simple call covers both files and stdin:

use mmap_guard::{load, FileData};
use std::io;

fn main() -> io::Result<()> {
    let path = std::env::args().nth(1).unwrap_or_else(|| "-".into());
    let data: FileData = load(&path)?;

    // Process data uniformly regardless of source
    println!("{} bytes", data.len());
    Ok(())
}

Advanced: custom stdin cap

For callers that need a different stdin limit, call load_stdin directly:

use mmap_guard::{load_stdin, FileData};
use std::io;

fn main() -> io::Result<()> {
    // Cap stdin reads to 256 MiB
    let data: FileData = load_stdin(Some(256 * 1024 * 1024))?;
    println!("{} bytes", data.len());
    Ok(())
}