docs: update docs

examples/barging.rs

@@ -3,7 +3,7 @@ use std::sync::Arc;
 use std::thread;
 
 // Requires that the `barging` feature is enabled.
-use mcslock::barging::spins::Mutex;
+use mcslock::barging::spins::backoff::Mutex;
 
 fn main() {
     const N: usize = 10;

src/barging/mod.rs

@@ -13,11 +13,16 @@
 //! [`lock`] and [`try_lock`]. Guards are also accessible as the closure argument
 //! for [`lock_with`] and [`try_lock_with`] methods.
 //!
-//! The Mutex is generic over the relax strategy. User may choose a strategy
-//! as long as it implements the [`Relax`] trait. There is a number of strategies
-//! provided by the [`relax`] module. Each submodule provides type aliases for
-//! [`Mutex`] and [`MutexGuard`] associated with one relax strategy. See their
-//! documentation for more information.
+//! This Mutex is generic over the two layers of relax strategies. User may
+//! choose a strategy as long as it implements the [`Relax`] trait. The shared
+//! lock relax strategy is associated with the `Rs` generic paramater. The
+//! handoff relax strategy is then associated with the `Rq` generic parameter.
+//! Backoff relax strategies are usually prefered for shared lock contention,
+//! while non-backoff relax strategies are usually prefered for handoffs.
+//!
+//! There is a number of strategies provided by the [`relax`] module. Each
+//! submodule provides type aliases for [`Mutex`] and [`MutexGuard`] associated
+//! with one relax strategy. See their documentation for more information.
 //!
 //! [lock_api]: https://crates.io/crates/lock_api
 //! [`lock`]: Mutex::lock

src/barging/mutex.rs

@@ -24,9 +24,9 @@ use crate::relax::Relax;
 /// use std::sync::mpsc::channel;
 ///
 /// use mcslock::barging::Mutex;
-/// use mcslock::relax::Spin;
+/// use mcslock::relax::{Spin, SpinBackoff};
 ///
-/// type SpinMutex<T> = Mutex<T, Spin, Spin>;
+/// type SpinMutex<T> = Mutex<T, SpinBackoff, Spin>;
 ///
 /// const N: usize = 10;
 ///
@@ -79,9 +79,9 @@ impl<T, Rs, Rq> Mutex<T, Rs, Rq> {
     ///
     /// ```
     /// use mcslock::barging::Mutex;
-    /// use mcslock::relax::Spin;
+    /// use mcslock::relax::{Spin, SpinBackoff};
     ///
-    /// type SpinMutex<T> = Mutex<T, Spin, Spin>;
+    /// type SpinMutex<T> = Mutex<T, SpinBackoff, Spin>;
     ///
     /// const MUTEX: SpinMutex<i32> = SpinMutex::new(0);
     /// let mutex = SpinMutex::new(0);
@@ -111,9 +111,9 @@ impl<T, Rs, Rq> Mutex<T, Rs, Rq> {
     ///
     /// ```
     /// use mcslock::barging::Mutex;
-    /// use mcslock::relax::Spin;
+    /// use mcslock::relax::{Spin, SpinBackoff};
     ///
-    /// type SpinMutex<T> = Mutex<T, Spin, Spin>;
+    /// type SpinMutex<T> = Mutex<T, SpinBackoff, Spin>;
     ///
     /// let mutex = SpinMutex::new(0);
     /// assert_eq!(mutex.into_inner(), 0);
@@ -141,9 +141,9 @@ impl<T: ?Sized, Rs: Relax, Rq: Relax> Mutex<T, Rs, Rq> {
     /// use std::thread;
     ///
     /// use mcslock::barging::Mutex;
-    /// use mcslock::relax::Spin;
+    /// use mcslock::relax::{Spin, SpinBackoff};
     ///
-    /// type SpinMutex<T> = Mutex<T, Spin, Spin>;
+    /// type SpinMutex<T> = Mutex<T, SpinBackoff, Spin>;
     ///
     /// let mutex = Arc::new(SpinMutex::new(0));
     /// let c_mutex = Arc::clone(&mutex);
@@ -188,9 +188,9 @@ impl<T: ?Sized, Rs: Relax, Rq: Relax> Mutex<T, Rs, Rq> {
     /// use std::thread;
     ///
     /// use mcslock::barging::Mutex;
-    /// use mcslock::relax::Spin;
+    /// use mcslock::relax::{Spin, SpinBackoff};
     ///
-    /// type SpinMutex<T> = Mutex<T, Spin, Spin>;
+    /// type SpinMutex<T> = Mutex::<T, SpinBackoff, Spin>;
     ///
     /// let mutex = Arc::new(SpinMutex::new(0));
     /// let c_mutex = Arc::clone(&mutex);
@@ -237,9 +237,9 @@ impl<T: ?Sized, Rs, Rq> Mutex<T, Rs, Rq> {
     /// use std::thread;
     ///
     /// use mcslock::barging::Mutex;
-    /// use mcslock::relax::Spin;
+    /// use mcslock::relax::{Spin, SpinBackoff};
     ///
-    /// type SpinMutex<T> = Mutex<T, Spin, Spin>;
+    /// type SpinMutex<T> = Mutex::<T, SpinBackoff, Spin>;
     ///
     /// let mutex = Arc::new(SpinMutex::new(0));
     /// let c_mutex = Arc::clone(&mutex);
@@ -280,9 +280,9 @@ impl<T: ?Sized, Rs, Rq> Mutex<T, Rs, Rq> {
     /// use std::thread;
     ///
     /// use mcslock::barging::Mutex;
-    /// use mcslock::relax::Spin;
+    /// use mcslock::relax::{Spin, SpinBackoff};
     ///
-    /// type SpinMutex<T> = Mutex<T, Spin, Spin>;
+    /// type SpinMutex<T> = Mutex::<T, SpinBackoff, Spin>;
     ///
     /// let mutex = Arc::new(SpinMutex::new(0));
     /// let c_mutex = Arc::clone(&mutex);
@@ -327,9 +327,9 @@ impl<T: ?Sized, Rs, Rq> Mutex<T, Rs, Rq> {
     ///
     /// ```
     /// use mcslock::barging::Mutex;
-    /// use mcslock::relax::Spin;
+    /// use mcslock::relax::{Spin, SpinBackoff};
     ///
-    /// type SpinMutex<T> = Mutex<T, Spin, Spin>;
+    /// type SpinMutex<T> = Mutex<T, SpinBackoff, Spin>;
     ///
     /// let mutex = SpinMutex::new(0);
     /// let guard = mutex.lock();
@@ -352,9 +352,9 @@ impl<T: ?Sized, Rs, Rq> Mutex<T, Rs, Rq> {
     ///
     /// ```
     /// use mcslock::barging::Mutex;
-    /// use mcslock::relax::Spin;
+    /// use mcslock::relax::{Spin, SpinBackoff};
     ///
-    /// type SpinMutex<T> = Mutex<T, Spin, Spin>;
+    /// type SpinMutex<T> = Mutex<T, SpinBackoff, Spin>;
     ///
     /// let mut mutex = SpinMutex::new(0);
     /// *mutex.get_mut() = 10;