Struct hash_rings::rendezvous::Ring

pub struct Ring<'a, T, H = RandomState> { /* fields omitted */ }

A hashing ring implemented using rendezvous hashing.

Rendezvous hashing is based on based on assigning a pseudorandom value to node-point pair. A point is mapped to the node that yields the greatest value associated with the node-point pair. By mapping the weights to [0, 1) using logarithms, rendezvous hashing can be modified to handle weighted nodes.

Examples

use hash_rings::rendezvous::Ring;
use std::collections::hash_map::DefaultHasher;
use std::hash::BuildHasherDefault;

type DefaultBuildHasher = BuildHasherDefault<DefaultHasher>;

let mut ring = Ring::with_hasher(DefaultBuildHasher::default());

ring.insert_node(&"node-1", 1);
ring.insert_node(&"node-2", 3);

ring.remove_node(&"node-1");

assert_eq!(ring.get_node(&"point-1"), &"node-2");
assert_eq!(ring.len(), 1);

let mut iterator = ring.iter();
assert_eq!(iterator.next(), Some((&"node-2", 3)));
assert_eq!(iterator.next(), None);

Methods

impl<'a, T> Ring<'a, T, RandomState>

pub fn new() -> Self where
    T: Hash + Eq, 

Constructs a new, empty Ring<T>.

Examples

use hash_rings::rendezvous::Ring;

let mut ring: Ring<&str> = Ring::new();

impl<'a, T, H> Ring<'a, T, H>

pub fn with_hasher(hash_builder: H) -> Self where
    T: Hash + Eq,
    H: BuildHasher, 

Constructs a new, empty Ring<T> with a specified hash builder.

Examples

use hash_rings::rendezvous::Ring;
use std::collections::hash_map::DefaultHasher;
use std::hash::BuildHasherDefault;

type DefaultBuildHasher = BuildHasherDefault<DefaultHasher>;

let mut ring: Ring<&str, _> = Ring::with_hasher(DefaultBuildHasher::default());

pub fn insert_node(&mut self, id: &'a T, replicas: usize) where
    T: Hash + Eq,
    H: BuildHasher, 

Inserts a node into the ring with a number of replicas.

Increasing the number of replicas will increase the number of expected points mapped to the node. For example, a node with three replicas will receive approximately three times more points than a node with one replica.

Examples

use hash_rings::rendezvous::Ring;

let mut ring: Ring<&str> = Ring::new();

// "node-2" will receive three times more points than "node-1"
ring.insert_node(&"node-1", 1);
ring.insert_node(&"node-2", 3);

pub fn remove_node(&mut self, id: &T) where
    T: Hash + Eq, 

Removes a node and all its replicas from the ring.

Examples

use hash_rings::rendezvous::Ring;

let mut ring: Ring<&str> = Ring::new();

ring.insert_node(&"node-1", 1);
ring.insert_node(&"node-2", 1);
ring.remove_node(&"node-2");

pub fn get_node<U>(&self, id: &U) -> &'a T where
    T: Hash + Ord,
    U: Hash,
    H: BuildHasher, 

Returns the node associated with a point.

Panics

Panics if the ring is empty.

Examples

use hash_rings::rendezvous::Ring;

let mut ring: Ring<&str> = Ring::new();

ring.insert_node(&"node-1", 1);
assert_eq!(ring.get_node(&"point-1"), &"node-1");

pub fn len(&self) -> usize where
    T: Hash + Eq, 

Returns the number of nodes in the ring.

Examples

use hash_rings::rendezvous::Ring;

let mut ring: Ring<&str> = Ring::new();

ring.insert_node(&"node-1", 3);
assert_eq!(ring.len(), 1);

pub fn is_empty(&self) -> bool where
    T: Hash + Eq, 

Returns true if the ring is empty.

Examples

use hash_rings::rendezvous::Ring;

let mut ring: Ring<&str> = Ring::new();

assert!(ring.is_empty());
ring.insert_node(&"node-1", 3);
assert!(!ring.is_empty());

pub fn iter(&'a self) -> impl Iterator<Item = (&'a T, usize)> where
    T: Hash + Eq, 

Returns an iterator over the ring. The iterator will yield nodes and the replica count in no particular order.

Examples

use hash_rings::rendezvous::Ring;

let mut ring = Ring::new();
ring.insert_node(&"node-1", 1);

let mut iterator = ring.iter();
assert_eq!(iterator.next(), Some((&"node-1", 1)));
assert_eq!(iterator.next(), None);

Trait Implementations

impl<'a, T, H> IntoIterator for &'a Ring<'a, T, H> where
    T: Hash + Eq, 

type IntoIter = Box<dyn Iterator<Item = (&'a T, usize)> + 'a>

Which kind of iterator are we turning this into?

type Item = (&'a T, usize)

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, T, H> Default for Ring<'a, T, H> where
    T: Hash + Eq,
    H: BuildHasher + Default, 

fn default() -> Self

Returns the "default value" for a type.