Skip to main content

ConsistentRing

Struct ConsistentRing 

Source
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>

Source

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.

Source

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.

Source

pub fn remove_node(&mut self, identifier: &str)

Removes a physical node and all its virtual positions; an unknown identifier has no effect.

Source

pub fn contains_identifier(&self, identifier: &str) -> bool

Returns whether a physical node with this identifier is registered.

Source

pub fn physical_nodes(&self) -> &[PhysicalRingNode<'a, T>]

Returns the physical nodes and their weights in insertion order.

Source

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.

Source

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.

Source

pub fn calculate_migration_on_add( &self, new_node: &'a T, new_identifier: &str, new_replica_multiplier: usize, ) -> Result<Vec<TokenRangeMigration<T>>, RingError>
where T: Clone, BH: Clone,

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.

Source

pub fn calculate_migration_on_remove( &self, identifier: &str, ) -> Vec<TokenRangeMigration<T>>
where T: Clone, BH: Clone,

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.

Source

pub fn get_node<K: Hash>(&self, key: &K) -> Option<&'a T>

Returns the primary owner of key, or None for an empty ring.

Source

pub fn len(&self) -> usize

Returns the number of virtual nodes in the ring.

Source

pub fn is_empty(&self) -> bool

Returns whether the ring has no virtual nodes.

Trait Implementations§

Source§

impl<'a, T: Clone, BH: Clone + BuildHasher> Clone for ConsistentRing<'a, T, BH>

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more

Auto Trait Implementations§

§

impl<'a, T, BH> Freeze for ConsistentRing<'a, T, BH>
where Vec<PhysicalRingNode<'a, T>>: Freeze, BH: Freeze,

§

impl<'a, T, BH> RefUnwindSafe for ConsistentRing<'a, T, BH>

§

impl<'a, T, BH> Send for ConsistentRing<'a, T, BH>
where Vec<PhysicalRingNode<'a, T>>: Send, BH: Send,

§

impl<'a, T, BH> Sync for ConsistentRing<'a, T, BH>
where Vec<PhysicalRingNode<'a, T>>: Sync, BH: Sync,

§

impl<'a, T, BH> Unpin for ConsistentRing<'a, T, BH>
where Vec<PhysicalRingNode<'a, T>>: Unpin, BH: Unpin,

§

impl<'a, T, BH> UnsafeUnpin for ConsistentRing<'a, T, BH>

§

impl<'a, T, BH> UnwindSafe for ConsistentRing<'a, T, BH>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.