From aef4e64e14e3988341071274505c41846e0be9ff Mon Sep 17 00:00:00 2001 From: Acrimon Date: Tue, 2 Jun 2020 03:32:46 +0200 Subject: [PATCH] Locking behaviour docs. --- src/lib.rs | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/src/lib.rs b/src/lib.rs index 5f1adce3..1a7a1e22 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -307,6 +307,8 @@ impl<'a, K: 'a + Eq + Hash, V: 'a, S: BuildHasher + Clone> DashMap { /// Inserts a key and a value into the map. /// + /// **Locking behaviour:** May deadlock if called when holding holding any sort of reference into the map. + /// /// # Examples /// /// ``` @@ -322,6 +324,8 @@ impl<'a, K: 'a + Eq + Hash, V: 'a, S: BuildHasher + Clone> DashMap { /// 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 holding any sort of reference into the map. + /// /// # Examples /// /// ``` @@ -343,6 +347,8 @@ impl<'a, K: 'a + Eq + Hash, V: 'a, S: BuildHasher + Clone> DashMap { /// 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 holding any sort of reference into the map. + /// /// ``` /// use dashmap::DashMap; /// @@ -370,6 +376,8 @@ impl<'a, K: 'a + Eq + Hash, V: 'a, S: BuildHasher + Clone> DashMap { /// Creates an iterator over a DashMap yielding immutable references. /// + /// **Locking behaviour:** May deadlock if called when holding holding a mutable reference into the map. + /// /// # Examples /// /// ``` @@ -386,6 +394,8 @@ impl<'a, K: 'a + Eq + Hash, V: 'a, S: BuildHasher + Clone> DashMap { /// Iterator over a DashMap yielding mutable references. /// + /// **Locking behaviour:** May deadlock if called when holding holding any sort of reference into the map. + /// /// # Examples /// /// ``` @@ -403,6 +413,8 @@ impl<'a, K: 'a + Eq + Hash, V: 'a, S: BuildHasher + Clone> DashMap { /// Get a immutable reference to an entry in the map /// + /// **Locking behaviour:** May deadlock if called when holding holding a mutable reference into the map. + /// /// # Examples /// /// ``` @@ -423,6 +435,8 @@ impl<'a, K: 'a + Eq + Hash, V: 'a, S: BuildHasher + Clone> DashMap { /// Get a mutable reference to an entry in the map /// + /// **Locking behaviour:** May deadlock if called when holding holding any sort of reference into the map. + /// /// # Examples /// /// ``` @@ -443,6 +457,8 @@ impl<'a, K: 'a + Eq + Hash, V: 'a, S: BuildHasher + Clone> DashMap { } /// Remove excess capacity to reduce memory usage. + /// + /// **Locking behaviour:** May deadlock if called when holding holding any sort of reference into the map. #[inline] pub fn shrink_to_fit(&self) { self._shrink_to_fit(); @@ -451,6 +467,8 @@ impl<'a, K: 'a + Eq + Hash, V: 'a, S: BuildHasher + Clone> DashMap { /// Retain elements that whose predicates return true /// and discard elements whose predicates return false. /// + /// **Locking behaviour:** May deadlock if called when holding holding any sort of reference into the map. + /// /// # Examples /// /// ``` @@ -470,6 +488,8 @@ impl<'a, K: 'a + Eq + Hash, V: 'a, S: BuildHasher + Clone> DashMap { /// Fetches the total number of key-value pairs stored in the map. /// + /// **Locking behaviour:** May deadlock if called when holding holding a mutable reference into the map. + /// /// # Examples /// /// ``` @@ -488,6 +508,8 @@ impl<'a, K: 'a + Eq + Hash, V: 'a, S: BuildHasher + Clone> DashMap { /// Checks if the map is empty or not. /// + /// **Locking behaviour:** May deadlock if called when holding holding a mutable reference into the map. + /// /// # Examples /// /// ``` @@ -503,6 +525,8 @@ impl<'a, K: 'a + Eq + Hash, V: 'a, S: BuildHasher + Clone> DashMap { /// Removes all key-value pairs in the map. /// + /// **Locking behaviour:** May deadlock if called when holding holding any sort of reference into the map. + /// /// # Examples /// /// ``` @@ -520,6 +544,8 @@ impl<'a, K: 'a + Eq + Hash, V: 'a, S: BuildHasher + Clone> DashMap { } /// Returns how many key-value pairs the map can store without reallocating. + /// + /// **Locking behaviour:** May deadlock if called when holding holding a mutable reference into the map. #[inline] pub fn capacity(&self) -> usize { self._capacity() @@ -527,6 +553,8 @@ impl<'a, K: 'a + Eq + Hash, V: 'a, S: BuildHasher + Clone> DashMap { /// Modify a specific value according to a function. /// + /// **Locking behaviour:** May deadlock if called when holding holding any sort of reference into the map. + /// /// # Examples /// /// ``` @@ -552,6 +580,8 @@ impl<'a, K: 'a + Eq + Hash, V: 'a, S: BuildHasher + Clone> DashMap { /// Modify every value in the map according to a function. /// + /// **Locking behaviour:** May deadlock if called when holding holding any sort of reference into the map. + /// /// # Examples /// /// ``` @@ -575,6 +605,8 @@ impl<'a, K: 'a + Eq + Hash, V: 'a, S: BuildHasher + Clone> DashMap { /// Checks if the map contains a specific key. /// + /// **Locking behaviour:** May deadlock if called when holding holding a mutable reference into the map. + /// /// # Examples /// /// ``` @@ -595,6 +627,8 @@ impl<'a, K: 'a + Eq + Hash, V: 'a, S: BuildHasher + Clone> DashMap { /// 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 holding any sort of reference into the map. #[inline] pub fn entry(&'a self, key: K) -> Entry<'a, K, V, S> { self._entry(key)