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

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

DashMap tries to implement an easy to use API similar to std::collections::HashMap with some slight changes to handle concurrency.

DashMap tries to be very simple to use and to be a direct replacement for RwLock<HashMap<K, V, S>>. To accomplish this, all methods take &self instead of modifying methods taking &mut self. This allows you to put a DashMap in an Arc<T> and share it between threads while being able to modify it.

Documentation mentioning locking behaviour acts in the reference frame of the calling thread. This means that it is safe to ignore it across multiple threads.

Implementations

Creates a new DashMap with a capacity of 0.

Examples
use dashmap::DashMap;

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

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

Creates a new DashMap with a specified shard amount

shard_amount should greater than 0 and be a power of two. If a shard_amount which is not a power of two is provided, the function will panic.

Examples
use dashmap::DashMap;

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

Creates a new DashMap with a specified capacity and shard amount.

shard_amount should greater than 0 and be a power of two. If a shard_amount which is not a power of two is provided, the function will panic.

Examples
use dashmap::DashMap;

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

Wraps this DashMap into a read-only view. This view allows to obtain raw references to the stored values.

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!");

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

Creates a new DashMap with a specified hasher and shard amount

shard_amount should be greater than 0 and a power of two. If a shard_amount which is not a power of two is provided, the function will panic.

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

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

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

shard_amount should greater than 0 and be a power of two. If a shard_amount which is not a power of two is provided, the function will panic.

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

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

Hash a given item to produce a usize. Uses the provided or default HashBuilder.

Allows you to peek at the inner shards that store your data. You should probably not use this unless you know what you are doing.

Requires the raw-api feature to be enabled.

Examples
use dashmap::DashMap;

let map = DashMap::<(), ()>::new();
println!("Amount of shards: {}", map.shards().len());

Finds which shard a certain key is stored in. You should probably not use this unless you know what you are doing. Note that shard selection is dependent on the default or provided HashBuilder.

Requires the raw-api feature to be enabled.

Examples
use dashmap::DashMap;

let map = DashMap::new();
map.insert("coca-cola", 1.4);
println!("coca-cola is stored in shard: {}", map.determine_map("coca-cola"));

Finds which shard a certain hash is stored in.

Requires the raw-api feature to be enabled.

Examples
use dashmap::DashMap;

let map: DashMap<i32, i32> = DashMap::new();
let key = "key";
let hash = map.hash_usize(&key);
println!("hash is stored in shard: {}", map.determine_shard(hash));

Returns a reference to the map’s BuildHasher.

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

let hasher = RandomState::new();
let map: DashMap<i32, i32> = DashMap::new();
let hasher: &RandomState = map.hasher();

Inserts a key and a value into the map. Returns the old value associated with the key if there was one.

Locking behaviour: May deadlock if called when holding any sort of reference into the map.

Examples
use dashmap::DashMap;

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

Removes an entry from the map, returning the key and value if they existed in the map.

Locking behaviour: May deadlock if called when holding any sort of reference into the map.

Examples
use dashmap::DashMap;

let soccer_team = DashMap::new();
soccer_team.insert("Jack", "Goalie");
assert_eq!(soccer_team.remove("Jack").unwrap().1, "Goalie");

Removes an entry from the map, returning the key and value if the entry existed and the provided conditional function returned true.

Locking behaviour: May deadlock if called when holding any sort of reference into the map.

use dashmap::DashMap;

let soccer_team = DashMap::new();
soccer_team.insert("Sam", "Forward");
soccer_team.remove_if("Sam", |_, position| position == &"Goalie");
assert!(soccer_team.contains_key("Sam"));
use dashmap::DashMap;

let soccer_team = DashMap::new();
soccer_team.insert("Sam", "Forward");
soccer_team.remove_if("Sam", |_, position| position == &"Forward");
assert!(!soccer_team.contains_key("Sam"));

Creates an iterator over a DashMap yielding immutable references.

Locking behaviour: May deadlock if called when holding a mutable reference into the map.

Examples
use dashmap::DashMap;

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

Iterator over a DashMap yielding mutable references.

Locking behaviour: May deadlock if called when holding any sort of reference into the map.

Examples
use dashmap::DashMap;

let map = DashMap::new();
map.insert("Johnny", 21);
map.iter_mut().for_each(|mut r| *r += 1);
assert_eq!(*map.get("Johnny").unwrap(), 22);

Get a immutable reference to an entry in the map

Locking behaviour: May deadlock if called when holding a mutable reference into the map.

Examples
use dashmap::DashMap;

let youtubers = DashMap::new();
youtubers.insert("Bosnian Bill", 457000);
assert_eq!(*youtubers.get("Bosnian Bill").unwrap(), 457000);

Get a mutable reference to an entry in the map

Locking behaviour: May deadlock if called when holding any sort of reference into the map.

Examples
use dashmap::DashMap;

let class = DashMap::new();
class.insert("Albin", 15);
*class.get_mut("Albin").unwrap() -= 1;
assert_eq!(*class.get("Albin").unwrap(), 14);

Get an immutable reference to an entry in the map, if the shard is not locked. If the shard is locked, the function will return TryResult::Locked.

Examples
use dashmap::DashMap;
use dashmap::try_result::TryResult;

let map = DashMap::new();
map.insert("Johnny", 21);

assert_eq!(*map.try_get("Johnny").unwrap(), 21);

let _result1_locking = map.get_mut("Johnny");

let result2 = map.try_get("Johnny");
assert!(result2.is_locked());

Get a mutable reference to an entry in the map, if the shard is not locked. If the shard is locked, the function will return TryResult::Locked.

Examples
use dashmap::DashMap;
use dashmap::try_result::TryResult;

let map = DashMap::new();
map.insert("Johnny", 21);

*map.try_get_mut("Johnny").unwrap() += 1;
assert_eq!(*map.get("Johnny").unwrap(), 22);

let _result1_locking = map.get("Johnny");

let result2 = map.try_get_mut("Johnny");
assert!(result2.is_locked());

Remove excess capacity to reduce memory usage.

Locking behaviour: May deadlock if called when holding any sort of reference into the map.

Retain elements that whose predicates return true and discard elements whose predicates return false.

Locking behaviour: May deadlock if called when holding any sort of reference into the map.

Examples
use dashmap::DashMap;

let people = DashMap::new();
people.insert("Albin", 15);
people.insert("Jones", 22);
people.insert("Charlie", 27);
people.retain(|_, v| *v > 20);
assert_eq!(people.len(), 2);

Fetches the total number of key-value pairs stored in the map.

Locking behaviour: May deadlock if called when holding a mutable reference into the map.

Examples
use dashmap::DashMap;

let people = DashMap::new();
people.insert("Albin", 15);
people.insert("Jones", 22);
people.insert("Charlie", 27);
assert_eq!(people.len(), 3);

Checks if the map is empty or not.

Locking behaviour: May deadlock if called when holding a mutable reference into the map.

Examples
use dashmap::DashMap;

let map = DashMap::<(), ()>::new();
assert!(map.is_empty());

Removes all key-value pairs in the map.

Locking behaviour: May deadlock if called when holding any sort of reference into the map.

Examples
use dashmap::DashMap;

let stats = DashMap::new();
stats.insert("Goals", 4);
assert!(!stats.is_empty());
stats.clear();
assert!(stats.is_empty());

Returns how many key-value pairs the map can store without reallocating.

Locking behaviour: May deadlock if called when holding a mutable reference into the map.

Modify a specific value according to a function.

Locking behaviour: May deadlock if called when holding any sort of reference into the map.

Examples
use dashmap::DashMap;

let stats = DashMap::new();
stats.insert("Goals", 4);
stats.alter("Goals", |_, v| v * 2);
assert_eq!(*stats.get("Goals").unwrap(), 8);
Panics

If the given closure panics, then alter will abort the process

Modify every value in the map according to a function.

Locking behaviour: May deadlock if called when holding any sort of reference into the map.

Examples
use dashmap::DashMap;

let stats = DashMap::new();
stats.insert("Wins", 4);
stats.insert("Losses", 2);
stats.alter_all(|_, v| v + 1);
assert_eq!(*stats.get("Wins").unwrap(), 5);
assert_eq!(*stats.get("Losses").unwrap(), 3);
Panics

If the given closure panics, then alter_all will abort the process

Scoped access into an item of the map according to a function.

Locking behaviour: May deadlock if called when holding any sort of reference into the map.

Examples
use dashmap::DashMap;

let warehouse = DashMap::new();
warehouse.insert(4267, ("Banana", 100));
warehouse.insert(2359, ("Pear", 120));
let fruit = warehouse.view(&4267, |_k, v| *v);
assert_eq!(fruit, Some(("Banana", 100)));
Panics

If the given closure panics, then view will abort the process

Checks if the map contains a specific key.

Locking behaviour: May deadlock if called when holding a mutable reference into the map.

Examples
use dashmap::DashMap;

let team_sizes = DashMap::new();
team_sizes.insert("Dakota Cherries", 23);
assert!(team_sizes.contains_key("Dakota Cherries"));

Advanced entry API that tries to mimic std::collections::HashMap. See the documentation on dashmap::mapref::entry for more details.

Locking behaviour: May deadlock if called when holding any sort of reference into the map.

source

pub fn try_entry(&'a self, key: K) -> Option<Entry<'a, K, V, S>>

Advanced entry API that tries to mimic std::collections::HashMap. See the documentation on dashmap::mapref::entry for more details.

Returns None if the shard is currently locked.

Advanced entry API that tries to mimic std::collections::HashMap::try_reserve. Tries to reserve capacity for at least shard * additional and may reserve more space to avoid frequent reallocations.

Errors

If the capacity overflows, or the allocator reports a failure, then an error is returned.

Trait Implementations

The resulting type after applying the & operator.

Performs the & operation. Read more

The resulting type after applying the | operator.

Performs the | operation. Read more

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Deserialize this value from the given Serde deserializer. Read more

Extends a collection with the contents of an iterator. Read more

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements. Read more

Creates a value from an iterator. Read more

Creates an instance of the collection from the parallel iterator par_iter. Read more

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

Creates an iterator from a value. Read more

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

Creates an iterator from a value. Read more

The parallel iterator type that will be created.

The type of item that the parallel iterator will produce.

Converts self into a parallel iterator. Read more

The parallel iterator type that will be created.

The type of item that the parallel iterator will produce.

Converts self into a parallel iterator. Read more

The parallel iterator type that will be created.

The type of item that the parallel iterator will produce.

Converts self into a parallel iterator. Read more

Safety Read more

Safety Read more

Safety Read more

Safety Read more

Safety Read more

source

fn _entry(&'a self, key: K) -> Entry<'a, K, V, S>

source

fn _try_entry(&'a self, key: K) -> Option<Entry<'a, K, V, S>>

Extends an instance of the collection with the elements drawn from the parallel iterator par_iter. Read more

Extends an instance of the collection with the elements drawn from the parallel iterator par_iter. Read more

Serialize this value into the given Serde serializer. Read more

The resulting type after applying the << operator.

Performs the << operation. Read more

The resulting type after applying the >> operator.

Performs the >> operation. Read more

The resulting type after applying the - operator.

Performs the - operation. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The type of the parallel iterator that will be returned.

The type of item that the parallel iterator will produce. This will typically be an &'data T reference type. Read more

Converts self into a parallel iterator. Read more

The type of iterator that will be created.

The type of item that will be produced; this is typically an &'data mut T reference. Read more

Creates the parallel iterator from self. Read more

The alignment of pointer.

The type for initializers.

Initializes a with the given initializer. Read more

Dereferences the given pointer. Read more

Mutably dereferences the given pointer. Read more

Drops the object pointed to by the given pointer. Read more

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.