Struct contrie::map::ConMap

pub struct ConMap<K, V: ?Sized, S = RandomState> where
    K: Hash + Eq + 'static,
    V: 'static,  { /* fields omitted */ }

A concurrent map.

This flavour stores the data as Arc<Element<K, V>>. This allows returning handles to the held values cheaply even if the data is larger or impossible to clone. This has several consequences:

• It is sometimes less convenient to use.
• It allows the values to be ?Sized ‒ you can store trait objects or slices as the values (not the keys).
• Entries can be shared between multiple maps.
• Cloning of the map doesn't clone the data, it will point to the same objects.
• There's another indirection in play.

Iteration returns (cloned) handles to the elements. The FromIterator and Extend traits accept both tuples and element handles. Furthermore, the Extend is also implemented for shared references (to allow extending the same map concurrently from multiple threads).

TODO: Support for rayon iterators/extend.

If this is not suitable, the CloneConMap can be used instead (TODO: Implement it).

Examples

use contrie::ConMap;
use crossbeam_utils::thread;

let map = ConMap::new();

thread::scope(|s| {
    s.spawn(|_| {
        map.insert("hello", 1);
    });
    s.spawn(|_| {
        map.insert("world", 2);
    });
}).unwrap();
assert_eq!(1, *map.get("hello").unwrap().value());
assert_eq!(2, *map.get("world").unwrap().value());

use std::sync::Arc;
use contrie::map::{ConMap, Element};
let map_1: ConMap<usize, [usize]> = ConMap::new();

map_1.insert_element(Arc::new(Element::new(42, [1, 2, 3])));
map_1.insert_element(Arc::new(Element::new(43, [1, 2, 3, 4])));

assert_eq!(3, map_1.get(&42).unwrap().value().len());

let map_2 = ConMap::new();
map_2.insert_element(map_1.get(&43).unwrap());

Methods

impl<K, V: ?Sized> ConMap<K, V> where
    K: Hash + Eq + 'static,
    V: 'static, 

pub fn new() -> Self

Creates a new empty map.

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

pub fn insert(&self, key: K, value: V) -> Option<Arc<Element<K, V>>>

Inserts a new element.

Any previous element with the same key is replaced and returned.

pub fn get_or_insert(
    &self,
    key: K,
    value: V
) -> ExistingOrNew<Arc<Element<K, V>>>

Looks up or inserts an element.

It looks up an element. If it isn't present, the provided one is inserted instead. Either way, an element is returned.

pub fn get_or_insert_with<F>(
    &self,
    key: K,
    create: F
) -> ExistingOrNew<Arc<Element<K, V>>> where
    F: FnOnce() -> V, 

Looks up or inserts a newly created element.

It looks up an element. If it isn't present, the provided closure is used to create a new one insert it. Either way, an element is returned.

Quirks

Due to races in case of concurrent accesses, the closure may be called even if the value is not subsequently inserted and an existing element is returned. This should be relatively rare (another thread must insert the new element between this method observes an empty slot and manages to insert the new element).

pub fn get_or_insert_default(&self, key: K) -> ExistingOrNew<Arc<Element<K, V>>> where
    V: Default, 

Looks up or inserts a default value of an element.

This is like get_or_insert_with, but a default value is used instead of manually providing a closure.

impl<K, V, S> ConMap<K, V, S> where
    K: Hash + Eq,
    V: ?Sized,
    S: BuildHasher, 

pub fn with_hasher(hasher: S) -> Self

Creates a new empty map, but with the provided hasher implementation.

pub fn insert_element(
    &self,
    element: Arc<Element<K, V>>
) -> Option<Arc<Element<K, V>>>

Inserts a new element.

This acts the same as insert, but takes the already created element. It can be used when:

• V: ?Sized.
• You want to insert the same element into multiple maps.

pub fn get_or_insert_with_element<F>(
    &self,
    key: K,
    create: F
) -> ExistingOrNew<Arc<Element<K, V>>> where
    F: FnOnce(K) -> Arc<Element<K, V>>, 

Looks up or inserts a new element.

This is the same as get_or_insert_with, but the closure returns a pre-created element. This can be used when:

• V: ?Sized.
• You want to insert the same element into multiple maps.

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

Looks up an element.

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

Removes an element identified by the given key, returning it.

impl<K, V, S> ConMap<K, V, S> where
    K: Hash + Eq,
    V: ?Sized, 

pub fn is_empty(&self) -> bool

Checks if the map is currently empty.

Note that due to the nature of concurrent map, this is inherently racy ‒ another thread may add or remove elements between you call this method and act based on the result.

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

impl<'a, K, V: ?Sized, S> Iterator for Iter<'a, K, V, S> where
    K: Hash + Eq + 'static,
    V: 'static,  type Item = Arc<Element<K, V>>;

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

Returns an iterator through the elements of the map.

Trait Implementations

impl<K, V, S> Clone for ConMap<K, V, S> where
    K: Hash + Eq,
    V: ?Sized,
    S: Clone + BuildHasher, 

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<K, V> Default for ConMap<K, V> where
    K: Hash + Eq,
    V: ?Sized, 

fn default() -> Self

Returns the "default value" for a type.

impl<'a, K, V, S> IntoIterator for &'a ConMap<K, V, S> where
    K: Hash + Eq,
    V: ?Sized, 

type Item = Arc<Element<K, V>>

The type of the elements being iterated over.

type IntoIter = Iter<'a, K, V, S>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, K, V, S> Extend<Arc<Element<K, V>>> for &'a ConMap<K, V, S> where
    K: Hash + Eq,
    V: ?Sized,
    S: BuildHasher, 

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

Extends a collection with the contents of an iterator.

impl<'a, K, V, S> Extend<(K, V)> for &'a ConMap<K, V, S> where
    K: Hash + Eq,
    S: BuildHasher, 

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

Extends a collection with the contents of an iterator.

impl<K, V, S> Extend<Arc<Element<K, V>>> for ConMap<K, V, S> where
    K: Hash + Eq,
    V: ?Sized,
    S: BuildHasher, 

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

Extends a collection with the contents of an iterator.

impl<K, V, S> Extend<(K, V)> for ConMap<K, V, S> where
    K: Hash + Eq,
    S: BuildHasher, 

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

Extends a collection with the contents of an iterator.

impl<K, V: ?Sized, S> Debug for ConMap<K, V, S> where
    K: Debug + Hash + Eq,
    V: Debug, 

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

Formats the value using the given formatter.

impl<K, V> FromIterator<Arc<Element<K, V>>> for ConMap<K, V> where
    K: Hash + Eq,
    V: ?Sized, 

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

Creates a value from an iterator.

impl<K, V> FromIterator<(K, V)> for ConMap<K, V> where
    K: Hash + Eq, 

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

Creates a value from an iterator.

impl<K, V: ?Sized> FromParallelIterator<Arc<Element<K, V>>> for ConMap<K, V> where
    K: Hash + Eq + Send + Sync,
    V: Send + Sync, 

fn from_par_iter<T>(par_iter: T) -> Self where
    T: IntoParallelIterator<Item = Arc<Element<K, V>>>, 

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

impl<K, V> FromParallelIterator<(K, V)> for ConMap<K, V> where
    K: Hash + Eq + Send + Sync,
    V: Send + Sync, 

fn from_par_iter<T>(par_iter: T) -> Self where
    T: IntoParallelIterator<Item = (K, V)>, 

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

impl<'a, K, V: ?Sized, S> ParallelExtend<Arc<Element<K, V>>> for &'a ConMap<K, V, S> where
    K: Hash + Eq + Send + Sync,
    V: Send + Sync,
    S: BuildHasher + Sync, 

fn par_extend<T>(&mut self, par_iter: T) where
    T: IntoParallelIterator<Item = Arc<Element<K, V>>>, 

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

impl<K, V, S> ParallelExtend<(K, V)> for ConMap<K, V, S> where
    K: Hash + Eq + Send + Sync,
    S: BuildHasher + Sync,
    V: Send + Sync, 

fn par_extend<T>(&mut self, par_iter: T) where
    T: IntoParallelIterator<Item = (K, V)>, 

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

impl<K, V: ?Sized, S> ParallelExtend<Arc<Element<K, V>>> for ConMap<K, V, S> where
    K: Hash + Eq + Send + Sync,
    V: Send + Sync,
    S: BuildHasher + Sync, 

fn par_extend<T>(&mut self, par_iter: T) where
    T: IntoParallelIterator<Item = Arc<Element<K, V>>>, 

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

impl<'a, K, V, S> ParallelExtend<(K, V)> for &'a ConMap<K, V, S> where
    K: Hash + Eq + Send + Sync,
    S: BuildHasher + Sync,
    V: Send + Sync, 

fn par_extend<T>(&mut self, par_iter: T) where
    T: IntoParallelIterator<Item = (K, V)>, 

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