Struct HashMap

pub struct HashMap<K, V, S = DefaultHashBuilder> { /* private fields */ }

A concurrent hash table.

Flurry uses Guards to control the lifetime of the resources that get stored and extracted from the map. Guards are acquired through the HashMap::pin and HashMap::guard functions. For more information, see the notes in the crate-level documentation.

Implementations

impl<K, V> HashMap<K, V, DefaultHashBuilder>

pub fn new() -> Self

Creates an empty HashMap.

The hash map is initially created with a capacity of 0, so it will not allocate until it is first inserted into.

Examples

use flurry::HashMap;
let map: HashMap<&str, i32> = HashMap::new();

pub fn with_capacity(capacity: usize) -> Self

Creates an empty HashMap with the specified capacity.

The hash map will be able to hold at least capacity elements without reallocating. If capacity is 0, the hash map will not allocate.

Examples

use flurry::HashMap;
let map: HashMap<&str, i32> = HashMap::with_capacity(10);

Notes

There is no guarantee that the HashMap will not resize if capacity elements are inserted. The map will resize based on key collision, so bad key distribution may cause a resize before capacity is reached. For more information see the resizing behavior

impl<K, V, S> HashMap<K, V, S>

pub fn with_hasher(hash_builder: S) -> Self

Creates an empty map which will use hash_builder to hash keys.

The created map has the default initial capacity.

Warning: hash_builder is normally randomly generated, and is designed to allow the map to be resistant to attacks that cause many collisions and very poor performance. Setting it manually using this function can expose a DoS attack vector.

Examples

use flurry::{HashMap, DefaultHashBuilder};

let map = HashMap::with_hasher(DefaultHashBuilder::default());
map.pin().insert(1, 2);

pub fn with_capacity_and_hasher(capacity: usize, hash_builder: S) -> Self

Creates an empty map with the specified capacity, using hash_builder to hash the keys.

The map will be sized to accommodate capacity elements with a low chance of reallocating (assuming uniformly distributed hashes). If capacity is 0, the call will not allocate, and is equivalent to HashMap::new.

Warning: hash_builder is normally randomly generated, and is designed to allow the map to be resistant to attacks that cause many collisions and very poor performance. Setting it manually using this function can expose a DoS attack vector.

Examples

use flurry::HashMap;
use std::collections::hash_map::RandomState;

let s = RandomState::new();
let map = HashMap::with_capacity_and_hasher(10, s);
map.pin().insert(1, 2);

pub fn with_collector(self, collector: Collector) -> Self

Associate a custom seize::Collector with this map.

By default, the global collector is used. With this method you can use a different collector instead. This may be desireable if you want more control over when and how memory reclamation happens.

Note that all Guard references provided to access the returned map must be constructed using guards produced by collector.

pub fn guard(&self) -> Guard<'_>

Pin a Guard for use with this map.

Keep in mind that for as long as you hold onto this Guard, you are preventing the collection of garbage generated by the map.

pub fn len(&self) -> usize

Returns the number of entries in the map.

Examples

use flurry::HashMap;

let map = HashMap::new();

map.pin().insert(1, "a");
map.pin().insert(2, "b");
assert!(map.pin().len() == 2);

pub fn is_empty(&self) -> bool

Returns true if the map is empty. Otherwise returns false.

Examples

use flurry::HashMap;

let map = HashMap::new();
assert!(map.pin().is_empty());
map.pin().insert("a", 1);
assert!(!map.pin().is_empty());

pub fn iter<'g>(&'g self, guard: &'g Guard<'_>) -> Iter<'g, K, V>

An iterator visiting all key-value pairs in arbitrary order.

The iterator element type is (&'g K, &'g V).

pub fn keys<'g>(&'g self, guard: &'g Guard<'_>) -> Keys<'g, K, V>

An iterator visiting all keys in arbitrary order.

The iterator element type is &'g K.

pub fn values<'g>(&'g self, guard: &'g Guard<'_>) -> Values<'g, K, V>

An iterator visiting all values in arbitrary order.

The iterator element type is &'g V.

impl<K, V, S> HashMap<K, V, S>

where K: Clone + Ord,

pub fn reserve(&self, additional: usize, guard: &Guard<'_>)

Tries to reserve capacity for at least additional more elements to be inserted in the HashMap.

The collection may reserve more space to avoid frequent reallocations.

Examples

use flurry::HashMap;

let map: HashMap<&str, i32> = HashMap::new();

map.pin().reserve(10);

Notes

Reserving does not panic in flurry. If the new size is invalid, no reallocation takes place.

impl<K, V, S> HashMap<K, V, S>

where K: Hash + Ord, S: BuildHasher,

pub fn contains_key<Q>(&self, key: &Q, guard: &Guard<'_>) -> bool

where K: Borrow<Q>, Q: ?Sized + Hash + Ord,

Returns true if the map contains a value for the specified key.

The key may be any borrowed form of the map’s key type, but Hash and Ord on the borrowed form must match those for the key type.

Examples

use flurry::HashMap;

let map = HashMap::new();
let mref = map.pin();
mref.insert(1, "a");
assert_eq!(mref.contains_key(&1), true);
assert_eq!(mref.contains_key(&2), false);

pub fn get<'g, Q>(&'g self, key: &Q, guard: &'g Guard<'_>) -> Option<&'g V>

where K: Borrow<Q>, Q: ?Sized + Hash + Ord,

Returns a reference to the value corresponding to the key.

The key may be any borrowed form of the map’s key type, but Hash and Ord on the borrowed form must match those for the key type.

To obtain a Guard, use HashMap::guard.

Examples

use flurry::HashMap;

let map = HashMap::new();
let mref = map.pin();
mref.insert(1, "a");
assert_eq!(mref.get(&1), Some(&"a"));
assert_eq!(mref.get(&2), None);

pub fn get_key_value<'g, Q>( &'g self, key: &Q, guard: &'g Guard<'_>, ) -> Option<(&'g K, &'g V)>

where K: Borrow<Q>, Q: ?Sized + Hash + Ord,

Returns the key-value pair corresponding to key.

Returns None if this map contains no mapping for key.

The key may be any borrowed form of the map’s key type, but Hash and Ord on the borrowed form must match those for the key type.

impl<K, V, S> HashMap<K, V, S>

where K: Clone + Ord,

pub fn clear(&self, guard: &Guard<'_>)

Clears the map, removing all key-value pairs.

Examples

use flurry::HashMap;

let map = HashMap::new();

map.pin().insert(1, "a");
map.pin().clear();
assert!(map.pin().is_empty());

impl<K, V, S> HashMap<K, V, S>

where K: Sync + Send + Clone + Hash + Ord, V: Sync + Send, S: BuildHasher,

pub fn insert<'g>( &'g self, key: K, value: V, guard: &'g Guard<'_>, ) -> Option<&'g V>

Inserts a key-value pair into the map.

If the map did not have this key present, None is returned.

If the map did have this key present, the value is updated, and the old value is returned. The key is left unchanged. See the std-collections documentation for more.

Examples

use flurry::HashMap;

let map = HashMap::new();
assert_eq!(map.pin().insert(37, "a"), None);
assert_eq!(map.pin().is_empty(), false);

// you can also re-use a map pin like so:
let mref = map.pin();

mref.insert(37, "b");
assert_eq!(mref.insert(37, "c"), Some(&"b"));
assert_eq!(mref.get(&37), Some(&"c"));

pub fn try_insert<'g>( &'g self, key: K, value: V, guard: &'g Guard<'_>, ) -> Result<&'g V, TryInsertError<'g, V>>

Inserts a key-value pair into the map unless the key already exists.

If the map does not contain the key, the key-value pair is inserted and this method returns Ok.

If the map does contain the key, the map is left unchanged and this method returns Err.

Examples

use flurry::{HashMap, TryInsertError};

let map = HashMap::new();
let mref = map.pin();

mref.insert(37, "a");
assert_eq!(
    mref.try_insert(37, "b"),
    Err(TryInsertError { current: &"a", not_inserted: &"b"})
);
assert_eq!(mref.try_insert(42, "c"), Ok(&"c"));
assert_eq!(mref.get(&37), Some(&"a"));
assert_eq!(mref.get(&42), Some(&"c"));

pub fn compute_if_present<'g, Q, F>( &'g self, key: &Q, remapping_function: F, guard: &'g Guard<'_>, ) -> Option<&'g V>

where K: Borrow<Q>, Q: ?Sized + Hash + Ord, F: FnOnce(&K, &V) -> Option<V>,

If the value for the specified key is present, attempts to compute a new mapping given the key and its current mapped value.

The new mapping is computed by the remapping_function, which may return None to signalize that the mapping should be removed. The entire method invocation is performed atomically. The supplied function is invoked exactly once per invocation of this method if the key is present, else not at all. Some attempted update operations on this map by other threads may be blocked while computation is in progress, so the computation should be short and simple.

Returns the new value associated with the specified key, or None if no value for the specified key is present.

The key may be any borrowed form of the map’s key type, but Hash and Ord on the borrowed form must match those for the key type.

pub fn remove<'g, Q>(&'g self, key: &Q, guard: &'g Guard<'_>) -> Option<&'g V>

where K: Borrow<Q>, Q: ?Sized + Hash + Ord,

Removes a key-value pair from the map, and returns the removed value (if any).

The key may be any borrowed form of the map’s key type, but Hash and Ord on the borrowed form must match those for the key type.

Examples

use flurry::HashMap;

let map = HashMap::new();
map.pin().insert(1, "a");
assert_eq!(map.pin().remove(&1), Some(&"a"));
assert_eq!(map.pin().remove(&1), None);

pub fn remove_entry<'g, Q>( &'g self, key: &Q, guard: &'g Guard<'_>, ) -> Option<(&'g K, &'g V)>

where K: Borrow<Q>, Q: ?Sized + Hash + Ord,

Removes a key from the map, returning the stored key and value if the key was previously in the map.

The key may be any borrowed form of the map’s key type, but Hash and Ord on the borrowed form must match those for the key type.

Examples

use flurry::HashMap;

let map = HashMap::new();
let guard = map.guard();
map.insert(1, "a", &guard);
assert_eq!(map.remove_entry(&1, &guard), Some((&1, &"a")));
assert_eq!(map.remove(&1, &guard), None);

pub fn retain<F>(&self, f: F, guard: &Guard<'_>)

where F: FnMut(&K, &V) -> bool,

Retains only the elements specified by the predicate.

In other words, remove all pairs (k, v) such that f(&k,&v) returns false.

Examples

use flurry::HashMap;

let map = HashMap::new();

for i in 0..8 {
    map.pin().insert(i, i*10);
}
map.pin().retain(|&k, _| k % 2 == 0);
assert_eq!(map.pin().len(), 4);

Notes

If f returns false for a given key/value pair, but the value for that pair is concurrently modified before the removal takes place, the entry will not be removed. If you want the removal to happen even in the case of concurrent modification, use HashMap::retain_force.

pub fn retain_force<F>(&self, f: F, guard: &Guard<'_>)

where F: FnMut(&K, &V) -> bool,

Retains only the elements specified by the predicate.

In other words, remove all pairs (k, v) such that f(&k,&v) returns false.

This method always deletes any key/value pair that f returns false for, even if the value is updated concurrently. If you do not want that behavior, use HashMap::retain.

Examples

use flurry::HashMap;

let map = HashMap::new();

for i in 0..8 {
    map.pin().insert(i, i*10);
}
map.pin().retain_force(|&k, _| k % 2 == 0);
assert_eq!(map.pin().len(), 4);

impl<K, V, S> HashMap<K, V, S>

pub fn pin(&self) -> HashMapRef<'_, K, V, S>

Get a reference to this map with the current thread pinned.

Keep in mind that for as long as you hold onto this, you are preventing the collection of garbage generated by the map.

pub fn with_guard<'g>(&'g self, guard: &'g Guard<'_>) -> HashMapRef<'g, K, V, S>

Get a reference to this map with the given guard.

Trait Implementations

impl<K, V, S> Clone for HashMap<K, V, S>

where K: Sync + Send + Clone + Hash + Ord, V: Sync + Send + Clone, S: BuildHasher + Clone,

fn clone(&self) -> HashMap<K, V, S>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<K, V, S> Debug for HashMap<K, V, S>

where K: Debug, V: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<K, V, S> Default for HashMap<K, V, S>

where S: Default,

fn default() -> Self

Returns the “default value” for a type.

impl<K, V, S> Drop for HashMap<K, V, S>

fn drop(&mut self)

Executes the destructor for this type.

impl<'a, K, V, S> Extend<(&'a K, &'a V)> for &HashMap<K, V, S>

where K: Sync + Send + Copy + Hash + Ord, V: Sync + Send + Copy, S: BuildHasher,

fn extend<T: IntoIterator<Item = (&'a K, &'a V)>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<K, V, S> Extend<(K, V)> for &HashMap<K, V, S>

where K: Sync + Send + Clone + Hash + Ord, V: Sync + Send, S: BuildHasher,

fn extend<T: IntoIterator<Item = (K, V)>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<'a, K, V, S> FromIterator<&'a (K, V)> for HashMap<K, V, S>

where K: Sync + Send + Copy + Hash + Ord, V: Sync + Send + Copy, S: BuildHasher + Default,

fn from_iter<T: IntoIterator<Item = &'a (K, V)>>(iter: T) -> Self

Creates a value from an iterator.

impl<'a, K, V, S> FromIterator<(&'a K, &'a V)> for HashMap<K, V, S>

where K: Sync + Send + Copy + Hash + Ord, V: Sync + Send + Copy, S: BuildHasher + Default,

fn from_iter<T: IntoIterator<Item = (&'a K, &'a V)>>(iter: T) -> Self

Creates a value from an iterator.

impl<K, V, S> FromIterator<(K, V)> for HashMap<K, V, S>

where K: Sync + Send + Clone + Hash + Ord, V: Sync + Send, S: BuildHasher + Default,

fn from_iter<T: IntoIterator<Item = (K, V)>>(iter: T) -> Self

Creates a value from an iterator.

impl<K, V, S> PartialEq<HashMap<K, V, S>> for HashMapRef<'_, K, V, S>

where K: Hash + Ord, V: PartialEq, S: BuildHasher,

fn eq(&self, other: &HashMap<K, V, S>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<K, V, S> PartialEq<HashMapRef<'_, K, V, S>> for HashMap<K, V, S>

where K: Hash + Ord, V: PartialEq, S: BuildHasher,

fn eq(&self, other: &HashMapRef<'_, K, V, S>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<K, V, S> PartialEq for HashMap<K, V, S>

where K: Ord + Hash, V: PartialEq, S: BuildHasher,

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<K, V, S> Eq for HashMap<K, V, S>

where K: Ord + Hash, V: Eq, S: BuildHasher,