Docs and improvements

4 files changed, 310 insertions, 15 deletions

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<Guard> fmt::Display for PoisonError<Guard> {
 impl<Guard> Error for PoisonError<Guard> {}
 
 impl<Guard> PoisonError<Guard> {
+	/// 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<L: Lockable + RawLock> Lockable for Poisonable<L> {
 	}
 
 	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<L: Lockable + RawLock> Lockable for Poisonable<L> {
 	}
 
 	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<L: Lockable + RawLock> From<L> for Poisonable<L> {
 }
 
 impl<L: Lockable + RawLock> Poisonable<L> {
+	/// 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<L: Lockable + RawLock> Poisonable<L> {
 		key: Key,
 	) -> PoisonResult<PoisonGuard<'flag, 'key, L::Guard<'flag>, 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<L: Lockable + RawLock> Poisonable<L> {
 		}
 	}
 
+	/// 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<L: Lockable + RawLock> Poisonable<L> {
 		}
 	}
 
+	/// 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::<Mutex<_>>::unlock(guard);
+	/// ```
 	pub fn unlock<'flag, 'key, Key: Keyable + 'key>(
 		guard: PoisonGuard<'flag, 'key, L::Guard<'flag>, Key>,
 	) -> Key {
@@ -108,14 +195,92 @@ impl<L: Lockable + RawLock> Poisonable<L> {
 		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<L> {
 		if self.is_poisoned() {
 			Err(PoisonError::new(self.inner))
@@ -124,6 +289,27 @@ impl<L: Lockable + RawLock> Poisonable<L> {
 		}
 	}
 
+	/// 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))