Struct MappedFile 

pub struct MappedFile { /* private fields */ }

Memory-mapped file with zero-copy access.

On native platforms (Linux, macOS, Windows), this uses real OS-level memory mapping via memmap2. On WASM, it falls back to standard heap-based file reading.

Safety

The mapped region is valid as long as:

1. The file is not modified externally (single-writer assumption)
2. The MappedFile instance is not dropped
3. The underlying storage remains available

SIGBUS Warning (Unix)

If the underlying file is truncated while mapped, accessing the truncated region will generate a SIGBUS signal. This library does not install signal handlers. See module documentation for details.

Example

use aprender::bundle::mmap::MappedFile;

let mapped = MappedFile::open("model.apr")?;
let header = mapped.slice(0, 32)?;  // Zero-copy access
println!("File size: {} bytes", mapped.len());

Implementations

impl MappedFile

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

Open a file for memory-mapped read access.

Safety Justification (Jidoka)

The unsafe block is required because memmap2::Mmap::map() has undefined behavior if:

• The file is modified by another process while mapped
• The file is truncated while mapped (triggers SIGBUS on Unix)

We mitigate these risks by:

1. Opening the file read-only (no write handle to leak)
2. Documenting the single-writer assumption
3. Validating checksums before use (in .apr format)

References:

• Vahalia (1996): SIGBUS from truncated mmap
• memmap2 crate safety documentation

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

Get the entire file as a byte slice (zero-copy).

pub fn slice(&self, start: usize, end: usize) -> Option<&[u8]>

Get a subslice of the file (zero-copy).

Returns None if the range is out of bounds.

pub fn len(&self) -> usize

File size in bytes.

pub fn is_empty(&self) -> bool

Check if file is empty.

pub fn path(&self) -> &str

Get the file path.

pub fn advise_sequential(&self) -> Result<()>

Advise the kernel about sequential access pattern (Unix only).

This can improve performance for linear scans through the file.

pub fn advise_random(&self) -> Result<()>

Advise the kernel about random access pattern (Unix only).

This can improve performance for random lookups.

Trait Implementations

impl Debug for MappedFile

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.