pub struct ConsistentRing<'a, T, BH: BuildHasher> { /* private fields */ }Expand description
A consistent hashing ring of physical nodes of type T.
The ring borrows each physical value and stores its identifier and weight
once. Virtual positions refer to it by index. Values must outlive the ring.
len counts virtual nodes, not physical nodes. Ordinary
membership changes and lookups accept values that do not implement Clone;
migration previews require it because they return owned node values.
Implementations§
Source§impl<'a, T, BH: BuildHasher> ConsistentRing<'a, T, BH>
impl<'a, T, BH: BuildHasher> ConsistentRing<'a, T, BH>
Sourcepub fn try_new(config: RingConfig<BH>) -> Result<Self, RingError>
pub fn try_new(config: RingConfig<BH>) -> Result<Self, RingError>
Creates an empty ring with the supplied configuration.
Returns RingError::EmptyRing if virtual_node_base_count is zero.
Sourcepub fn add_node(
&mut self,
node: &'a T,
identifier: &str,
replica_multiplier: usize,
) -> Result<String, RingError>
pub fn add_node( &mut self, node: &'a T, identifier: &str, replica_multiplier: usize, ) -> Result<String, RingError>
Adds a physical node and returns its identifier.
The node gets virtual_node_base_count * replica_multiplier positions.
The multiplier is a relative placement weight, not a replica count;
the caller must decide whether it matches the node’s actual capacity.
The product is not checked for overflow or capped for memory use.
Returns RingError::NodeAlreadyExists for a duplicate identifier and
RingError::ZeroWeight for a zero multiplier.
Sourcepub fn remove_node(&mut self, identifier: &str)
pub fn remove_node(&mut self, identifier: &str)
Removes a physical node and all its virtual positions; an unknown identifier has no effect.
Sourcepub fn contains_identifier(&self, identifier: &str) -> bool
pub fn contains_identifier(&self, identifier: &str) -> bool
Returns whether a physical node with this identifier is registered.
Sourcepub fn physical_nodes(&self) -> &[PhysicalRingNode<'a, T>]
pub fn physical_nodes(&self) -> &[PhysicalRingNode<'a, T>]
Returns the physical nodes and their weights in insertion order.
Sourcepub fn find_start_index(&self, target_hash: u64) -> usize
pub fn find_start_index(&self, target_hash: u64) -> usize
Returns the index of the first virtual node at or after target_hash.
The search wraps to index 0 beyond the last token. An empty ring also
returns 0; check is_empty before indexing.
Sourcepub fn get_nodes<K: Hash>(&self, key: &K, count: usize) -> Vec<&'a T>
pub fn get_nodes<K: Hash>(&self, key: &K, count: usize) -> Vec<&'a T>
Returns up to count distinct physical nodes for a key, in ring order.
The first result is the primary owner returned by get_node.
The result is empty for an empty ring or a zero count, and may contain
fewer than count nodes when the ring has fewer distinct identifiers.
The caller must check the returned length and store any desired copies.
Sourcepub fn calculate_migration_on_add(
&self,
new_node: &'a T,
new_identifier: &str,
new_replica_multiplier: usize,
) -> Result<Vec<TokenRangeMigration<T>>, RingError>
pub fn calculate_migration_on_add( &self, new_node: &'a T, new_identifier: &str, new_replica_multiplier: usize, ) -> Result<Vec<TokenRangeMigration<T>>, RingError>
Previews token ranges associated with adding a node without changing this ring.
Each returned entry identifies an existing owner at a new virtual token
and the proposed destination. An empty ring has no source to migrate
from, so it returns an empty list. A zero multiplier returns
RingError::ZeroWeight.
Sourcepub fn calculate_migration_on_remove(
&self,
identifier: &str,
) -> Vec<TokenRangeMigration<T>>
pub fn calculate_migration_on_remove( &self, identifier: &str, ) -> Vec<TokenRangeMigration<T>>
Previews token ranges that would leave identifier on removal.
Each range is (start_hash, end_hash] on the hash ring, wrapping at
u64::MAX. The ring is unchanged. Returns an empty list when the
identifier is absent or when removal would leave no destination node.