Struct BlockStoreSharding 

pub struct BlockStoreSharding {
    pub config: ShardingConfig,
    pub total_insertions: u64,
    pub total_lookups: u64,
    pub total_bytes: u64,
    /* private fields */
}

A sharded, content-addressed block store.

Distributes blocks across num_shards logical shards using FNV-1a hashing of the CID. Provides per-shard metrics, rebalancing, and LRU eviction.

Fields

config: ShardingConfig

Runtime configuration.

total_insertions: u64

Total insertions since creation (new + replaced).

total_lookups: u64

Total get calls since creation.

total_bytes: u64

Total bytes currently stored.

Implementations

impl BlockStoreSharding

pub fn new(config: ShardingConfig) -> Self

Creates a new BlockStoreSharding with the given configuration.

Panics if config.num_shards == 0.

pub fn shard_for_cid(&self, cid: &str) -> ShardKey

Deterministically maps a CID string to a shard using FNV-1a % num_shards.

pub fn put( &mut self, cid: String, data: Vec<u8>, now: u64, ) -> Result<bool, ShardingError>

Inserts or replaces a block.

Returns Ok(true) if the block was newly inserted, Ok(false) if an existing block for the same CID was replaced. Returns Err(ShardingError::ShardFull) if the shard is at capacity and there is no existing entry for the CID to replace.

pub fn get(&mut self, cid: &str) -> Option<&BlockRecord>

Looks up a block by CID.

Updates the shard’s hit_count / miss_count and, on hit, increments the record’s access_count. Returns None if not found.

pub fn get_mut(&mut self, cid: &str) -> Option<&mut BlockRecord>

Returns a mutable reference to a block record (no metrics update).

pub fn contains(&self, cid: &str) -> bool

Returns true if the CID is present in the store.

pub fn remove(&mut self, cid: &str) -> bool

Removes a block by CID.

Returns true if the block existed and was removed, false otherwise.

pub fn shard_metrics(&self, shard: ShardKey) -> Option<&ShardMetrics>

Returns metrics for a specific shard, or None if the shard id is out of range.

pub fn all_shard_metrics(&self) -> &[ShardMetrics]

Returns a slice of per-shard metrics.

pub fn needs_rebalance(&self) -> bool

Returns true when at least one shard exceeds avg * (1 + threshold).

Returns false when no blocks are stored.

pub fn rebalance(&mut self, now: u64) -> usize

Rebalances the store by moving blocks from over-loaded shards to under-loaded shards.

For each shard that exceeds the average by more than the threshold, the function removes the surplus blocks (those with the lowest access_count) and re-inserts them using their natural shard_for_cid routing. This is a no-op if the shard they naturally belong to has not changed (e.g. due to the same num_shards); however the inserted_at timestamp is refreshed to now.

Returns the total number of blocks moved.

pub fn evict_lru(&mut self, shard: ShardKey, count: usize) -> usize

Evicts up to count blocks from the given shard, preferring blocks with the lowest access_count (LRU approximation).

Returns the number of blocks actually evicted (may be less than count if the shard has fewer blocks).

pub fn cids_in_shard(&self, shard: ShardKey) -> Vec<&str>

Returns all CIDs stored in the given shard.

pub fn total_block_count(&self) -> usize

Returns the total number of blocks across all shards.

pub fn total_bytes(&self) -> u64

Returns the total bytes stored across all shards.

pub fn global_stats(&self) -> BlockStoreGlobalStats

Returns a snapshot of global statistics.