Struct dashmap::DashMap

pub struct DashMap<K, V> where
    K: Hash + Eq,  { /* fields omitted */ }

DashMap is a threadsafe, versatile and concurrent hashmap with good performance and is balanced for both reads and writes.

The API mostly matches that of the standard library hashmap but there are some differences to due to the design.

One of those limits is iteration, you cannot iterate over the elements directly. Instead you have to iterate over chunks which can iterate over KV pairs. This is needed in order to use the calling thread stack as scratch space to avoid heap allocations.

The iter method currently provides a more ergonomic iterator that is slightly less performant. It should be extremely performant still but it is a tad slower than using the chunks interface.

Unsafe is used to avoid bounds checking when accessing chunks. This is guaranteed to be safe since we cannot possibly get a value higher than the amount of chunks. The amount of chunks cannot be altered after creation in any way.

This map is not lockfree but uses some clever locking internally. It has good average case performance

You should not rely on being able to hold any combination of references involving a mutable one as it may cause a deadlock. This will be fixed in the future.

Methods

impl<'a, K: 'a, V: 'a> DashMap<K, V> where
    K: Hash + Eq, 

pub fn new(num_chunks_log_2: u8) -> Self

Create a new DashMap. If you do not have specific requirements and understand the code you should probably call DashMap::default instead. It will determine the optimal parameters automagically. The amount of chunks used is based on the formula 2^n where n is the value passed. The default method will automagically determine the optimal amount.

Will panic if the first parameter plugged into the formula 2^n produces a result higher than isize::MAX.

pub fn with_capacity(num_chunks_log_2: u8, capacity: usize) -> Self

Create a new DashMap with a specified capacity.

Will panic if the first parameter plugged into the formula 2^n produces a result higher than isize::MAX.

pub fn insert(&self, key: K, value: V)

Insert an element into the map.

pub fn get_or_insert(&'a self, key: &K, default: V) -> DashMapRefAny<'a, K, V> where
    K: Clone, 

Get or insert an element into the map if one does not exist.

pub fn get_or_insert_with<F: FnOnce() -> V>(
    &'a self,
    key: &K,
    default: F
) -> DashMapRefAny<'a, K, V> where
    K: Clone, 

Get or insert an element into the map if one does not exist.

pub fn contains_key<Q: ?Sized>(&self, key: &Q) -> bool where
    K: Borrow<Q>,
    Q: Hash + Eq, 

Check if the map contains the specified key.

pub fn get_raw_from_key<Q: ?Sized>(
    &'a self,
    key: &Q
) -> RwLockReadGuard<'a, HashMap<K, V>> where
    K: Borrow<Q>,
    Q: Hash + Eq, 

pub fn get_raw_mut_from_key<Q: ?Sized>(
    &'a self,
    key: &Q
) -> RwLockWriteGuard<'a, HashMap<K, V>> where
    K: Borrow<Q>,
    Q: Hash + Eq, 

pub fn get<Q: ?Sized>(&'a self, key: &Q) -> Option<DashMapRef<'a, K, V>> where
    K: Borrow<Q>,
    Q: Hash + Eq, 

Get a shared reference to an element contained within the map.

pub fn async_get<Q>(
    &'a self,
    key: Q
) -> impl Future<Output = Option<DashMapRef<'a, K, V>>> where
    K: Borrow<Q>,
    Q: Hash + Eq + Sized, 

pub fn try_get<Q: ?Sized>(
    &'a self,
    key: &Q
) -> TryGetResult<DashMapRef<'a, K, V>> where
    K: Borrow<Q>,
    Q: Hash + Eq, 

Same as above but will return an error if the method would block at the current time.

pub fn try_get_with_timeout<Q: ?Sized>(
    &'a self,
    key: &Q,
    timeout: Duration
) -> TryGetResult<DashMapRef<'a, K, V>> where
    K: Borrow<Q>,
    Q: Hash + Eq, 

Same as above but will return an error if the method would block at the current time.

pub fn index<Q: ?Sized>(&'a self, key: &Q) -> DashMapRef<'a, K, V> where
    K: Borrow<Q>,
    Q: Hash + Eq, 

Shortcut for a get followed by an unwrap.

pub fn get_mut<Q: ?Sized>(&'a self, key: &Q) -> Option<DashMapRefMut<'a, K, V>> where
    K: Borrow<Q>,
    Q: Hash + Eq, 

Get a unique reference to an element contained within the map.

pub fn async_get_mut<Q>(
    &'a self,
    key: Q
) -> impl Future<Output = Option<DashMapRefMut<'a, K, V>>> where
    K: Borrow<Q>,
    Q: Hash + Eq + Sized, 

pub fn try_get_mut<Q: ?Sized>(
    &'a self,
    key: &Q
) -> TryGetResult<DashMapRefMut<'a, K, V>> where
    K: Borrow<Q>,
    Q: Hash + Eq, 

Same as above but will return an error if the method would block at the current time.

pub fn try_get_mut_with_timeout<Q: ?Sized>(
    &'a self,
    key: &Q,
    timeout: Duration
) -> TryGetResult<DashMapRefMut<'a, K, V>> where
    K: Borrow<Q>,
    Q: Hash + Eq, 

Same as above but will return an error if the method would block at the current time.

pub fn index_mut<Q: ?Sized>(&'a self, key: &Q) -> DashMapRefMut<'a, K, V> where
    K: Borrow<Q>,
    Q: Hash + Eq, 

Shortcut for a get_mut followed by an unwrap.

pub fn len(&self) -> usize

Get the amount of elements stored within the map.

pub fn is_empty(&self) -> bool

Check if the map is empty.

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

Remove an element from the map if it exists. Will return the K, V pair.

pub fn retain<F: Clone + FnMut(&K, &mut V) -> bool>(&self, f: F)

Retain all elements that the specified function returns true for.

pub fn clear(&self)

Clear all elements from the map.

pub fn alter<Q: ?Sized, F: FnOnce(V) -> V>(&self, k: &Q, f: F) where
    K: Borrow<Q>,
    Q: Hash + Eq, 

Apply a function to a a specified entry in the map.

pub fn alter_all<F: FnMut(V) -> V + Clone>(&self, f: F)

Apply a function to every item in the map.

Important traits for Iter<'a, K, V>

impl<'a, K, V> Iterator for Iter<'a, K, V> where
    K: Hash + Eq,  type Item = DashMapIterRef<'a, K, V>;

pub fn iter(&'a self) -> Iter<'a, K, V>

Iterate over the (K, V) pairs stored in the map immutably.

Important traits for IterMut<'a, K, V>

impl<'a, K, V> Iterator for IterMut<'a, K, V> where
    K: Hash + Eq,  type Item = DashMapIterRefMut<'a, K, V>;

pub fn iter_mut(&'a self) -> IterMut<'a, K, V>

Iterate over the (K, V) pairs stored in the map mutably.

pub fn chunks(&self) -> impl Iterator<Item = Chunk<K, V>>

Iterate over chunks in a read only fashion.

pub fn chunks_write(&self) -> impl Iterator<Item = ChunkMut<K, V>>

Iterate over chunks in a read-write fashion.

pub fn chunks_count(&self) -> usize

Trait Implementations

impl<K, V> Default for DashMap<K, V> where
    K: Hash + Eq, 

fn default() -> Self

Creates a new DashMap and automagically determines the optimal amount of chunks.

impl<K, V> Debug for DashMap<K, V> where
    K: Eq + Hash + Debug,
    V: Debug, 

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

Formats the value using the given formatter.