diff options
Diffstat (limited to 'src/collection/retry.rs')
| -rw-r--r-- | src/collection/retry.rs | 83 |
1 files changed, 77 insertions, 6 deletions
diff --git a/src/collection/retry.rs b/src/collection/retry.rs index 83842f8..db09ebf 100644 --- a/src/collection/retry.rs +++ b/src/collection/retry.rs @@ -422,10 +422,44 @@ impl<L> RetryingLockCollection<L> { Self { data } } + /// Gets an immutable reference to the underlying collection. + /// + /// # Examples + /// + /// ``` + /// use happylock::{Mutex, ThreadKey}; + /// use happylock::collection::RetryingLockCollection; + /// + /// let data = (Mutex::new(42), Mutex::new("")); + /// let lock = RetryingLockCollection::new(data); + /// + /// let key = ThreadKey::get().unwrap(); + /// let inner = lock.child(); + /// let guard = inner.0.lock(key); + /// assert_eq!(*guard, 42); + /// ``` + #[must_use] pub const fn child(&self) -> &L { &self.data } + /// Gets a mutable reference to the underlying collection. + /// + /// # Examples + /// + /// ``` + /// use happylock::{Mutex, ThreadKey}; + /// use happylock::collection::RetryingLockCollection; + /// + /// let data = (Mutex::new(42), Mutex::new("")); + /// let mut lock = RetryingLockCollection::new(data); + /// + /// let key = ThreadKey::get().unwrap(); + /// let mut inner = lock.child_mut(); + /// let guard = inner.0.get_mut(); + /// assert_eq!(*guard, 42); + /// ``` + #[must_use] pub fn child_mut(&mut self) -> &mut L { &mut self.data } @@ -515,9 +549,14 @@ impl<L: Lockable> RetryingLockCollection<L> { /// Attempts to lock the without blocking. /// - /// If successful, this method returns a guard that can be used to access - /// the data, and unlocks the data when it is dropped. Otherwise, `None` is - /// returned. + /// If the access could not be granted at this time, then `Err` is + /// returned. Otherwise, an RAII guard is returned which will release the + /// locks when it is dropped. + /// + /// # Errors + /// + /// If any of the locks in the collection are already locked, then an error + /// is returned containing the given key. /// /// # Examples /// @@ -622,9 +661,14 @@ impl<L: Sharable> RetryingLockCollection<L> { /// Attempts to lock the without blocking, in such a way that other threads /// can still read from the collection. /// - /// If successful, this method returns a guard that can be used to access - /// the data immutably, and unlocks the data when it is dropped. Otherwise, - /// `None` is returned. + /// If the access could not be granted at this time, then `Err` is + /// returned. Otherwise, an RAII guard is returned which will release the + /// shared access when it is dropped. + /// + /// # Errors + /// + /// If shared access cannot be acquired at this time, then an error is + /// returned containing the given key. /// /// # Examples /// @@ -685,12 +729,39 @@ impl<L: Sharable> RetryingLockCollection<L> { } impl<L: LockableGetMut> RetryingLockCollection<L> { + /// Gets a mutable reference to the data behind this + /// `RetryingLockCollection`. + /// + /// Since this call borrows the `RetryingLockCollection` mutably, no actual + /// locking needs to take place - the mutable borrow statically guarantees + /// no locks exist. + /// + /// # Examples + /// + /// ``` + /// use happylock::{Mutex, LockCollection}; + /// use happylock::collection::RetryingLockCollection; + /// + /// let mut mutex = RetryingLockCollection::new([Mutex::new(0), Mutex::new(0)]); + /// assert_eq!(mutex.get_mut(), [&mut 0, &mut 0]); + /// ``` pub fn get_mut(&mut self) -> L::Inner<'_> { LockableGetMut::get_mut(self) } } impl<L: LockableIntoInner> RetryingLockCollection<L> { + /// Consumes this `RetryingLockCollection`, returning the underlying data. + /// + /// # Examples + /// + /// ``` + /// use happylock::{Mutex, LockCollection}; + /// use happylock::collection::RetryingLockCollection; + /// + /// let mutex = RetryingLockCollection::new([Mutex::new(0), Mutex::new(0)]); + /// assert_eq!(mutex.into_inner(), [0, 0]); + /// ``` pub fn into_inner(self) -> L::Inner { LockableIntoInner::into_inner(self) } |