Skip to main content

ferrite_model/
model_file.rs

1//! Shared read-only model-file mapping for zero-copy tensor storage.
2#![allow(
3    unsafe_code,
4    reason = "read-only file mapping is isolated behind an immutable slice API"
5)]
6
7use memmap2::{Mmap, MmapOptions};
8use std::{fs::File, io, path::Path, sync::Arc};
9
10/// A read-only operating-system mapping of one model file.
11///
12/// Mapping avoids allocating a model-sized heap buffer and can be cloned
13/// cheaply so validated tensors retain ranges of the same operating-system
14/// mapping.
15#[derive(Clone, Debug)]
16pub struct MappedModelFile {
17    bytes: Arc<Mmap>,
18}
19
20impl MappedModelFile {
21    /// Opens and maps a non-empty model file read-only.
22    ///
23    /// # Safety
24    ///
25    /// The underlying file must not be modified or truncated until this value
26    /// and every clone derived from it have been dropped. File-backed mappings
27    /// cannot enforce that condition against other processes.
28    ///
29    /// # Errors
30    ///
31    /// Returns an I/O error when the file cannot be opened, inspected, or
32    /// mapped, or when it is empty.
33    pub unsafe fn open(path: &Path) -> io::Result<Self> {
34        let file = File::open(path)?;
35        if file.metadata()?.len() == 0 {
36            return Err(io::Error::new(
37                io::ErrorKind::InvalidData,
38                "model file must not be empty",
39            ));
40        }
41        // SAFETY: the caller accepts the file-stability requirement documented
42        // by this function. The mapping is read-only, `Mmap` keeps it alive
43        // independently of the `File`, and this API exposes immutable slices.
44        let bytes = Arc::new(unsafe { MmapOptions::new().map(&file)? });
45        Ok(Self { bytes })
46    }
47
48    /// Returns the complete mapped file contents.
49    pub fn as_bytes(&self) -> &[u8] {
50        &self.bytes
51    }
52}
53
54#[cfg(test)]
55mod tests {
56    use super::MappedModelFile;
57    use std::{fs, io, path::PathBuf};
58
59    #[test]
60    fn maps_complete_file_contents_read_only() -> io::Result<()> {
61        let path = temporary_path("contents");
62        fs::write(&path, b"GGUF-test-bytes")?;
63
64        // SAFETY: the test owns the temporary file and does not modify or
65        // remove it until the mapping is dropped.
66        let mapped = unsafe { MappedModelFile::open(&path)? };
67        assert_eq!(mapped.as_bytes(), b"GGUF-test-bytes");
68
69        drop(mapped);
70        fs::remove_file(path)
71    }
72
73    #[test]
74    fn rejects_empty_model_file() -> io::Result<()> {
75        let path = temporary_path("empty");
76        fs::write(&path, [])?;
77
78        // SAFETY: the test owns the temporary file and does not modify it
79        // while the attempted mapping is alive.
80        let error = unsafe { MappedModelFile::open(&path) }
81            .err()
82            .ok_or_else(|| io::Error::other("empty model file unexpectedly mapped"))?;
83
84        fs::remove_file(path)?;
85        assert_eq!(error.kind(), io::ErrorKind::InvalidData);
86        Ok(())
87    }
88
89    fn temporary_path(label: &str) -> PathBuf {
90        std::env::temp_dir().join(format!(
91            "ferrite-mapped-model-{label}-{}",
92            std::process::id()
93        ))
94    }
95}