bale 0.1.0

A mmap-first, fixed-stride zip-like pack format
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

//! Read-only memory-mapped archive.

use crate::BaleError;

use std::fs::File;
use std::path::Path;

/// A read-only memory-mapped archive file.
///
/// This struct provides zero-copy access to archive contents by memory-mapping
/// the underlying file. A shared lock is held on the file for the lifetime of
/// this struct, allowing multiple concurrent readers while preventing writers.
///
/// The lock is automatically released when this struct is dropped.
pub struct MappedArchive {
    /// The underlying file handle (kept open to maintain the lock).
    file: File,
    /// The memory-mapped region.
    mmap: memmap2::Mmap,
}

impl MappedArchive {
    /// Opens a file and memory-maps it for reading.
    ///
    /// Acquires a shared lock on the file, allowing multiple concurrent readers
    /// while preventing exclusive writers.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - The file cannot be opened
    /// - The shared lock cannot be acquired
    /// - Memory mapping fails
    ///
    /// # Safety
    ///
    /// Memory mapping is inherently unsafe because the underlying file could
    /// be modified by another process while mapped. This implementation
    /// mitigates this by holding a shared lock on the file, preventing
    /// cooperative writers from modifying it during the mapping lifetime.
    pub fn open(path: impl AsRef<Path>) -> Result<Self, BaleError> {
        let file = File::open(path.as_ref())?;
        file.lock_shared()?;
        // SAFETY: We hold a shared lock on the file, preventing cooperative
        // writers from modifying it while mapped.
        #[allow(unsafe_code)]
        let mmap = unsafe { memmap2::Mmap::map(&file)? };
        Ok(Self { file, mmap })
    }

    /// Returns the length of the mapped region in bytes.
    #[must_use]
    pub fn len(&self) -> usize {
        self.mmap.len()
    }

    /// Returns true if the mapped region is empty.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.mmap.is_empty()
    }

    /// Returns a byte slice of the entire mapped region.
    #[must_use]
    pub fn as_bytes(&self) -> &[u8] {
        &self.mmap
    }

    ///Returns the underlying file.
    #[must_use]
    pub fn file(&self) -> &File {
        &self.file
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::io::Write;
    use tempfile::NamedTempFile;

    /// Opening a valid file returns a mapped archive.
    #[test]
    fn open_valid_file() {
        let mut file = NamedTempFile::new().unwrap();
        file.write_all(b"test data").unwrap();
        let mapped = MappedArchive::open(file.path()).unwrap();
        assert_eq!(mapped.len(), 9);
        assert_eq!(mapped.as_bytes(), b"test data");
    }

    /// Opening a nonexistent file returns an error.
    #[test]
    fn open_nonexistent_file() {
        let result = MappedArchive::open("/nonexistent/path/to/file.bale");
        assert!(result.is_err());
    }

    /// Empty files can be mapped.
    #[test]
    fn open_empty_file() {
        let file = NamedTempFile::new().unwrap();
        let mapped = MappedArchive::open(file.path()).unwrap();
        assert!(mapped.is_empty());
        assert_eq!(mapped.len(), 0);
    }
}