Struct MmapStorage 

pub struct MmapStorage { /* private fields */ }

Memory-mapped file storage for vectors.

Uses a combination of an index file (ID -> offset) and a data file (raw vectors). Also implements a simple WAL for durability.

Implementations

impl MmapStorage

pub fn new<P: AsRef<Path>>(path: P, dimension: usize) -> Result<Self>

Creates a new MmapStorage or opens an existing one.

Uses the default durability mode (Fsync).

Arguments

• path - Directory to store data
• dimension - Vector dimension

Errors

Returns an error if file operations fail.

pub fn new_with_durability<P: AsRef<Path>>( path: P, dimension: usize, durability: DurabilityMode, ) -> Result<Self>

Creates a new MmapStorage with the specified durability mode.

See DurabilityMode for available modes and their trade-offs.

Issue #423 Component 4: DurabilityMode::None skips WAL writes entirely for bulk import scenarios. Data is written directly to the mmap file and is readable immediately, but not recoverable from WAL after a crash.

Arguments

• path - Directory to store data
• dimension - Vector dimension
• durability - WAL write/sync behavior

Errors

Returns an error if file operations fail.

pub fn durability(&self) -> DurabilityMode

Returns the current durability mode.

pub fn set_durability_mode(&mut self, mode: DurabilityMode)

Sets the durability mode at runtime.

pub fn metrics(&self) -> &StorageMetrics

Returns a reference to the storage metrics.

pub fn retrieve_ref(&self, id: u64) -> Result<Option<VectorSliceGuard<'_>>>

Retrieves a vector by ID without copying (zero-copy).

Returns a guard providing direct mmap access. Faster than retrieve() as it eliminates heap allocation and memcpy. Guard must be dropped to release lock.

Errors

Returns an error if the stored offset is out of bounds.

Panics

Panics if the stored offset is not f32-aligned (must be multiple of 4). This should never happen with properly stored data.

pub fn flush_index(&self) -> Result<()>

Persists the vectors.idx index file to disk with fsync.

Issue #423: Extracted from the former flush() to allow callers to control when the (expensive) index serialization happens. The WAL provides crash recovery even if this file is stale, so it can be deferred to compaction or explicit shutdown.

Errors

Returns an error if serialization or I/O fails.

pub fn flush_full(&mut self) -> Result<()>

Full durability flush: WAL + mmap + vectors.idx.

Equivalent to the pre-#423 flush() behavior. Use this on shutdown or before compaction to ensure the index file is up-to-date, avoiding a full WAL replay on the next startup.

Errors

Returns an error if any I/O operation fails.

impl MmapStorage

pub fn reserve_capacity(&mut self, vector_count: usize) -> Result<()>

Pre-allocates storage capacity for a known number of vectors.

Errors

Returns an error if file operations fail.

pub fn compact(&mut self) -> Result<usize>

Compacts the storage by rewriting only active vectors.

Returns

The number of bytes reclaimed.

Errors

Returns an error if file operations fail.

pub fn fragmentation_ratio(&self) -> f64

Returns the fragmentation ratio (0.0 = no fragmentation, 1.0 = 100% fragmented).

Trait Implementations

impl Drop for MmapStorage

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl VectorStorage for MmapStorage

fn store(&mut self, id: u64, vector: &[f32]) -> Result<()>

Stores a vector with the given ID.

fn store_batch(&mut self, vectors: &[(u64, &[f32])]) -> Result<usize>

Stores multiple vectors in a single batch operation.

fn retrieve(&self, id: u64) -> Result<Option<Vec<f32>>>

Retrieves a vector by ID.

fn delete(&mut self, id: u64) -> Result<()>

Deletes a vector by ID.

fn flush(&mut self) -> Result<()>

Flushes pending writes to disk.

fn len(&self) -> usize

Returns the number of vectors stored.

fn ids(&self) -> Vec<u64>

Returns all stored IDs.

fn is_empty(&self) -> bool

Returns true if the storage is empty.