Struct dashmap::DashMap

pub struct DashMap<K, V, S = RandomState> { /* fields omitted */ }

DashMap is an implementation of a concurrent associative array/hashmap in Rust.

This library attempts to be a replacement for most uses of RwLock<HashMap<K, V>> but does not cover all scenarios such as multi key serializable operations that are possible with RwLock<HashMap<K, V>>. Instead we prefer speed and leave more complex constructs to libraries that can build on top of this.

In essence, this is meant to be a high performance core that can be built upon.

In contrast to v3 and prior versions. You cannot deadlock this. You are free to run any combination of operations and keep any combination of guards and be guaranteed not to deadlock.

Implementations

impl<K: Eq + Hash + 'static, V: 'static> DashMap<K, V, RandomState>

pub fn new() -> Self

Creates a new DashMap.

Examples

use dashmap::DashMap;

let reviews = DashMap::new();
reviews.insert("Veloren", "What a fantastic game!");

pub fn with_capacity(capacity: usize) -> Self

Creates a new DashMap with a specified starting capacity.

Examples

use dashmap::DashMap;

let mappings = DashMap::with_capacity(2);
mappings.insert(2, 4);
mappings.insert(8, 16);

impl<K: Eq + Hash + 'static, V: 'static, S: BuildHasher + 'static> DashMap<K, V, S>

pub fn with_hasher(build_hasher: S) -> Self

Creates a new DashMap with a capacity of 0 and the provided hasher.

Examples

use dashmap::DashMap;
use std::collections::hash_map::RandomState;

let s = RandomState::new();
let reviews = DashMap::with_hasher(s);
reviews.insert("Veloren", "What a fantastic game!");

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

Creates a new DashMap with a specified starting capacity and hasher.

Examples

use dashmap::DashMap;
use std::collections::hash_map::RandomState;

let s = RandomState::new();
let mappings = DashMap::with_capacity_and_hasher(2, s);
mappings.insert(2, 4);
mappings.insert(8, 16);

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

Inserts a key and a value into the map.

Examples

use dashmap::DashMap;

let map = DashMap::new();
map.insert("I am the key!", "And I am the value!");

pub fn insert_and_get(&self, key: K, value: V) -> ElementGuard<K, V>

Inserts a key and a value into the map and returns a guard to the new entry.

Examples

use dashmap::DashMap;

let map = DashMap::new();
let new_entry = map.insert_and_get("I am the key!", "And I am the value!");
assert!(*new_entry.value() == "And I am the value!")

pub fn replace(&self, key: K, value: V) -> Option<ElementGuard<K, V>>

Inserts a key and a value into the map and returns a guard to the replaced entry if there was one.

Examples

use dashmap::DashMap;

let map = DashMap::new();
map.insert("I am the key!", "I'm the old value!");
let maybe_old_entry = map.replace("I am the key!", "And I am the value!");
assert!(maybe_old_entry.is_some());
let old_entry = maybe_old_entry.unwrap();
assert!(*old_entry.value() == "I'm the old value!");

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

Get the entry of a key if it exists in the map.

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

Check if the map contains a specific key.

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

Removes an entry from the map. Returns true if the key existed and the entry was removed. Otherwise returns false.

pub fn remove_if<Q: ?Sized, P>(&self, key: &Q, predicate: P) -> bool where
    K: Borrow<Q>,
    Q: Eq + Hash,
    P: FnMut(&K, &V) -> bool, 

Removes an entry from the map if the conditional returns true. Returns true if the key existed and the entry was removed. Otherwise returns false.

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

Removes an entry from the map. Returns the entry if it existed in the map. Otherwise returns None.

pub fn remove_if_take<Q: ?Sized, P>(
    &self,
    key: &Q,
    predicate: P
) -> Option<ElementGuard<K, V>> where
    K: Borrow<Q>,
    Q: Eq + Hash,
    P: FnMut(&K, &V) -> bool, 

Removes an entry from the map if the conditional returns true. Returns the entry if it existed in the map. Otherwise returns None.

pub fn extract<T, Q: ?Sized, F>(
    &self,
    search_key: &Q,
    do_extract: F
) -> Option<T> where
    K: Borrow<Q>,
    Q: Eq + Hash,
    F: FnOnce(&K, &V) -> T, 

Run a closure on an entry in the map. If the key existed the function's output is returned. Otherwise returns None.

pub fn update<Q: ?Sized, F>(&self, search_key: &Q, do_update: F) -> bool where
    K: Borrow<Q> + Clone,
    Q: Eq + Hash,
    F: FnMut(&K, &V) -> V, 

Update the value of a key in the map by supplying a mutation closure. Returns true if the key existed. Otherwise returns false.

pub fn update_get<Q: ?Sized, F>(
    &self,
    search_key: &Q,
    do_update: F
) -> Option<ElementGuard<K, V>> where
    K: Borrow<Q> + Clone,
    Q: Eq + Hash,
    F: FnMut(&K, &V) -> V, 

Update the value of a key in the map by supplying a mutation closure. Returns the updated entry of the key if the key existed. Otherwise returns false.

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

Create an iterator over all entries in the map. This does not take a snapshot of the map and thus changes during the lifetime of the iterator may or may not become visible in the iterator.

Examples

use dashmap::DashMap;

let words = DashMap::new();
words.insert("hello", "world");
words.insert("macn", "cheese");
assert_eq!(words.iter().count(), 2);

pub fn retain(&self, predicate: impl FnMut(&K, &V) -> bool)

Retain elements that the filter closure returns true for.

pub fn clear(&self)

Clear all entries in the map.

pub fn len(&self) -> usize

Get the amount of entries in the map.

pub fn is_empty(&self) -> bool

Checks if the map is empty.

pub fn capacity(&self) -> usize

Returns the capacity of the map. That is the maximum amount of entries before a reallocation is needed. The backend implementation cannot always know the capacity. If this function returns 0, the capacity is unknown.

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

Create a map from an iterator over key + value pairs.

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

Extend the map with an iterator over key + value pairs.

Trait Implementations

impl<K: Eq + Hash + 'static + Debug, V: 'static + Debug, S: BuildHasher + 'static> Debug for DashMap<K, V, S>

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

Formats the value using the given formatter.

impl<K: Eq + Hash + 'static, V: 'static> Default for DashMap<K, V, RandomState>

fn default() -> Self

Returns the "default value" for a type.

impl<'de, K: 'static, V: 'static> Deserialize<'de> for DashMap<K, V> where
    K: Deserialize<'de> + Eq + Hash,
    V: Deserialize<'de>, 

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error> where
    D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl<K: Eq + Hash + 'static, V: 'static> FromIterator<(K, V)> for DashMap<K, V, RandomState>

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

Creates a value from an iterator.

impl<'_, K: Eq + Hash + 'static, V: 'static, S: BuildHasher + 'static> IntoIterator for &'_ DashMap<K, V, S>

type Item = ElementGuard<K, V>

The type of the elements being iterated over.

type IntoIter = Iter<K, V>

Which kind of iterator are we turning this into?

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

Creates an iterator from a value.

impl<K: 'static, V: 'static> Serialize for DashMap<K, V> where
    K: Serialize + Eq + Hash,
    V: Serialize, 

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> where
    S: Serializer, 

Serialize this value into the given Serde serializer.