Struct CHashMap

pub struct CHashMap<K, V, S = RandomState> { /* private fields */ }

A concurrent hash map.

This type defines a concurrent associative array, based on hash tables with linear probing and dynamic resizing.

The idea is to let each entry hold a multi-reader lock, effectively limiting lock contentions to writing simultaneously on the same entry, and resizing the table.

It is not an atomic or lockless hash table, since such construction is only useful in very few cases, due to limitations on in-place operations on values.

Implementations

impl<K, V> CHashMap<K, V, RandomState>

pub fn with_capacity(cap: usize) -> Self

Create a new hash map with a certain capacity.

“Capacity” means the amount of entries the hash map can hold before reallocating. This function allocates a hash map with at least the capacity of cap.

pub fn new() -> Self

Create a new hash map.

This creates a new hash map with some fixed initial capacity.

impl<K, V, S> CHashMap<K, V, S>

pub fn len(&self) -> usize

Get the number of entries in the hash table.

This is entirely atomic, and will not acquire any locks.

This is guaranteed to reflect the number of entries _at this particular moment.

pub async fn capacity(&self) -> usize

Get the capacity of the hash table.

The capacity is equal to the number of entries the table can hold before reallocating.

pub async fn buckets(&self) -> usize

Get the number of buckets of the hash table.

“Buckets” refers to the amount of potential entries in the inner table. It is different from capacity, in the sense that the map cannot hold this number of entries, since it needs to keep the load factor low.

pub fn is_empty(&self) -> bool

Is the hash table empty?

pub async fn retain<F>(&self, predicate: F)

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

Filter the map based on some predicate.

This tests every entry in the hash map by closure predicate. If it returns true, the map will retain the entry. If not, the entry will be removed.

This won’t lock the table. This can be a major performance trade-off, as it means that it must lock on every table entry. However, it won’t block other operations of the table, while filtering.

impl<K, V, S: Default + BuildHasher> CHashMap<K, V, S>

pub fn with_hasher_and_capacity(cap: usize, hash_builder: S) -> Self

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

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

Warning: hash_builder is normally randomly generated, and is designed to allow HashMaps 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.

pub fn with_hasher(hash_builder: S) -> Self

Creates an empty CHashMap which will use the given 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 HashMaps 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.

impl<K, V, S> CHashMap<K, V, S>

where S: Default + BuildHasher,

pub async fn clear(&self) -> CHashMap<K, V, S>

Clear the map.

This clears the hash map and returns the previous version of the map.

It is relatively efficient, although it needs to write lock a RW lock.

impl<K: PartialEq + Hash, V, S: BuildHasher> CHashMap<K, V, S>

pub async fn get<Q>(&self, key: &Q) -> Option<ReadGuard<'_, K, V, S>>

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

Get the value of some key.

This will lookup the entry of some key key, and acquire the read-only lock. This means that all other parties are blocked from writing (not reading) this value while the guard is held.

pub async fn get_mut<Q>(&self, key: &Q) -> Option<WriteGuard<'_, K, V, S>>

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

Get the (mutable) value of some key.

This will lookup the entry of some key key, and acquire the writable lock. This means that all other parties are blocked from both reading and writing this value while the guard is held.

pub async fn contains_key<Q>(&self, key: &Q) -> bool

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

Does the hash map contain this key?

impl<K, V, S> CHashMap<K, V, S>

where K: PartialEq + Hash, S: BuildHasher + Default,

pub async fn insert_new(&self, key: K, val: V)

Insert a new entry.

This inserts an entry, which the map does not already contain, into the table. If the entry exists, the old entry won’t be replaced, nor will an error be returned. It will possibly introduce silent bugs.

To be more specific, it assumes that the entry does not already exist, and will simply skip to the end of the cluster, even if it does exist.

This is faster than e.g. insert, but should only be used, if you know that the entry doesn’t already exist.

Warning

Only use this, if you know what you’re doing. This can easily introduce very complex logic errors.

For most other purposes, use insert.

Panics

This might perform checks in debug mode testing if the key exists already.

pub async fn insert(&self, key: K, val: V) -> Option<V>

Replace an existing entry, or insert a new one.

This will replace an existing entry and return the old entry, if any. If no entry exists, it will simply insert the new entry and return None.

pub async fn upsert<F, G>(&self, key: K, insert: F, update: G)

where F: FnOnce() -> V, G: FnOnce(&mut V),

Insert or update.

This looks up key. If it exists, the reference to its value is passed through closure update. If it doesn’t exist, the result of closure insert is inserted.

pub async fn alter<F, Fut>(&self, key: K, f: F)

where F: FnOnce(Option<V>) -> Fut, Fut: Future<Output = Option<V>>,

Map or insert an entry.

This sets the value associated with key key to f(Some(old_val)) (if it returns None, the entry is removed) if it exists. If it does not exist, it inserts it with value f(None), unless the closure returns None.

Note that if f returns None, the entry of key key is removed unconditionally.

pub async fn remove<Q>(&self, key: &Q) -> Option<V>

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

Remove an entry.

This removes and returns the entry with key key. If no entry with said key exists, it will simply return None.

pub async fn reserve(&self, additional: usize)

Reserve additional space.

This reserves additional additional buckets to the table. Note that it might reserve more in order make reallocation less common.

pub async fn shrink_to_fit(&self)

Shrink the capacity of the map to reduce space usage.

This will shrink the capacity of the map to the needed amount (plus some additional space to avoid reallocations), effectively reducing memory usage in cases where there is excessive space.

It is healthy to run this once in a while, if the size of your hash map changes a lot (e.g. has a high maximum case).

impl<K: Clone, V: Clone, S: Clone> CHashMap<K, V, S>

pub fn clone_mut(&mut self) -> Self

Clone the struct, bypassing the locks by the statically guaranteed exclusive &mut access. Not that the map is not actually mutated.

pub async fn clone_locking(&self) -> Self

Clone by accessing keys and values via the locks. That requires this method to be async.

Trait Implementations

impl<K: Debug, V: Debug, S> Debug for CHashMap<K, V, S>

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

Formats the value using the given formatter.

impl<K, V, S: Default + BuildHasher> Default for CHashMap<K, V, S>

fn default() -> Self

Returns the “default value” for a type.

impl<K: PartialEq + Hash, V, S: Default + BuildHasher> FromIterator<(K, V)> for CHashMap<K, V, S>

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

Creates a value from an iterator.

impl<K, V, S> IntoIterator for CHashMap<K, V, S>

type Item = (K, V)

The type of the elements being iterated over.

type IntoIter = IntoIter<K, V, S>

Which kind of iterator are we turning this into?

fn into_iter(self) -> IntoIter<K, V, S>

Creates an iterator from a value.