From 00991791bba57a8757ba207a573e360224f43e6e Mon Sep 17 00:00:00 2001 From: Botahamec Date: Thu, 26 Sep 2024 22:12:52 -0400 Subject: Docs and improvements --- src/poisonable/error.rs | 96 ++++++++++++++++++++ src/poisonable/flag.rs | 2 +- src/poisonable/guard.rs | 15 ++- src/poisonable/poisonable.rs | 212 ++++++++++++++++++++++++++++++++++++++++--- 4 files changed, 310 insertions(+), 15 deletions(-) (limited to 'src/poisonable') diff --git a/src/poisonable/error.rs b/src/poisonable/error.rs index 2384953..1c4d60a 100644 --- a/src/poisonable/error.rs +++ b/src/poisonable/error.rs @@ -18,21 +18,117 @@ impl fmt::Display for PoisonError { impl Error for PoisonError {} impl PoisonError { + /// Creates a `PoisonError` + /// + /// This is generally created by methods like [`Poisonable::lock`]. + /// + /// ``` + /// use happylock::poisonable::PoisonError; + /// + /// let error = PoisonError::new("oh no"); + /// ``` + /// + /// [`Poisonable::lock`]: `crate::poisonable::Poisonable::lock` #[must_use] pub const fn new(guard: Guard) -> Self { Self { guard } } + /// Consumes the error indicating that a lock is poisonmed, returning the + /// underlying guard to allow access regardless. + /// + /// # Examples + /// + /// ``` + /// use std::collections::HashSet; + /// use std::sync::Arc; + /// use std::thread; + /// + /// use happylock::{Mutex, Poisonable, ThreadKey}; + /// + /// let mutex = Arc::new(Poisonable::new(Mutex::new(HashSet::new()))); + /// + /// // poison the mutex + /// let c_mutex = Arc::clone(&mutex); + /// let _ = thread::spawn(move || { + /// let key = ThreadKey::get().unwrap(); + /// let mut data = c_mutex.lock(key).unwrap(); + /// data.insert(10); + /// panic!(); + /// }).join(); + /// + /// let key = ThreadKey::get().unwrap(); + /// let p_err = mutex.lock(key).unwrap_err(); + /// let data = p_err.into_inner(); + /// println!("recovered {} items", data.len()); + /// ``` #[must_use] pub fn into_inner(self) -> Guard { self.guard } + /// Reaches into this error indicating that a lock is poisoned, returning a + /// reference to the underlying guard to allow access regardless. + /// + /// # Examples + /// + /// ``` + /// use std::collections::HashSet; + /// use std::sync::Arc; + /// use std::thread; + /// + /// use happylock::{Mutex, Poisonable, ThreadKey}; + /// + /// let mutex = Arc::new(Poisonable::new(Mutex::new(HashSet::new()))); + /// + /// // poison the mutex + /// let c_mutex = Arc::clone(&mutex); + /// let _ = thread::spawn(move || { + /// let key = ThreadKey::get().unwrap(); + /// let mut data = c_mutex.lock(key).unwrap(); + /// data.insert(10); + /// panic!(); + /// }).join(); + /// + /// let key = ThreadKey::get().unwrap(); + /// let p_err = mutex.lock(key).unwrap_err(); + /// let data = p_err.get_ref(); + /// println!("recovered {} items", data.len()); + /// ``` #[must_use] pub const fn get_ref(&self) -> &Guard { &self.guard } + /// Reaches into this error indicating that a lock is poisoned, returning a + /// mutable reference to the underlying guard to allow access regardless. + /// + /// # Examples + /// + /// ``` + /// use std::collections::HashSet; + /// use std::sync::Arc; + /// use std::thread; + /// + /// use happylock::{Mutex, Poisonable, ThreadKey}; + /// + /// let mutex = Arc::new(Poisonable::new(Mutex::new(HashSet::new()))); + /// + /// // poison the mutex + /// let c_mutex = Arc::clone(&mutex); + /// let _ = thread::spawn(move || { + /// let key = ThreadKey::get().unwrap(); + /// let mut data = c_mutex.lock(key).unwrap(); + /// data.insert(10); + /// panic!(); + /// }).join(); + /// + /// let key = ThreadKey::get().unwrap(); + /// let mut p_err = mutex.lock(key).unwrap_err(); + /// let data = p_err.get_mut(); + /// data.insert(20); + /// println!("recovered {} items", data.len()); + /// ``` #[must_use] pub fn get_mut(&mut self) -> &mut Guard { &mut self.guard diff --git a/src/poisonable/flag.rs b/src/poisonable/flag.rs index 0775c71..be38a38 100644 --- a/src/poisonable/flag.rs +++ b/src/poisonable/flag.rs @@ -14,7 +14,7 @@ impl PoisonFlag { } pub fn clear_poison(&self) { - self.0.store(true, Relaxed) + self.0.store(false, Relaxed) } } diff --git a/src/poisonable/guard.rs b/src/poisonable/guard.rs index 97b0028..a8a54fe 100644 --- a/src/poisonable/guard.rs +++ b/src/poisonable/guard.rs @@ -1,10 +1,23 @@ use std::fmt::{Debug, Display}; +use std::marker::PhantomData; use std::ops::{Deref, DerefMut}; use std::sync::atomic::Ordering::Relaxed; use crate::Keyable; -use super::{PoisonGuard, PoisonRef}; +use super::{PoisonFlag, PoisonGuard, PoisonRef}; + +impl<'a, Guard> PoisonRef<'a, Guard> { + // This is used so that we don't keep accidentally adding the flag reference + pub(super) const fn new(flag: &'a PoisonFlag, guard: Guard) -> Self { + Self { + guard, + #[cfg(panic = "unwind")] + flag, + _phantom: PhantomData, + } + } +} impl<'flag, Guard> Drop for PoisonRef<'flag, Guard> { fn drop(&mut self) { diff --git a/src/poisonable/poisonable.rs b/src/poisonable/poisonable.rs index f774e2d..4d8d1eb 100644 --- a/src/poisonable/poisonable.rs +++ b/src/poisonable/poisonable.rs @@ -18,10 +18,7 @@ unsafe impl Lockable for Poisonable { } unsafe fn guard(&self) -> Self::Guard<'_> { - let ref_guard = PoisonRef { - guard: self.inner.guard(), - flag: &self.poisoned, - }; + let ref_guard = PoisonRef::new(&self.poisoned, self.inner.guard()); if self.is_poisoned() { Ok(ref_guard) @@ -31,10 +28,7 @@ unsafe impl Lockable for Poisonable { } unsafe fn read_guard(&self) -> Self::ReadGuard<'_> { - let ref_guard = PoisonRef { - guard: self.inner.read_guard(), - flag: &self.poisoned, - }; + let ref_guard = PoisonRef::new(&self.poisoned, self.inner.read_guard()); if self.is_poisoned() { Ok(ref_guard) @@ -51,6 +45,15 @@ impl From for Poisonable { } impl Poisonable { + /// Creates a new `Poisonable` + /// + /// # Examples + /// + /// ``` + /// use happylock::{Mutex, Poisonable}; + /// + /// let mutex = Poisonable::new(Mutex::new(0)); + /// ``` pub const fn new(value: L) -> Self { Self { inner: value, @@ -63,21 +66,49 @@ impl Poisonable { key: Key, ) -> PoisonResult, Key>> { let guard = PoisonGuard { - guard: PoisonRef { - guard: self.inner.guard(), - flag: &self.poisoned, - }, + guard: PoisonRef::new(&self.poisoned, self.inner.guard()), key, _phantom: PhantomData, }; - if !self.is_poisoned() { + if self.is_poisoned() { return Err(PoisonError::new(guard)); } Ok(guard) } + /// Acquires the lock, blocking the current thread until it is ok to do so. + /// + /// This function will block the current thread until it is available to + /// acquire the mutex. Upon returning, the thread is the only thread with + /// the lock held. An RAII guard is returned to allow scoped unlock of the + /// lock. When the guard goes out of scope, the mutex will be unlocked. + /// + /// # Errors + /// + /// If another use of this mutex panicked while holding the mutex, then + /// this call will return an error once thr mutex is acquired. + /// + /// # Examples + /// + /// ``` + /// use std::sync::Arc; + /// use std::thread; + /// + /// use happylock::{Mutex, Poisonable, ThreadKey}; + /// + /// let mutex = Arc::new(Poisonable::new(Mutex::new(0))); + /// let c_mutex = Arc::clone(&mutex); + /// + /// thread::spawn(move || { + /// let key = ThreadKey::get().unwrap(); + /// **c_mutex.lock(key).unwrap() = 10; + /// }).join().expect("thread::spawn failed"); + /// + /// let key = ThreadKey::get().unwrap(); + /// assert_eq!(**mutex.lock(key).unwrap(), 10); + /// ``` pub fn lock<'flag, 'key, Key: Keyable + 'key>( &'flag self, key: Key, @@ -88,6 +119,47 @@ impl Poisonable { } } + /// Attempts to acquire this lock. + /// + /// If the lock could not be acquired at this time, then [`Err`] is + /// returned. Otherwise, an RAII guard is returned. The lock will be + /// unlocked when the guard is dropped. + /// + /// This function does not block. + /// + /// # Errors + /// + /// If another user of this mutex panicked while holding the mutex, then + /// this call will return the [`Poisoned`] error if the mutex would + /// otherwise be acquired. + /// + /// If the mutex could not be acquired because it is already locked, then + /// this call will return the [`WouldBlock`] error. + /// + /// # Examples + /// + /// ``` + /// use std::sync::Arc; + /// use std::thread; + /// + /// use happylock::{Mutex, Poisonable, ThreadKey}; + /// + /// let mutex = Arc::new(Poisonable::new(Mutex::new(0))); + /// let c_mutex = Arc::clone(&mutex); + /// + /// thread::spawn(move || { + /// let key = ThreadKey::get().unwrap(); + /// let mut lock = c_mutex.try_lock(key); + /// if let Ok(ref mut mutex) = lock { + /// ***mutex = 10; + /// } else { + /// println!("try_lock failed"); + /// } + /// }).join().expect("thread::spawn failed"); + /// + /// let key = ThreadKey::get().unwrap(); + /// assert_eq!(**mutex.lock(key).unwrap(), 10); + /// ``` pub fn try_lock<'flag, 'key, Key: Keyable + 'key>( &'flag self, key: Key, @@ -101,6 +173,21 @@ impl Poisonable { } } + /// Consumes the [`PoisonGuard`], and consequently unlocks its `Poisonable`. + /// + /// # Examples + /// + /// ``` + /// use happylock::{ThreadKey, Mutex, Poisonable}; + /// + /// let key = ThreadKey::get().unwrap(); + /// let mutex = Poisonable::new(Mutex::new(0)); + /// + /// let mut guard = mutex.lock(key).unwrap(); + /// **guard += 20; + /// + /// let key = Poisonable::>::unlock(guard); + /// ``` pub fn unlock<'flag, 'key, Key: Keyable + 'key>( guard: PoisonGuard<'flag, 'key, L::Guard<'flag>, Key>, ) -> Key { @@ -108,14 +195,92 @@ impl Poisonable { guard.key } + /// Determines whether the mutex is poisoned. + /// + /// If another thread is active, the mutex can still become poisoned at any + /// time. You should not trust a `false` value for program correctness + /// without additional synchronization. + /// + /// # Examples + /// + /// ``` + /// use std::sync::Arc; + /// use std::thread; + /// + /// use happylock::{Mutex, Poisonable, ThreadKey}; + /// + /// let mutex = Arc::new(Poisonable::new(Mutex::new(0))); + /// let c_mutex = Arc::clone(&mutex); + /// + /// let _ = thread::spawn(move || { + /// let key = ThreadKey::get().unwrap(); + /// let _lock = c_mutex.lock(key).unwrap(); + /// panic!(); // the mutex gets poisoned + /// }).join(); + /// + /// assert_eq!(mutex.is_poisoned(), true); + /// ``` pub fn is_poisoned(&self) -> bool { self.poisoned.is_poisoned() } + /// Clear the poisoned state from a lock. + /// + /// If the lock is poisoned, it will remain poisoned until this function + /// is called. This allows recovering from a poisoned state and marking + /// that it has recovered. For example, if the value is overwritten by a + /// known-good value, then the lock can be marked as un-poisoned. Or + /// possibly, the value could by inspected to determine if it is in a + /// consistent state, and if so the poison is removed. + /// + /// # Examples + /// + /// ``` + /// use std::sync::Arc; + /// use std::thread; + /// + /// use happylock::{Mutex, Poisonable, ThreadKey}; + /// + /// let mutex = Arc::new(Poisonable::new(Mutex::new(0))); + /// let c_mutex = Arc::clone(&mutex); + /// + /// let _ = thread::spawn(move || { + /// let key = ThreadKey::get().unwrap(); + /// let _lock = c_mutex.lock(key).unwrap(); + /// panic!(); // the mutex gets poisoned + /// }).join(); + /// + /// assert_eq!(mutex.is_poisoned(), true); + /// + /// let key = ThreadKey::get().unwrap(); + /// let x = mutex.lock(key).unwrap_or_else(|mut e| { + /// ***e.get_mut() = 1; + /// mutex.clear_poison(); + /// e.into_inner() + /// }); + /// + /// assert_eq!(mutex.is_poisoned(), false); + /// assert_eq!(**x, 1); + /// ``` pub fn clear_poison(&self) { self.poisoned.clear_poison() } + /// Consumes this `Poisonable`, returning the underlying lock. + /// + /// # Errors + /// + /// If another user of this lock panicked while holding the lock, then this + /// call will return an error instead. + /// + /// # Examples + /// + /// ``` + /// use happylock::{Mutex, Poisonable}; + /// + /// let mutex = Poisonable::new(Mutex::new(0)); + /// assert_eq!(mutex.into_inner().unwrap().into_inner(), 0); + /// ``` pub fn into_inner(self) -> PoisonResult { if self.is_poisoned() { Err(PoisonError::new(self.inner)) @@ -124,6 +289,27 @@ impl Poisonable { } } + /// Returns a mutable reference to the underlying lock. + /// + /// Since this call borrows the `Poisonable` mutable, no actual locking + /// needs to take place - the mutable borrow statically guarantees no locks + /// exist. + /// + /// # Errors + /// + /// If another user of this lock panicked while holding the lock, then + /// this call will return an error instead. + /// + /// # Examples + /// + /// ``` + /// use happylock::{Mutex, Poisonable, ThreadKey}; + /// + /// let key = ThreadKey::get().unwrap(); + /// let mut mutex = Poisonable::new(Mutex::new(0)); + /// *mutex.get_mut().unwrap().as_mut() = 10; + /// assert_eq!(**mutex.lock(key).unwrap(), 10); + /// ``` pub fn get_mut(&mut self) -> PoisonResult<&mut L> { if self.is_poisoned() { Err(PoisonError::new(&mut self.inner)) -- cgit v1.2.3