pub struct CHashMap<K, V> { /* private fields */ }Expand description
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§
Source§impl<K, V> CHashMap<K, V>
impl<K, V> CHashMap<K, V>
Sourcepub fn with_capacity(cap: usize) -> 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.
Sourcepub fn new() -> CHashMap<K, V>
pub fn new() -> CHashMap<K, V>
Create a new hash map.
This creates a new hash map with some fixed initial capacity.
Sourcepub fn len(&self) -> usize
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.
Sourcepub fn capacity(&self) -> usize
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.
Sourcepub fn buckets(&self) -> usize
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.
Sourcepub fn clear(&self) -> CHashMap<K, V>
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.
Sourcepub fn retain<F>(&self, predicate: F)
pub fn retain<F>(&self, predicate: F)
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.
Source§impl<K: PartialEq + Hash, V> CHashMap<K, V>
impl<K: PartialEq + Hash, V> CHashMap<K, V>
Sourcepub fn get<Q>(&self, key: &Q) -> Option<ReadGuard<'_, K, V>>
pub fn get<Q>(&self, key: &Q) -> Option<ReadGuard<'_, K, V>>
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.
Sourcepub fn get_mut<Q>(&self, key: &Q) -> Option<WriteGuard<'_, K, V>>
pub fn get_mut<Q>(&self, key: &Q) -> Option<WriteGuard<'_, K, V>>
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.
Sourcepub fn contains_key<Q>(&self, key: &Q) -> bool
pub fn contains_key<Q>(&self, key: &Q) -> bool
Does the hash map contain this key?
Sourcepub fn insert_new(&self, key: K, val: V)
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.
Sourcepub fn insert(&self, key: K, val: V) -> Option<V>
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.
Sourcepub fn upsert<F, G>(&self, key: K, insert: F, update: G)
pub fn upsert<F, G>(&self, key: K, insert: F, update: G)
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.
Sourcepub fn alter<F>(&self, key: K, f: F)
pub fn alter<F>(&self, key: K, f: F)
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.
Sourcepub fn remove<Q>(&self, key: &Q) -> Option<V>
pub fn remove<Q>(&self, key: &Q) -> Option<V>
Remove an entry.
This removes and returns the entry with key key. If no entry with said key exists, it
will simply return None.
Sourcepub fn reserve(&self, additional: usize)
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.
Sourcepub fn shrink_to_fit(&self)
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).