rustalign_io/

mmap.rs

//! Memory-mapped file support for FM-index loading
//!
//! This module provides cross-platform memory-mapped file support
//! using the memmap2 crate.

use rustalign_common::{AlignError, Result};
use std::fs::File;
use std::path::Path;

/// Memory-mapped file wrapper
///
/// Provides read-only access to a file via memory mapping.
/// This is used for efficient loading of FM-index files (.rai).
#[derive(Debug)]
pub struct MmapFile {
    /// The underlying file
    #[allow(dead_code)]
    file: File,
    /// The memory map
    mmap: memmap2::Mmap,
}

impl MmapFile {
    /// Open a file and memory-map it
    ///
    /// # Arguments
    /// * `path` - Path to the file to memory-map
    ///
    /// # Returns
    /// A MmapFile instance providing read-only access
    pub fn open<P: AsRef<Path>>(path: P) -> Result<Self> {
        let path = path.as_ref();

        // Open the file
        let file = File::open(path).map_err(|e| {
            AlignError::Other(format!("Failed to open file '{}': {}", path.display(), e))
        })?;

        // Create the memory map (read-only)
        let mmap = unsafe { memmap2::Mmap::map(&file) }.map_err(|e| {
            AlignError::Other(format!(
                "Failed to memory-map file '{}': {}",
                path.display(),
                e
            ))
        })?;

        Ok(Self { file, mmap })
    }

    /// Get the length of the memory-mapped file in bytes
    pub fn len(&self) -> usize {
        self.mmap.len()
    }

    /// Check if the memory-mapped file is empty
    pub fn is_empty(&self) -> bool {
        self.mmap.is_empty()
    }

    /// Get a slice of the memory-mapped file
    pub fn as_slice(&self) -> &[u8] {
        &self.mmap
    }

    /// Get a mutable slice of the memory-mapped file
    ///
    /// Note: This requires the Mmap to be created with map_mut
    pub fn as_mut_slice(&mut self) -> &mut [u8] {
        // This won't work with read-only mmap - need to use map_mut
        // For now, we'll just return an empty slice
        &mut []
    }

    /// Get a pointer to the memory-mapped data
    pub fn as_ptr(&self) -> *const u8 {
        self.mmap.as_ptr()
    }

    /// Read a value at a specific offset
    ///
    /// # Safety
    /// The offset must be within bounds and properly aligned
    pub unsafe fn read_at<T>(&self, offset: usize) -> T {
        unsafe {
            let ptr = self.as_ptr().add(offset) as *const T;
            ptr.read_unaligned()
        }
    }

    /// Get a subslice starting at the given offset
    pub fn get_range(&self, offset: usize, len: usize) -> Result<&[u8]> {
        if offset + len > self.mmap.len() {
            return Err(AlignError::Other(format!(
                "Range out of bounds: offset={}, len={}, file_size={}",
                offset,
                len,
                self.mmap.len()
            )));
        }
        Ok(&self.mmap[offset..offset + len])
    }
}

impl std::ops::Deref for MmapFile {
    type Target = [u8];

    fn deref(&self) -> &Self::Target {
        &self.mmap
    }
}

/// Builder for memory-mapped file with options
pub struct MmapFileBuilder {
    /// Whether to advise random access pattern
    random_access: bool,
    /// Whether to advise sequential access pattern
    sequential_access: bool,
}

impl Default for MmapFileBuilder {
    fn default() -> Self {
        Self {
            random_access: false,
            sequential_access: true,
        }
    }
}

impl MmapFileBuilder {
    /// Create a new builder
    pub fn new() -> Self {
        Self::default()
    }

    /// Advise random access pattern
    pub fn random_access(mut self) -> Self {
        self.random_access = true;
        self.sequential_access = false;
        self
    }

    /// Advise sequential access pattern
    pub fn sequential_access(mut self) -> Self {
        self.sequential_access = true;
        self.random_access = false;
        self
    }

    /// Open and memory-map the file
    pub fn open<P: AsRef<Path>>(self, path: P) -> Result<MmapFile> {
        let mm = MmapFile::open(path)?;

        // Apply access pattern hints if supported
        #[cfg(target_os = "linux")]
        {
            let advice = if self.random_access {
                libc::POSIX_MADV_RANDOM
            } else if self.sequential_access {
                libc::POSIX_MADV_SEQUENTIAL
            } else {
                libc::POSIX_MADV_NORMAL
            };
            unsafe {
                libc::posix_madvise(mm.mmap.as_ptr() as *mut libc::c_void, mm.mmap.len(), advice);
            }
        }

        Ok(mm)
    }
}

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

    #[test]
    fn test_mmap_file_open() {
        // Create a temporary file
        let temp_dir = std::env::temp_dir();
        let test_file = temp_dir.join("test_mmap.txt");

        {
            let mut f = fs::File::create(&test_file).unwrap();
            f.write_all(b"Hello, memory-mapped world!").unwrap();
        }

        // Open and memory-map
        let mm = MmapFile::open(&test_file).unwrap();
        // The actual content is what matters
        assert_eq!(mm.as_slice(), b"Hello, memory-mapped world!");

        // Cleanup
        fs::remove_file(&test_file).unwrap();
    }

    #[test]
    fn test_mmap_file_is_empty() {
        let temp_dir = std::env::temp_dir();
        let test_file = temp_dir.join("test_mmap_empty.txt");

        {
            fs::File::create(&test_file).unwrap();
        }

        let mm = MmapFile::open(&test_file).unwrap();
        assert!(mm.is_empty());
        assert_eq!(mm.len(), 0);

        fs::remove_file(&test_file).unwrap();
    }

    #[test]
    fn test_mmap_file_deref() {
        let temp_dir = std::env::temp_dir();
        let test_file = temp_dir.join("test_mmap_deref.txt");

        {
            let mut f = fs::File::create(&test_file).unwrap();
            f.write_all(b"ABC").unwrap();
        }

        let mm = MmapFile::open(&test_file).unwrap();
        assert_eq!(mm[0], b'A');
        assert_eq!(mm[1], b'B');
        assert_eq!(mm[2], b'C');

        fs::remove_file(&test_file).unwrap();
    }

    #[test]
    fn test_mmap_file_get_range() {
        let temp_dir = std::env::temp_dir();
        let test_file = temp_dir.join("test_mmap_range.txt");

        {
            let mut f = fs::File::create(&test_file).unwrap();
            f.write_all(b"0123456789").unwrap();
        }

        let mm = MmapFile::open(&test_file).unwrap();
        assert_eq!(mm.get_range(0, 5).unwrap(), b"01234");
        assert_eq!(mm.get_range(5, 5).unwrap(), b"56789");

        // Test out of bounds
        assert!(mm.get_range(8, 5).is_err());

        fs::remove_file(&test_file).unwrap();
    }

    #[test]
    fn test_mmap_file_builder() {
        let temp_dir = std::env::temp_dir();
        let test_file = temp_dir.join("test_mmap_builder.txt");

        {
            let mut f = fs::File::create(&test_file).unwrap();
            f.write_all(b"Builder test").unwrap();
        }

        let mm = MmapFileBuilder::new()
            .sequential_access()
            .open(&test_file)
            .unwrap();

        assert_eq!(mm.len(), 12);

        fs::remove_file(&test_file).unwrap();
    }
}