Struct SegmentManager 

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

Segment manager - coordinates segment registration and background merging

This is the SOLE owner of metadata.json ensuring linearized access. All segment list modifications and metadata updates go through here.

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, ) -> Self

Create a new segment manager with existing metadata

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

Get the current segment IDs (snapshot)

pub async fn register_segment(&self, segment_id: String) -> Result<()>

Register a new segment, persist metadata, and trigger merge check

This is the main entry point for adding segments after builds complete. It atomically:

1. Adds the segment ID to the list
2. Registers with tracker for reference counting
3. Persists metadata to disk
4. Triggers merge check (spawns background merges if needed)

pub fn pending_merge_count(&self) -> usize

Get the number of pending background merges

pub async fn maybe_merge(&self)

Check merge policy and spawn background merges if needed

pub async fn wait_for_merges(&self)

Wait for all pending merges to complete

pub fn metadata(&self) -> Arc<AsyncMutex<IndexMetadata>>

Get a clone of the metadata Arc for read access

pub async fn update_metadata<F>(&self, f: F) -> Result<()>

where F: FnOnce(&mut IndexMetadata),

Update metadata with a closure and persist atomically

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

Replace segment list atomically (for force merge / rebuild)

pub async fn acquire_snapshot(&self) -> SegmentSnapshot<D>

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

This is atomic: we hold the metadata lock while acquiring refs to prevent a race where a merge completes between getting segment IDs and acquiring refs.

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

Get the segment tracker

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

Get the directory

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

Clean up orphan segment files that are not registered

This can happen if the process halts after segment files are written but before they are registered in metadata.json. Call this on startup to reclaim disk space from incomplete operations.

Returns the number of orphan segments deleted.