Store minorant flag in family mask to avoid costly k-mer reconstruction

Transition the minorant flag from a derived value to a stored field within the family mask, resolving a performance regression where on-the-fly reconstruction consumed significant query time. This change introduces O(1) k-mer reconstruction APIs, shifts minorant computation to the index build phase, and enables direct annex-based statistics. Supporting updates include adopting shared ownership for partition caches and refactoring batch processing pipelines.
This commit is contained in:
Eric Coissac committed 2026-08-16 13:50:44 +02:00
1 parent c7679fac90
commit 0de078fdf1
15 files changed
+519 -145

No files matched your search

+47 -12
View File
@@ -41,11 +41,22 @@ const MAGIC: [u8; 4] = *b"PSIB";
// Header: magic(4) + _pad(4) + n(8) = 16 bytes. Data (1 byte/slot) follows.
const HEADER_SIZE: usize = 16;
/// A family presence mask: bit `b` set iff the member whose own canonical
/// central base is `b` (0=A, 1=C, 2=G, 3=T) is observed in the index.
/// A family presence mask: bit `b` (0..3) set iff the member whose own
/// canonical central base is `b` (0=A, 1=C, 2=G, 3=T) is observed in the
/// index. Bit 4 is a second, independent fact piggy-backed onto the same
/// byte: whether *this slot's own k-mer* is its family's minorant (the
/// smallest raw encoding among the family's observed members) — computed
/// once, when the whole family's mask is already final (see
/// `obikindex::siblings::build_sibling_annex`), and read back by every
/// consumer that would otherwise have to reconstruct this slot's k-mer from
/// `unitigs.bin` and hash it through the MPHF again just to ask the same
/// question. Bits 5-7 unused.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct FamilyMask(u8);
const PRESENCE_BITS: u8 = 0b0000_1111;
const MINORANT_BIT: u8 = 0b0001_0000;
impl FamilyMask {
/// The empty mask — never a valid *computed* result (a slot's own base
/// is always present in its own family) — used only to build up a mask
@@ -69,7 +80,7 @@ impl FamilyMask {
/// Number of family members observed anywhere in the index (1..=4).
#[inline]
pub fn family_size(self) -> u32 {
self.0.count_ones()
(self.0 & PRESENCE_BITS).count_ones()
}
/// Number of *other* members observed (0..=3) — `family_size() - 1`.
@@ -78,18 +89,39 @@ impl FamilyMask {
self.family_size() - 1
}
/// Raw bitmask (bit `b` = base `b` present) — for callers that build up
/// a mask via their own bit operations (e.g. concurrently, via an
/// `AtomicU8`) and only need the `FamilyMask` wrapper at the end.
/// Set or clear the minorant flag (see the struct docs).
#[inline]
pub fn bits(self) -> u8 {
self.0
pub fn with_minorant(self, is_minorant: bool) -> Self {
if is_minorant {
FamilyMask(self.0 | MINORANT_BIT)
} else {
FamilyMask(self.0 & !MINORANT_BIT)
}
}
/// Construct from a raw bitmask (only the low 4 bits are kept).
/// Is this slot's own k-mer its family's minorant? Only meaningful once
/// `with_minorant` has been called with the family's *final* mask (i.e.
/// after construction) — see the struct docs.
#[inline]
pub fn is_minorant(self) -> bool {
self.0 & MINORANT_BIT != 0
}
/// Raw presence bitmask (bit `b` = base `b` present, low 4 bits only —
/// never includes the minorant flag) — for callers that build up a mask
/// via their own bit operations (e.g. concurrently, via an `AtomicU8`)
/// and only need the `FamilyMask` wrapper at the end.
#[inline]
pub fn bits(self) -> u8 {
self.0 & PRESENCE_BITS
}
/// Construct from a raw presence bitmask (only the low 4 bits are kept —
/// the minorant flag is not part of this, use [`with_minorant`](Self::with_minorant)
/// separately).
#[inline]
pub fn from_bits(bits: u8) -> Self {
FamilyMask(bits & 0b1111)
FamilyMask(bits & PRESENCE_BITS)
}
#[inline]
@@ -101,10 +133,13 @@ impl FamilyMask {
fn decode(byte: u8) -> Option<Self> {
if byte == 0 {
// Unreachable for a real result — reserved as the "not yet
// computed" sentinel.
// computed" sentinel. Still safe as a sentinel with the
// minorant bit added: a real entry always has at least one
// presence bit set (bits 0-3), so byte == 0 still means
// "nothing written yet" and never a genuine minorant-only value.
return None;
}
Some(FamilyMask(byte & 0b1111))
Some(FamilyMask(byte))
}
}