Struct TurboCollectionState 

pub struct TurboCollectionState {
    pub dim: usize,
    pub metric: DistanceMetric,
    pub index: Mutex<RawMutex, TurboQuantIndex>,
    pub extent: Mutex<RawMutex, Option<TurboExtent>>,
    /* private fields */
}

Per-collection runtime state for a vector.turbo collection.

index is the in-memory TurboQuant index that owns the encoded codes + raw vectors; extent is the per-collection page-backed payload buffer when the store is in paged mode (None for in-memory runtimes). Both are wrapped in Mutex because INSERTs serialize on the per-collection state — the contention point lives here rather than on the global store lock.

Fields

dim: usize

metric: DistanceMetric

index: Mutex<RawMutex, TurboQuantIndex>

extent: Mutex<RawMutex, Option<TurboExtent>>

Implementations

impl TurboCollectionState

pub fn new( dim: usize, metric: DistanceMetric, pager: Option<&Arc<Pager>>, ) -> TurboCollectionState

pub fn set_snapshot_path(&self, path: Option<PathBuf>)

Set (or clear) the .tv snapshot path for this collection. Called by RedDB::turbo_state once the resolved TieredLayoutPaths is known.

pub fn snapshot_path(&self) -> Option<PathBuf>

Current .tv snapshot path, if any.

pub fn is_ready(&self) -> bool

Returns the current readiness flag. true means the background rebuild (or lazy populate) has completed and the in-memory index reflects every WAL-acked INSERT.

pub fn wait_until_ready(&self, timeout: Duration) -> bool

Block the caller (with a bounded timeout) until the collection becomes ready. Returns true if ready within the timeout, false if the timeout fired. A zero-or-negative timeout still does one fast-path check.

pub fn ensure_populated(&self, store: &UnifiedStore, collection: &str)

Lazily populate the in-memory index from any vector entities already persisted in the collection, then drain any WAL-replayed VectorInsert records captured at store-open time (issue #694).

Boot-time recovery: the WAL VectorInsert records are the authoritative source for vectors that may not have made it into the entity manager’s persisted state (e.g. a crash between WAL fsync and the next paged flush). Replaying them in WAL order under a fixed codec seed reconstructs the in-memory TurboQuantIndex deterministically — including the partial-block tail introduced by ADR 0024.

Non-vector traffic does not block on this rebuild: the runtime only takes this path on the first turbo INSERT/SEARCH after boot. #673 wires the per-collection ready: bool flag on top of this hook to keep vector traffic from observing a half-built index while the rebuild is in flight.

pub fn dump_snapshot_async(self: &Arc<TurboCollectionState>, lsn: u64)

Capture the current in-memory index state and dump it to the configured .tv path on a worker thread (#674). The next caller (typically the next WAL checkpoint cycle) blocks on the previous worker before starting a new one — bounded backpressure of at most one dump in flight per collection. The WAL checkpoint itself never waits for the snapshot fsync.

No-op when snapshot_path is None (StorageLayout::Minimal or embedded mode) — preserves the single-file portability story.

pub fn wait_snapshot(&self)

Join the in-flight snapshot worker, if any. Used by RedDB::Drop to make sure no .tv write outlives the runtime, and by tests that want to assert the on-disk state synchronously.

pub fn background_rebuild(&self, store: &UnifiedStore, collection: &str)

Background-rebuild hook (#694 / #673). Drives the same code path as ensure_populated; safe to call from a worker thread. On completion the per-collection readiness flag flips and any SEARCH callers parked on wait_until_ready are woken.