Struct ConsistentHashRing 

pub struct ConsistentHashRing { /* private fields */ }

A consistent hash ring for routing documents to shards.

The ring uses virtual nodes to achieve better load distribution across shards. Each physical shard is represented by multiple virtual nodes on the ring, which helps ensure that documents are distributed evenly.

Thread Safety

The ring itself is Clone and can be wrapped in Arc<RwLock<_>> for thread-safe access with dynamic updates, or Arc<_> for read-only concurrent access.

Example

use phago_distributed::hashing::ConsistentHashRing;
use phago_core::types::DocumentId;

let ring = ConsistentHashRing::new(3);
let doc_id = DocumentId::from_seed(42);
let shard = ring.get_shard(&doc_id);
println!("Document maps to shard: {}", shard);

Implementations

impl ConsistentHashRing

pub fn new(num_shards: u32) -> Self

Create a new hash ring with the specified number of shards.

Each shard will be represented by VIRTUAL_NODES_PER_SHARD virtual nodes on the ring for better distribution.

Arguments

• num_shards - The number of physical shards to distribute across

Panics

Panics if num_shards is 0.

pub fn with_virtual_nodes(num_shards: u32, virtual_nodes: u32) -> Self

Create a new hash ring with custom virtual nodes per shard.

More virtual nodes generally result in better distribution but increase memory usage and lookup time slightly.

Arguments

• num_shards - The number of physical shards
• virtual_nodes - Number of virtual nodes per shard

pub fn get_shard(&self, doc_id: &DocumentId) -> ShardId

Get the shard ID for a document.

This operation is O(log n) where n is the total number of virtual nodes.

Arguments

• doc_id - The document ID to route

Returns

The shard ID that should store this document.

pub fn get_shard_for_key<K: Hash>(&self, key: &K) -> ShardId

Get the shard ID for an arbitrary key.

This is useful for routing non-document data to shards.

Arguments

• key - Any hashable key

pub fn add_shard(&mut self, shard_id: ShardId)

Add a new shard to the ring.

This will redistribute approximately 1 / (n+1) of the keys from existing shards to the new shard, where n is the current number of shards.

Arguments

• shard_id - The shard ID to add

pub fn remove_shard(&mut self, shard_id: ShardId)

Remove a shard from the ring.

Documents previously assigned to this shard will be redistributed to the next shard in the ring (clockwise).

Arguments

• shard_id - The shard ID to remove

pub fn shard_count(&self) -> u32

Get the number of shards.

pub fn all_shards(&self) -> Vec<ShardId>

Get all shard IDs in the ring.

Returns a sorted, deduplicated list of all shard IDs.

pub fn virtual_nodes_per_shard(&self) -> u32

Get the number of virtual nodes per shard.

pub fn total_virtual_nodes(&self) -> usize

Get the total number of virtual nodes in the ring.

pub fn get_replica_shards( &self, doc_id: &DocumentId, replica_count: usize, ) -> Vec<ShardId>

Get replica shards for a document.

Returns the primary shard plus replica_count additional shards that should store replicas of the document.

Arguments

• doc_id - The document ID
• replica_count - Number of additional replicas (excluding primary)

Returns

A vector of shard IDs, with the primary shard first.

Trait Implementations

impl Clone for ConsistentHashRing

fn clone(&self) -> ConsistentHashRing

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ConsistentHashRing

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ConsistentHashRing

fn default() -> Self

Returns the “default value” for a type.