Struct ContiguousVectors 

pub struct ContiguousVectors { /* private fields */ }

Contiguous memory layout for vectors (cache-friendly).

Stores all vectors in a single contiguous buffer to maximize cache locality and enable SIMD prefetching.

Memory Layout

[v0_d0, v0_d1, ..., v0_dn, v1_d0, v1_d1, ..., v1_dn, ...]

Safety Invariants (EPIC-032/US-002)

• data is always non-null (enforced by NonNull)
• data points to memory allocated with 64-byte alignment
• capacity * dimension * sizeof(f32) bytes are always allocated
• count <= capacity is always maintained

Implementations

impl ContiguousVectors

pub fn reorder(&mut self, new_order: &[usize]) -> Result<()>

Reorders vectors according to the given permutation.

new_order[i] contains the old index of the vector that should occupy position i after reordering. The permutation must have exactly self.len() elements and every index must be < self.len().

Errors

Returns an error if:

• new_order.len() != self.len()
• Any index in new_order is out of bounds
• The new buffer allocation fails

pub fn dot_product(&self, index: usize, query: &[f32]) -> Option<f32>

Computes dot product with another vector using SIMD.

pub fn batch_dot_products(&self, indices: &[usize], query: &[f32]) -> Vec<f32>

Computes batch dot products with a query vector.

This is optimized for HNSW search with prefetching.

impl ContiguousVectors

pub fn ensure_capacity(&mut self, required_capacity: usize) -> Result<()>

Ensures the storage has capacity for at least required_capacity vectors.

Errors

Returns Error::AllocationFailed if reallocation fails.

pub fn reserve_additional(&mut self, additional: usize) -> Result<()>

Pre-allocates capacity for additional more vectors beyond the current length.

Analogous to Vec::reserve: ensures the buffer can hold self.len() + additional vectors without reallocating. No-op if sufficient capacity already exists.

Call before a batch push to guarantee push_batch won’t resize.

Errors

Returns Error::AllocationFailed if reallocation fails.

impl ContiguousVectors

pub fn new(dimension: usize, capacity: usize) -> Result<Self>

Creates a new ContiguousVectors with the given dimension and initial capacity.

Arguments

• dimension - Vector dimension (must be > 0)
• capacity - Initial capacity (number of vectors)

Errors

Returns Error::InvalidDimension if dimension is 0 or exceeds MAX_DIMENSION. Returns Error::AllocationFailed if memory allocation fails or exceeds the AllocGuard ceiling.

pub const fn dimension(&self) -> usize

Returns the dimension of stored vectors.

pub const fn len(&self) -> usize

Returns the number of vectors stored.

pub const fn is_empty(&self) -> bool

Returns true if no vectors are stored.

pub const fn capacity(&self) -> usize

Returns the capacity (max vectors before reallocation).

pub fn as_flat_slice(&self) -> &[f32]

Returns the raw contiguous buffer as a flat slice.

The slice contains all vectors packed sequentially: [v0_d0, v0_d1, ..., v1_d0, ...]. Useful for GPU upload without copying.

pub fn gather_flat(&self, indices: &[usize]) -> Vec<f32>

Gathers vectors at the specified indices into a contiguous flat buffer.

Returns a new Vec<f32> containing the selected vectors packed sequentially. Useful for GPU upload when only a subset of vectors is needed (e.g., reranking).

Important

Out-of-bounds indices are silently skipped — the result may contain fewer vectors than indices.len(). Callers must validate result.len() == indices.len() * dimension before using the result in positional operations (e.g., zip with an ID map), otherwise scores will be misattributed to wrong IDs.

pub const fn memory_bytes(&self) -> usize

Returns total memory usage in bytes.

Saturates instead of overflowing; capacity * dimension * 4 was validated to fit in usize at allocation time, so saturation is unreachable for a live buffer and exists purely as a defensive backstop (#899).

pub fn insert_at(&mut self, index: usize, vector: &[f32]) -> Result<()>

Inserts a vector at a specific index.

Automatically grows capacity if needed. Note: This allows sparse population. Uninitialized slots contain undefined data (or 0.0 if alloc gave zeroed memory).

Errors

Returns crate::error::Error::DimensionMismatch if vector.len() != self.dimension. Returns Error::AllocationFailed if capacity growth fails.

pub fn push(&mut self, vector: &[f32]) -> Result<()>

Adds a vector to the storage.

Errors

Returns crate::error::Error::DimensionMismatch if vector.len() != self.dimension. Returns Error::AllocationFailed if capacity growth fails.

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

Adds multiple vectors in batch (optimized).

Arguments

• vectors - Iterator of vectors to add

Returns

Number of vectors added.

Errors

Returns crate::error::Error::DimensionMismatch or Error::AllocationFailed on the first vector that fails. Vectors added before the failure remain in storage.

pub fn get(&self, index: usize) -> Option<&[f32]>

Gets a vector by index.

Returns

Slice to the vector data, or None if index is out of bounds.

pub unsafe fn get_unchecked(&self, index: usize) -> &[f32]

Gets a vector by index (unchecked).

Safety

Caller must ensure index < self.len().

Debug Assertions

In debug builds, this function will panic if index >= self.len(). This catches bugs early during development without impacting release performance.

pub fn prefetch(&self, index: usize)

Prefetches a vector into multiple cache levels for upcoming access.

Uses cross-platform multi-cache-line prefetch (x86_64 + aarch64 + no-op fallback) to warm CPU caches before SIMD distance computation.

Trait Implementations

impl Debug for ContiguousVectors

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for ContiguousVectors

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 Send for ContiguousVectors

impl Sync for ContiguousVectors