pub struct ClusterManager<'a, T, BH: BuildHasher> { /* private fields */ }Expand description
Manages physical node membership through a ConsistentRing.
The ring borrows each physical value and stores its weight once. Callers must keep values alive while the manager uses them. This type provides checked membership changes and delegates placement to the ring.
§Example
use xxhash_rust::xxh3::Xxh3Builder;
use ringlet_hash::{ClusterManager, RingConfig};
let mut cluster = ClusterManager::try_new(RingConfig {
virtual_node_base_count: 50,
build_hasher: Xxh3Builder::new().with_seed(0),
})?;
let server_a = String::from("server-a");
let server_b = String::from("server-b");
cluster.add_node(&server_a, "a", 1)?;
cluster.add_node(&server_b, "b", 2)?;
let moves = cluster.calculate_migration_on_remove("a")?;
assert!(!moves.is_empty());
cluster.remove_node("a")?;
assert_eq!(cluster.get_node(&"customer-42"), Some(&server_b));
Ok::<(), ringlet_hash::RingError>(())Implementations§
Source§impl<'a, T, BH: BuildHasher> ClusterManager<'a, T, BH>
impl<'a, T, BH: BuildHasher> ClusterManager<'a, T, BH>
Sourcepub fn try_new(config: RingConfig<BH>) -> Result<Self, RingError>
pub fn try_new(config: RingConfig<BH>) -> Result<Self, RingError>
Creates a manager with an empty ring.
Returns RingError::EmptyRing if the base virtual node count is zero.
Sourcepub fn nodes(&self) -> &[PhysicalRingNode<'a, T>]
pub fn nodes(&self) -> &[PhysicalRingNode<'a, T>]
Returns physical nodes and weights in insertion order.
Sourcepub fn ring(&self) -> &ConsistentRing<'a, T, BH>
pub fn ring(&self) -> &ConsistentRing<'a, T, BH>
Returns the ring for read-only lookups and token inspection.
Sourcepub fn add_node(
&mut self,
node: &'a T,
identifier: &str,
replica_multiplier: usize,
) -> Result<(), RingError>
pub fn add_node( &mut self, node: &'a T, identifier: &str, replica_multiplier: usize, ) -> Result<(), RingError>
Adds a physical node with the given identifier and replica multiplier.
The multiplier is a relative placement weight, not a replica count.
The caller must choose a weight that reflects the node’s capacity.
Returns RingError::NodeAlreadyExists for a duplicate identifier or
RingError::ZeroWeight for a zero multiplier.
Sourcepub fn remove_node(&mut self, identifier: &str) -> Result<(), RingError>
pub fn remove_node(&mut self, identifier: &str) -> Result<(), RingError>
Removes a physical node and all its virtual nodes.
Returns RingError::NodeNotFound for an unknown identifier.
Sourcepub fn calculate_migration_on_add(
&self,
new_node: &'a T,
identifier: &str,
replica_multiplier: usize,
) -> Result<Vec<TokenRangeMigration<T>>, RingError>
pub fn calculate_migration_on_add( &self, new_node: &'a T, identifier: &str, replica_multiplier: usize, ) -> Result<Vec<TokenRangeMigration<T>>, RingError>
Previews migration ranges for adding a node without changing membership.
Returns RingError::NodeAlreadyExists for a duplicate identifier or
RingError::ZeroWeight for a zero multiplier.
Sourcepub fn calculate_migration_on_remove(
&self,
identifier: &str,
) -> Result<Vec<TokenRangeMigration<T>>, RingError>
pub fn calculate_migration_on_remove( &self, identifier: &str, ) -> Result<Vec<TokenRangeMigration<T>>, RingError>
Previews migration ranges for removing a node without changing membership.
Returns RingError::NodeNotFound for an unknown identifier. Removing
the last node has no migration destination and returns an empty list.
Sourcepub fn get_node<K: Hash>(&self, key: &K) -> Option<&'a T>
pub fn get_node<K: Hash>(&self, key: &K) -> Option<&'a T>
Returns the primary owner of key, or None for an empty cluster.