Struct consistent_hash_ring::Ring

pub struct Ring<T: Hash + Eq + Clone, S = FnvBuildHasher> { /* fields omitted */ }

A consistent hash ring with support for vnodes and key replication.

Methods

impl<T: Hash + Eq + Clone, S: BuildHasher> Ring<T, S>

pub fn len(&self) -> usize

Returns the number of nodes in the ring (not including any duplicate vnodes).

use consistent_hash_ring::*;

let ring = RingBuilder::default()
    .nodes_iter(0..32)
    .build();
assert_eq!(32, ring.len());

pub fn is_empty(&self) -> bool

Returns whether or not the ring is empty.

use consistent_hash_ring::*;

let mut ring = Ring::default();
assert!(ring.is_empty());
ring.insert(&());
assert!(!ring.is_empty());

pub fn vnodes(&self) -> usize

Returns the total number of vnodes in the ring, across all nodes.

use consistent_hash_ring::*;

let ring = RingBuilder::default()
    .vnodes(4)
    .nodes_iter(0..12)
    .build();
assert_eq!(48, ring.vnodes());
assert_eq!(12, ring.len());

pub fn weight(&self, node: &T) -> usize

Returns the number of vnodes for the provided node, or 0 if it does not exist.

use consistent_hash_ring::*;

let mut ring = RingBuilder::default()
    .vnodes(12)
    .nodes_iter(0..4)
    .build();
ring.insert_weight(&42, 9);
assert_eq!(12, ring.weight(&3));
assert_eq!(9, ring.weight(&42));
assert_eq!(0, ring.weight(&24));

pub fn insert(&mut self, node: &T)

Insert a node into the ring with the default vnode count.

use consistent_hash_ring::*;

let mut ring = Ring::default();
ring.insert(b"hello worldo");
assert_eq!(1, ring.len());
assert_eq!(10, ring.weight(b"hello worldo"));

pub fn insert_weight(&mut self, node: &T, vnodes: usize)

Insert a node into the ring with the provided number of vnodes.

This can be used give some nodes more weight than others - nodes with more vnodes will be selected for larger proportions of keys.

If the provided node is already present in the ring with a lower vnode count, the count is updated. If the existing count is higher, this method does nothing.

use consistent_hash_ring::*;

let mut ring = Ring::default();
ring.insert(b"hello worldo");
ring.insert_weight(b"worldo hello", 9);
assert_eq!(2, ring.len());
assert_eq!(10, ring.weight(b"hello worldo"));
assert_eq!(9, ring.weight(b"worldo hello"));

pub fn remove(&mut self, node: &T)

Remove a node from the ring.

Any keys that were mapped to this node will be uniformly distributed amongst any remaining nodes.

use consistent_hash_ring::*;

let mut ring = RingBuilder::default()
    .nodes_iter(0..12)
    .build();
assert_eq!(12, ring.len());
assert_eq!(10, ring.weight(&3));
ring.remove(&3);
assert_eq!(11, ring.len());
assert_eq!(0, ring.weight(&3));

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

Returns a reference to the first node responsible for the provided key.

Any key type may be used so long as it is Hash.

Returns None if there are no nodes in the ring.

use consistent_hash_ring::*;

let mut ring = RingBuilder::default()
    .vnodes(12)
    .build();
assert_eq!(None, ring.try_first(b"none"));

ring.insert(b"hello worldo");
assert_eq!(Some(b"hello worldo"), ring.try_first(42));

pub fn first<K: Hash>(&self, key: K) -> &T

Returns a reference to the first node responsible for the provided key.

Any key type may be used so long as it is Hash.

Panics if there are no nodes in the ring.

use consistent_hash_ring::*;

let mut ring = RingBuilder::default()
    .vnodes(12)
    .nodes_iter(0..1)
    .build();

assert_eq!(&0, ring.first("by"));

Important traits for Candidates<'a, T, S>

impl<'a, T: Hash + Eq + Clone, S: BuildHasher> Iterator for Candidates<'a, T, S> type Item = &'a T;

pub fn get<'a, K: Hash>(&'a self, key: K) -> Candidates<'a, T, S>

Returns an iterator over replication candidates for the provided key.

Prefer Ring::first instead if only the first node will be used.

use consistent_hash_ring::*;

let ring = RingBuilder::default()
    .replicas(3)
    .nodes_iter(0..12)
    .build();

let expect = vec![&1, &2, &6];

assert_eq!(expect, ring.get("key").collect::<Vec<_>>());
assert_eq!(expect[0], ring.first("key"));

Trait Implementations

impl<T: Clone + Hash + Eq, S: Clone> Clone for Ring<T, S>

fn clone(&self) -> Ring<T, S>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Hash + Eq + Clone> Default for Ring<T>

fn default() -> Self

Returns the "default value" for a type.