diff --git a/src/lib.rs b/src/lib.rs index de06c51c..6d0d4a60 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -29,8 +29,8 @@ //! //! # Consistency //! -//! Retrieval operations (including [`get`](HashMap::get)) generally do not block, so may -//! overlap with update operations (including [`insert`](HashMap::insert)). Retrievals +//! Retrieval operations (including [`get`](ConcurrentHashMap::get)) generally do not block, so may +//! overlap with update operations (including [`insert`](ConcurrentHashMap::insert)). Retrievals //! reflect the results of the most recently *completed* update operations holding upon their //! onset. (More formally, an update operation for a given key bears a _happens-before_ relation //! with any successful retrieval for that key reporting the updated value.) @@ -38,11 +38,11 @@ //! Operations that inspect the map as a whole, rather than a single key, operate on a snapshot of //! the underlying table. For example, iterators return elements reflecting the state of the hash //! table at some point at or since the creation of the iterator. Aggregate status methods like -//! [`len`](HashMap::len) are typically useful only when a map is not undergoing concurrent -//! updates in other threads. Otherwise the results of these methods reflect transient states that -//! may be adequate for monitoring or estimation purposes, but not for program control. -//! Similarly, [`Clone`](std::clone::Clone) may not produce a "perfect" clone if the underlying -//! map is being concurrently modified. +//! [`len`](ConcurrentHashMap::len) are typically useful only when a map is not undergoing +//! concurrent updates in other threads. Otherwise the results of these methods reflect transient +//! states that may be adequate for monitoring or estimation purposes, but not for program control. +//! Similarly, [`Clone`](std::clone::Clone) may not produce a "perfect" clone if the underlying map +//! is being concurrently modified. //! //! # Resizing behavior //! @@ -53,7 +53,7 @@ //! and removed, but overall, this maintains a commonly accepted time/space tradeoff for hash //! tables. However, resizing this or any other kind of hash table may be a relatively slow //! operation. When possible, it is a good idea to provide a size estimate by using the -//! [`with_capacity`](HashMap::with_capacity) constructor. Note that using many keys with +//! [`with_capacity`](ConcurrentHashMap::with_capacity) constructor. Note that using many keys with //! exactly the same [`Hash`](std::hash::Hash) value is a sure way to slow down performance of any //! hash table. /* TODO: dynamic load factor */ //! diff --git a/src/map.rs b/src/map.rs index a196a4d0..880857a1 100644 --- a/src/map.rs +++ b/src/map.rs @@ -63,7 +63,7 @@ pub type HashMap = /// A concurrent hash table. /// -/// Prefer the type alias [`HashMap`]. +/// Prefer the type alias [`HashMap`] unless you are on `no_std`. /// /// See the [crate-level documentation](index.html) for details. pub struct ConcurrentHashMap @@ -266,7 +266,7 @@ where /// /// The map will be sized to accommodate `capacity` elements with a low chance of reallocating /// (assuming uniformly distributed hashes). If `capacity` is 0, the call will not allocate, - /// and is equivalent to [`HashMap::new`]. + /// and is equivalent to [`ConcurrentHashMap::new`]. /// /// Warning: `hash_builder` is normally randomly generated, and is designed to allow the map /// to be resistant to attacks that cause many collisions and very poor performance. @@ -368,7 +368,7 @@ where /// /// Returns `None` if this map contains no mapping for the key. /// - /// To obtain a `Guard`, use [`HashMap::guard`]. + /// To obtain a `Guard`, use [`ConcurrentHashMap::guard`]. /// /// The key may be any borrowed form of the map's key type, but `Hash` and `Eq` on the borrowed /// form must match those for the key type. @@ -479,7 +479,8 @@ where #[inline] /// Maps `key` to `value` in this table. /// - /// The value can be retrieved by calling [`HashMap::get`] with a key that is equal to the original key. + /// The value can be retrieved by calling [`ConcurrentHashMap::get`] with a key that is equal + /// to the original key. pub fn insert<'g>(&'g self, key: K, value: V, guard: &'g Guard) -> Option<&'g V> { self.check_guard(guard); self.put(key, value, false, guard) @@ -1690,7 +1691,8 @@ where /// /// If `f` returns `false` for a given key/value pair, but the value for that pair is concurrently /// modified before the removal takes place, the entry will not be removed. - /// If you want the removal to happen even in the case of concurrent modification, use [`HashMap::retain_force`]. + /// If you want the removal to happen even in the case of concurrent modification, use + /// [`ConcurrentHashMap::retain_force`]. pub fn retain(&self, mut f: F, guard: &Guard) where F: FnMut(&K, &V) -> bool, @@ -1710,7 +1712,8 @@ where /// In other words, remove all pairs (k, v) such that f(&k,&v) returns false. /// /// This method always deletes any key/value pair that `f` returns `false` for, - /// even if if the value is updated concurrently. If you do not want that behavior, use [`HashMap::retain`]. + /// even if if the value is updated concurrently. If you do not want that behavior, use + /// [`ConcurrentHashMap::retain`]. pub fn retain_force(&self, mut f: F, guard: &Guard) where F: FnMut(&K, &V) -> bool, diff --git a/src/map_ref.rs b/src/map_ref.rs index 27b34ab9..6075216f 100644 --- a/src/map_ref.rs +++ b/src/map_ref.rs @@ -6,14 +6,16 @@ use core::ops::{Deref, Index}; use crossbeam_epoch::Guard; #[cfg(feature = "std")] -/// A reference to a [`HashMap`], constructed with [`HashMap::pin`] or [`HashMap::with_guard`]. +/// A reference to a [`HashMap`](crate::HashMap), constructed with [`ConcurrentHashMap::pin`] or +/// [`ConcurrentHashMap::with_guard`]. /// /// The current thread will be pinned for the duration of this reference. /// Keep in mind that this prevents the collection of garbage generated by the map. pub type HashMapRef<'map, K, V, S = crate::DefaultHashBuilder> = ConcurrentHashMapRef<'map, K, V, parking_lot::RawMutex, S>; -/// A reference to a [`ConcurrentHashMap`], constructed with [`HashMap::pin`] or [`HashMap::with_guard`]. +/// A reference to a [`ConcurrentHashMap`], constructed with [`ConcurrentHashMap::pin`] or +/// [`ConcurrentHashMap::with_guard`]. /// /// Prefer the type alias [`HashMapRef`]. /// @@ -80,7 +82,7 @@ where L: lock_api::RawMutex, { /// Tests if `key` is a key in this table. - /// See also [`HashMap::contains_key`]. + /// See also [`ConcurrentHashMap::contains_key`]. pub fn contains_key(&self, key: &Q) -> bool where K: Borrow, @@ -90,7 +92,7 @@ where } /// Returns the value to which `key` is mapped. - /// See also [`HashMap::get`]. + /// See also [`ConcurrentHashMap::get`]. pub fn get<'g, Q>(&'g self, key: &Q) -> Option<&'g V> where K: Borrow, @@ -100,7 +102,7 @@ where } /// Returns the key-value pair corresponding to `key`. - /// See also [`HashMap::get_key_value`]. + /// See also [`ConcurrentHashMap::get_key_value`]. pub fn get_key_value<'g, Q>(&'g self, key: &Q) -> Option<(&'g K, &'g V)> where K: Borrow, @@ -110,20 +112,20 @@ where } /// Maps `key` to `value` in this table. - /// See also [`HashMap::insert`]. + /// See also [`ConcurrentHashMap::insert`]. pub fn insert(&self, key: K, value: V) -> Option<&'_ V> { self.map.insert(key, value, &self.guard) } /// Removes all entries from this map. - /// See also [`HashMap::clear`]. + /// See also [`ConcurrentHashMap::clear`]. pub fn clear(&self) { self.map.clear(&self.guard); } /// If the value for the specified `key` is present, attempts to /// compute a new mapping given the key and its current mapped value. - /// See also [`HashMap::compute_if_present`]. + /// See also [`ConcurrentHashMap::compute_if_present`]. pub fn compute_if_present<'g, Q, F>(&'g self, key: &Q, remapping_function: F) -> Option<&'g V> where K: Borrow, @@ -135,13 +137,13 @@ where } /// Tries to reserve capacity for at least additional more elements. - /// See also [`HashMap::reserve`]. + /// See also [`ConcurrentHashMap::reserve`]. pub fn reserve(&self, additional: usize) { self.map.reserve(additional, &self.guard) } /// Removes the key (and its corresponding value) from this map. - /// See also [`HashMap::remove`]. + /// See also [`ConcurrentHashMap::remove`]. pub fn remove<'g, Q>(&'g self, key: &Q) -> Option<&'g V> where K: Borrow, @@ -151,7 +153,7 @@ where } /// Retains only the elements specified by the predicate. - /// See also [`HashMap::retain`]. + /// See also [`ConcurrentHashMap::retain`]. pub fn retain(&self, f: F) where F: FnMut(&K, &V) -> bool, @@ -160,7 +162,7 @@ where } /// Retains only the elements specified by the predicate. - /// See also [`HashMap::retain_force`]. + /// See also [`ConcurrentHashMap::retain_force`]. pub fn retain_force(&self, f: F) where F: FnMut(&K, &V) -> bool, @@ -170,33 +172,33 @@ where /// An iterator visiting all key-value pairs in arbitrary order. /// The iterator element type is `(&'g K, &'g V)`. - /// See also [`HashMap::iter`]. + /// See also [`ConcurrentHashMap::iter`]. pub fn iter(&self) -> impl Iterator { self.map.iter(&self.guard) } /// An iterator visiting all keys in arbitrary order. /// The iterator element type is `&'g K`. - /// See also [`HashMap::keys`]. + /// See also [`ConcurrentHashMap::keys`]. pub fn keys(&self) -> impl Iterator { self.map.keys(&self.guard) } /// An iterator visiting all values in arbitrary order. /// The iterator element type is `&'g V`. - /// See also [`HashMap::values`]. + /// See also [`ConcurrentHashMap::values`]. pub fn values(&self) -> impl Iterator { self.map.values(&self.guard) } /// Returns the number of entries in the map. - /// See also [`HashMap::len`]. + /// See also [`ConcurrentHashMap::len`]. pub fn len(&self) -> usize { self.map.len() } /// Returns `true` if the map is empty. Otherwise returns `false`. - /// See also [`HashMap::is_empty`]. + /// See also [`ConcurrentHashMap::is_empty`]. pub fn is_empty(&self) -> bool { self.map.is_empty() }