Introduce memory mapping for index files and sparse matrices

This change implements memory-mapped views for index readers and sparse matrices, enabling shared page-cache access. It also includes performance analysis confirming that the default chunk size cap negatively impacts parallelism for small inputs.
This commit is contained in:
Eric Coissac committed 2026-10-15 12:17:09 +02:00
1 parent 09c80468b2
commit 093d81c359
4 files changed
+116 -42

No files matched your search

+18 -5
View File
@@ -25,6 +25,7 @@ use std::fs;
use std::io;
use std::path::{Path, PathBuf};
use memmap2::Mmap;
use ndarray::{Array1, Array2};
use crate::traits::{BitPartials, ColumnWeights};
@@ -151,7 +152,9 @@ pub struct PersistentSparseBitMatrix {
singleton: PersistentFixedIntVec,
multi: PersistentFixedIntVec,
dict_offsets: EliasFano,
dict_values: Vec<u8>,
/// `dict_values.bin`, mapped (never copied to the heap); `None` when the
/// file is empty — no multi-genome set — since an empty file cannot be mapped.
dict_values: Option<Mmap>,
/// Row count (k-mer slots).
n: usize,
/// Column count (genomes).
@@ -167,7 +170,12 @@ impl PersistentSparseBitMatrix {
let singleton = PersistentFixedIntVec::open(&singleton_path(dir))?;
let multi = PersistentFixedIntVec::open(&multi_path(dir))?;
let dict_offsets = EliasFano::open(&dict_offsets_base(dir))?;
let dict_values = fs::read(dict_values_path(dir))?;
let dict_file = fs::File::open(dict_values_path(dir))?;
let dict_values = if dict_file.metadata()?.len() == 0 {
None
} else {
Some(unsafe { Mmap::map(&dict_file)? })
};
Ok(Self {
is_multi, singleton, multi, dict_offsets, dict_values,
n: meta.n, n_cols: meta.n_cols, n_distinct_multi: meta.n_distinct_multi,
@@ -179,6 +187,11 @@ impl PersistentSparseBitMatrix {
#[inline]
pub fn n_cols(&self) -> usize { self.n_cols }
#[inline]
fn dict_bytes(&self) -> &[u8] {
self.dict_values.as_deref().unwrap_or(&[])
}
/// Byte range of `dict_id`'s varint-encoded genome list within
/// `dict_values`.
#[inline]
@@ -187,7 +200,7 @@ impl PersistentSparseBitMatrix {
let end = if dict_id + 1 < self.n_distinct_multi {
self.dict_offsets.get(dict_id + 1) as usize
} else {
self.dict_values.len()
self.dict_bytes().len()
};
(start, end)
}
@@ -232,7 +245,7 @@ impl PersistentSparseBitMatrix {
let (start, end) = self.dict_entry_range(dict_id);
let mut p = start;
while p < end {
f(read_varint(&self.dict_values, &mut p) as usize);
f(read_varint(self.dict_bytes(), &mut p) as usize);
}
} else {
let pos = self.is_multi.rank0(slot) as usize;
@@ -287,7 +300,7 @@ impl PersistentSparseBitMatrix {
present.clear();
let mut p = start;
while p < end {
present.push(read_varint(&self.dict_values, &mut p) as usize);
present.push(read_varint(self.dict_bytes(), &mut p) as usize);
}
for &g in &present {
counts[g] += w;
+50 -37
View File
@@ -24,7 +24,7 @@ use super::{DEFAULT_BLOCK_BITS, MAGIC, idx_path};
/// correct but slower.
pub struct UnitigFileReader {
mmap: Mmap,
block_offsets: Vec<u32>,
block_offsets: BlockOffsets,
n_unitigs: usize,
n_kmers: usize,
k: usize,
@@ -64,7 +64,7 @@ impl UnitigFileReader {
Ok(Self {
mmap,
block_offsets: Vec::new(),
block_offsets: BlockOffsets::none(),
n_unitigs,
n_kmers,
k,
@@ -108,7 +108,7 @@ impl UnitigFileReader {
}
#[inline]
pub fn has_direct_access(&self) -> bool {
!self.block_offsets.is_empty()
!self.block_offsets.is_none()
}
/// Byte offset of record `i` in the mmap.
@@ -119,11 +119,11 @@ impl UnitigFileReader {
fn chunk_start(&self, i: usize) -> usize {
if self.has_direct_access() {
if self.block_bits == 0 {
return self.block_offsets[i] as usize;
return self.block_offsets.get(i) as usize;
}
let block = i >> self.block_bits;
let rem = i & self.mask;
let mut offset = self.block_offsets[block] as usize;
let mut offset = self.block_offsets.get(block) as usize;
for _ in 0..rem {
let seql_minus_k = self.mmap[offset] as usize;
offset += 1 + (seql_minus_k + self.k + 3) / 4;
@@ -292,25 +292,54 @@ impl UnitigFileReader {
}
}
fn read_idx(path: &Path) -> SKResult<(usize, usize, u8, Vec<u32>)> {
let data = std::fs::read(path).map_err(SKError::Io)?;
let mut pos = 0;
/// Block offsets of a `.idx` file, read in place from its memory map: nothing
/// is copied to the heap, and every reader of the same `.idx` shares the same
/// page-cache pages (a copy was ~30 MB per large layer per reader).
struct BlockOffsets {
/// The whole `.idx` file; `None` for a sequential reader (no `.idx`).
mmap: Option<Mmap>,
}
let magic_bytes = data.get(pos..pos + 4).ok_or(SKError::Truncated {
context: "unitig index: magic",
})?;
impl BlockOffsets {
fn none() -> Self {
Self { mmap: None }
}
fn is_none(&self) -> bool {
self.mmap.is_none()
}
/// The `i`-th offset (little-endian `u32` after the fixed header).
/// `read_idx` has checked that the file holds every offset the header
/// announces, so `i` within `0..=n_blocks` cannot run past the map.
#[inline]
fn get(&self, i: usize) -> u32 {
let at = IDX_HEADER_SIZE + 4 * i;
let map = self.mmap.as_ref().expect("direct-access reader has its .idx map");
u32::from_le_bytes(map[at..at + 4].try_into().unwrap())
}
}
/// magic (4) + block_bits (4) + n_unitigs (4) + n_kmers (8).
const IDX_HEADER_SIZE: usize = 20;
fn read_idx(path: &Path) -> SKResult<(usize, usize, u8, BlockOffsets)> {
let file = File::open(path).map_err(SKError::Io)?;
let len = file.metadata().map_err(SKError::Io)?.len() as usize;
if len < IDX_HEADER_SIZE {
return Err(SKError::Truncated { context: "unitig index: header" });
}
let data = unsafe { Mmap::map(&file).map_err(SKError::Io)? };
let magic_bytes = &data[0..4];
if magic_bytes != &MAGIC {
return Err(SKError::BadMagic {
expected: "UIX3",
got: magic_bytes.try_into().unwrap(),
});
}
pos += 4;
let bb_bytes = data.get(pos..pos + 4).ok_or(SKError::Truncated {
context: "unitig index: block_bits",
})?;
let block_bits_u32 = u32::from_le_bytes(bb_bytes.try_into().unwrap());
let block_bits_u32 = u32::from_le_bytes(data[4..8].try_into().unwrap());
if block_bits_u32 > 31 {
return Err(SKError::InvalidData {
context: "unitig index",
@@ -318,31 +347,15 @@ fn read_idx(path: &Path) -> SKResult<(usize, usize, u8, Vec<u32>)> {
});
}
let block_bits = block_bits_u32 as u8;
pos += 4;
let n_bytes = data.get(pos..pos + 4).ok_or(SKError::Truncated {
context: "unitig index: n_unitigs",
})?;
let n_unitigs = u32::from_le_bytes(n_bytes.try_into().unwrap()) as usize;
pos += 4;
let nk_bytes = data.get(pos..pos + 8).ok_or(SKError::Truncated {
context: "unitig index: n_kmers",
})?;
let n_kmers = u64::from_le_bytes(nk_bytes.try_into().unwrap()) as usize;
pos += 8;
let n_unitigs = u32::from_le_bytes(data[8..12].try_into().unwrap()) as usize;
let n_kmers = u64::from_le_bytes(data[12..20].try_into().unwrap()) as usize;
let block_size = 1usize << block_bits;
let n_blocks = (n_unitigs + block_size - 1) >> block_bits;
let n_offsets = n_blocks + 1;
let mut block_offsets = Vec::with_capacity(n_offsets);
for _ in 0..n_offsets {
let off_bytes = data.get(pos..pos + 4).ok_or(SKError::Truncated {
context: "unitig index: block_offsets",
})?;
block_offsets.push(u32::from_le_bytes(off_bytes.try_into().unwrap()));
pos += 4;
if len < IDX_HEADER_SIZE + 4 * n_offsets {
return Err(SKError::Truncated { context: "unitig index: block_offsets" });
}
Ok((n_unitigs, n_kmers, block_bits, block_offsets))
Ok((n_unitigs, n_kmers, block_bits, BlockOffsets { mmap: Some(data) }))
}