Struct Ring 

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

A hashing ring implemented using consistent hashing.

Consistent hashing is based on mapping each node to a pseudorandom value. In this implementation the pseudorandom is a combination of the hash of the node and the hash of the replica number. A point is also represented as a pseudorandom value and it is mapped to the node with the smallest value that is greater than or equal to the point’s value. If such a node does not exist, then the point maps to the node with the smallest value.

Examples

use hash_rings::consistent::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);

Implementations

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::consistent::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 + Default,

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

Examples

use hash_rings::consistent::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::consistent::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, H: BuildHasher,

Removes a node and all its replicas from the ring.

Examples

use hash_rings::consistent::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, point: &U) -> &T

where U: Hash, H: BuildHasher,

Returns the node associated with a point.

Panics

Panics if the ring is empty.

Examples

use hash_rings::consistent::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::consistent::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::consistent::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::consistent::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> Default for Ring<'a, T, H>

where T: Hash + Eq, H: BuildHasher + Default,

fn default() -> Self

Returns the “default value” for a type.

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.