Struct ShardBalancer 

pub struct ShardBalancer { /* private fields */ }

Tracks per-shard load and makes placement / rebalancing decisions.

All load counters use AtomicUsize so concurrent updates from multiple async tasks require no mutex.

Implementations

impl ShardBalancer

pub fn new(config: ShardConfig) -> Self

Create a new ShardBalancer with the given configuration.

Panics

Panics if config.num_shards == 0.

pub fn assign_vector(&self, vector_id: u64) -> usize

Return the shard that should store the vector with the given id.

Uses Knuth multiplicative hashing for a uniform distribution.

pub fn least_loaded_shard(&self) -> usize

Return the shard index with the lowest current load.

In the case of a tie the shard with the smaller index wins, giving stable, deterministic behaviour in tests.

pub fn increment_shard_load(&self, shard_id: usize)

Atomically increment the vector count for the given shard.

pub fn decrement_shard_load(&self, shard_id: usize)

Atomically decrement the vector count for the given shard.

Saturates at zero to avoid underflow.

pub fn shard_loads_snapshot(&self) -> Vec<usize>

Return a point-in-time snapshot of all shard load counts.

pub fn rebalance_needed(&self) -> bool

Return true when the ratio of the most-loaded shard to the least-loaded shard exceeds 2.0 (ignoring empty shards with zero load).

pub fn hotspot_shards(&self) -> Vec<usize>

Return the indices of shards whose load exceeds the average load.

pub fn config(&self) -> &ShardConfig

Expose configuration for inspection.