Struct SegmentManager 

pub struct SegmentManager<D: DirectoryWriter + 'static> { /* private fields */ }

Segment manager — coordinates segment commit, background merging, and trained structures.

SOLE owner of metadata.json. All metadata mutations go through state Mutex.

Implementations

impl<D: DirectoryWriter + 'static> SegmentManager<D>

pub fn new( directory: Arc<D>, schema: Arc<Schema>, metadata: IndexMetadata, merge_policy: Box<dyn MergePolicy>, term_cache_blocks: usize, max_concurrent_merges: usize, ) -> Self

Create a new segment manager with existing metadata

pub async fn get_segment_ids(&self) -> Vec<String>

Get the current segment IDs

pub fn trained(&self) -> Option<Arc<TrainedVectorStructures>>

Get trained vector structures (lock-free via ArcSwap)

pub async fn load_and_publish_trained(&self)

Load trained structures from disk and publish to ArcSwap. Copies metadata under lock, releases lock, then does disk I/O.

pub async fn acquire_snapshot(&self) -> SegmentSnapshot

Acquire a snapshot of current segments for reading. The snapshot holds references — segments won’t be deleted while snapshot exists.

pub fn tracker(&self) -> Arc<SegmentTracker>

Get the segment tracker

pub fn directory(&self) -> Arc<D>

Get the directory

impl<D: DirectoryWriter + 'static> SegmentManager<D>

pub async fn commit(&self, new_segments: Vec<(String, u32)>) -> Result<()>

Atomic commit: register new segments + persist metadata.

pub async fn maybe_merge(self: &Arc<Self>)

Evaluate merge policy and spawn background merges for all eligible candidates.

Single lock scope: builds segment list AND calls find_merges atomically to prevent stale-list races with concurrent replace_segments. Segments already involved in active merges are excluded from policy evaluation so the policy only sees truly available segments.

Note: max_concurrent_merges is a soft limit — concurrent auto-triggers may briefly exceed it by one or two due to TOCTOU between slot counting and handle registration.

pub async fn wait_for_merging_thread(self: &Arc<Self>)

Wait for all current in-flight merges to complete.

pub async fn wait_for_all_merges(self: &Arc<Self>)

Wait for all eligible merges to complete, including cascading merges.

Drains current handles, then loops. Each completed merge auto-triggers maybe_merge (which pushes new handles) before its JoinHandle resolves, so by the time h.await returns all cascading handles are registered.

pub async fn force_merge(self: &Arc<Self>) -> Result<()>

Force merge all segments into one. Iterates in batches until ≤1 segment remains.

Each batch is registered in merge_inventory via MergeGuard to prevent maybe_merge from spawning a conflicting background merge.

pub async fn cleanup_orphan_segments(&self) -> Result<usize>

Clean up orphan segment files not registered in metadata.

Non-blocking: reads both metadata and merge_inventory to determine which segments are legitimate. In-flight merge outputs are protected by the inventory.