Struct chashmap::CHashMap

pub struct CHashMap<K, V> { /* fields omitted */ }

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.

Methods

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

pub fn with_capacity(cap: usize) -> CHashMap<K, V>

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() -> CHashMap<K, V>

Create a new hash map.

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

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 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 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 fn clear(&self) -> CHashMap<K, V>

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.

pub fn filter<F>(&self, predicate: F) where
    F: Fn(&K, &V) -> bool, 

Deprecated

Deprecated. Do not use.

pub 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: PartialEq + Hash, V> CHashMap<K, V>

pub fn get<Q: ?Sized>(&self, key: &Q) -> Option<ReadGuard<K, V>> where
    K: Borrow<Q>,
    Q: Hash + PartialEq, 

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 fn get_mut<Q: ?Sized>(&self, key: &Q) -> Option<WriteGuard<K, V>> where
    K: Borrow<Q>,
    Q: Hash + PartialEq, 

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 fn contains_key<Q: ?Sized>(&self, key: &Q) -> bool where
    K: Borrow<Q>,
    Q: Hash + PartialEq, 

Does the hash map contain this key?

pub 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 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 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 fn alter<F>(&self, key: K, f: F) where
    F: FnOnce(Option<V>) -> 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 fn remove<Q: ?Sized>(&self, key: &Q) -> Option<V> where
    K: Borrow<Q>,
    Q: PartialEq + Hash, 

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 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 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).

Trait Implementations

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

type Item = (K, V)

The type of the elements being iterated over.

type IntoIter = IntoIter<K, V>

Which kind of iterator are we turning this into?

Important traits for IntoIter<K, V>

impl<K, V> Iterator for IntoIter<K, V> type Item = (K, V);

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

Creates an iterator from a value.

impl<K, V> Default for CHashMap<K, V>

fn default() -> CHashMap<K, V>

Returns the "default value" for a type.

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

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

Returns a copy of the value.

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

Performs copy-assignment from source.

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

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

Creates a value from an iterator.

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

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

Formats the value using the given formatter.