chore: improve thread local macro docs (#21)

Change thread_local_node! examples so they correctly demonstrate their usage as declaration blocks as oppose to function calls.

Author: pedromfedricci

README.md

@@ -112,7 +112,7 @@ use std::thread;
 use mcslock::raw::spins::Mutex;
 
 // Requires `thread_local` feature.
-mcslock::thread_local_node!(static NODE);
+mcslock::thread_local_node! { static NODE }
 
 fn main() {
     let mutex = Arc::new(Mutex::new(0));

examples/thread_local.rs

@@ -6,7 +6,7 @@ use mcslock::raw::spins::Mutex;
 
 // Requires that the `thread_local` feature is enabled.
 mcslock::thread_local_node! {
-    // * Allows multiple static definitions, must be separated with semicolons.
+    // * Allows multiple static declarations, must be separated with semicolons.
     // * Visibility is optional (private by default).
     // * Requires `static` keyword and a UPPER_SNAKE_CASE name.
     pub static NODE;

src/barging/mutex.rs

@@ -497,9 +497,9 @@ impl<T: ?Sized, Rs: Relax, Rq: Relax> LockThen for MutexStackNode<T, Rs, Rq> {
 #[cfg(test)]
 impl<T: ?Sized, Rs: Relax, Rq: Relax> TryLockThen for MutexStackNode<T, Rs, Rq> {}
 
-#[cfg(all(feature = "lock_api", not(loom)))]
 // SAFETY: This `Mutex` implementation guarantees linearization of access and
 // modification to the protected data in a concurrent, multithreaded context.
+#[cfg(all(feature = "lock_api", not(loom)))]
 unsafe impl<Rs: Relax, Rq: Relax> lock_api::RawMutex for Mutex<(), Rs, Rq> {
     type GuardMarker = lock_api::GuardSend;
 
@@ -595,10 +595,10 @@ impl<T: ?Sized, Rs, Rq> core::ops::DerefMut for MutexGuard<'_, T, Rs, Rq> {
     }
 }
 
-#[cfg(all(loom, test))]
-#[cfg(not(tarpaulin_include))]
 // SAFETY: A guard instance hold the lock locked, with exclusive access to the
 // underlying data.
+#[cfg(all(loom, test))]
+#[cfg(not(tarpaulin_include))]
 unsafe impl<T: ?Sized, Rs, Rq> Guard for MutexGuard<'_, T, Rs, Rq> {
     type Target = T;
 

src/barging/thread_local.rs

@@ -12,7 +12,7 @@ impl<T: ?Sized, Rs: Relax, Rq: Relax> Mutex<T, Rs, Rq> {
     /// in the thread local storage of the locking threads. That is, the number
     /// of queue nodes is proportional at 1:1 to the number of locking threads.
     pub(super) fn lock_with_local_queue_node(&self) -> MutexGuard<'_, T, Rs, Rq> {
-        crate::thread_local_node!(static NODE);
+        crate::thread_local_node! { static NODE }
         // SAFETY: The thread local node: `NODE` is not borrowed to any other
         // locking operation for all duration of the `inner` borrow of it.
         unsafe { self.inner.lock_with_local_unchecked(&NODE.inner) }.into()

src/inner/barging/mod.rs

@@ -20,6 +20,7 @@ pub struct Mutex<T: ?Sized, L, Ws, Wq> {
 // SAFETY: A `Mutex` is safe to be sent across thread boundaries as long as
 // the inlined protected data `T` is also safe to be sent to other threads.
 unsafe impl<T: ?Sized + Send, L: Send, Ws, Wq> Send for Mutex<T, L, Ws, Wq> {}
+
 // SAFETY: A `Mutex` is safe to be shared across thread boundaries since it
 // guarantees linearization of access and modification to the protected data,
 // but only if the protected data `T` is safe to be sent to other threads.
@@ -53,7 +54,10 @@ impl<T: ?Sized, L: Lock, Ws: Wait, Wq: Wait> Mutex<T, L, Ws, Wq> {
     /// each call, storing it at the current stack frame.
     #[cfg(any(test, not(feature = "thread_local")))]
     pub fn lock_with_stack_queue_node(&self) -> MutexGuard<'_, T, L, Ws, Wq> {
-        self.lock(|f| self.queue.lock_with_then(&mut raw::MutexNode::new(), |()| f(self)))
+        self.lock(|f| {
+            let mut node = raw::MutexNode::new();
+            self.queue.lock_with_then(&mut node, |()| f(self));
+        })
     }
 
     /// Generic lock implementation over call site provided queueing logic.
@@ -139,6 +143,7 @@ pub struct MutexGuard<'a, T: ?Sized, L: Lock, Ws, Wq> {
 // Note that `std::sync::MutexGuard` is `!Send` because it must be compatible
 // with `Pthreads` implementation on Linux, but we do not have this constraint.
 unsafe impl<T: ?Sized + Send, L: Lock + Send, Ws, Wq> Send for MutexGuard<'_, T, L, Ws, Wq> {}
+
 // SAFETY: A `MutexGuard` is safe to be shared across thread boundaries since
 // it owns exclusive access over the protected data during its lifetime, and so
 // the can safely share references to the data, but only if the protected data
@@ -199,10 +204,10 @@ impl<T: ?Sized, L: Lock, Ws, Wq> Drop for MutexGuard<'_, T, L, Ws, Wq> {
     }
 }
 
-#[cfg(all(loom, test))]
-#[cfg(not(tarpaulin_include))]
 // SAFETY: A guard instance hold the lock locked, with exclusive access to the
 // underlying data.
+#[cfg(all(loom, test))]
+#[cfg(not(tarpaulin_include))]
 unsafe impl<T: ?Sized, L: Lock, Ws, Wq> crate::loom::Guard for MutexGuard<'_, T, L, Ws, Wq> {
     type Target = T;
 

src/inner/raw/mod.rs

@@ -27,7 +27,7 @@ pub struct MutexNodeInit<L> {
 
 impl<L> MutexNodeInit<L> {
     /// Returns a raw mutable pointer of this node.
-    #[allow(clippy::ref_as_ptr)] // 1.91.0
+    #[allow(clippy::ref_as_ptr)] // `from_ref`: 1.76.0
     const fn as_ptr(&self) -> *mut Self {
         (self as *const Self).cast_mut()
     }
@@ -88,7 +88,7 @@ impl<L> MutexNode<L> {
 impl<L: Lock> MutexNode<L> {
     /// Initializes this node's inner state, returning a shared reference
     /// pointing to it.
-    #[allow(clippy::missing_const_for_fn)] // 1.91.0
+    #[allow(clippy::missing_const_for_fn)] // &mut self in const: 1.83.0
     fn initialize(&mut self) -> &MutexNodeInit<L> {
         self.inner.write(MutexNodeInit::locked())
     }
@@ -113,6 +113,7 @@ pub struct Mutex<T: ?Sized, L, W> {
 // SAFETY: A `Mutex` is safe to be sent across thread boundaries as long as
 // the inlined protected data `T` is also safe to be sent to other threads.
 unsafe impl<T: ?Sized + Send, L, W> Send for Mutex<T, L, W> {}
+
 // SAFETY: A `Mutex` is safe to be shared across thread boundaries since it
 // guarantees linearization of access and modification to the protected data,
 // but only if the protected data `T` is safe to be sent to other threads.
@@ -267,11 +268,6 @@ struct MutexGuard<'a, T: ?Sized, L: Lock, W: Wait> {
     head: &'a MutexNodeInit<L>,
 }
 
-// SAFETY: A `MutexGuard` is safe to be sent across thread boundaries as long as
-// the referenced protected data `T` is also safe to be sent to other threads.
-// Note that `std::sync::MutexGuard` is `!Send` because it must be compatible
-// with `Pthreads` implementation on Linux, but we do not have this constraint.
-unsafe impl<T: ?Sized + Send, L: Lock + Send, W: Wait> Send for MutexGuard<'_, T, L, W> {}
 // SAFETY: A `MutexGuard` is safe to be shared across thread boundaries since
 // it owns exclusive access over the protected data during its lifetime, and so
 // the can safely share references to the data, but only if the protected data

src/lib.rs

@@ -80,7 +80,7 @@
 //! use mcslock::raw::spins::Mutex;
 //!
 //! // Requires `thread_local` feature.
-//! mcslock::thread_local_node!(static NODE);
+//! mcslock::thread_local_node! { static NODE }
 //!
 //! let mutex = Arc::new(Mutex::new(0));
 //! let c_mutex = Arc::clone(&mutex);

src/loom.rs

@@ -92,8 +92,8 @@ pub mod models {
     use loom::sync::Arc;
     use loom::{model, thread};
 
-    use crate::test::{lock_get, lock_inc, try_lock_inc, Int};
-    use crate::test::{LockThen, TryLockThen};
+    use crate::test::{lock_get, lock_inc, try_lock_inc};
+    use crate::test::{Int, LockThen, TryLockThen};
 
     /// Get a copy of the shared integer, converting it to usize.
     ///

src/raw/thread_local.rs

@@ -23,13 +23,13 @@ type Key = &'static LocalMutexNode;
 /// See: [`try_lock_with_local_then`], [`lock_with_local_then`],
 /// [`try_lock_with_local_then_unchecked`] or [`lock_with_local_then_unchecked`].
 ///
-/// The thread local node definition generated by this macro avoids lazy
+/// The thread local node declaration generated by this macro avoids lazy
 /// initialization and does not need to be dropped, which enables a more
 /// efficient underlying implementation. See [`std::thread_local!`] macro.
 ///
 /// # Sintax
 ///
-/// * Allows multiple static definitions, must be separated with semicolons.
+/// * Allows multiple static declarations, must be separated with semicolons.
 /// * Visibility is optional (private by default).
 /// * Requires `static` keyword and a **UPPER_SNAKE_CASE** name.
 ///
@@ -38,15 +38,13 @@ type Key = &'static LocalMutexNode;
 /// ```
 /// use mcslock::raw::spins::Mutex;
 ///
-/// // Multiple difenitions.
+/// // Multiple declarations allowed.
 /// mcslock::thread_local_node! {
 ///     pub static NODE;
-///     static OTHER_NODE1;
+///     static OTHER_NODE;
+///     // ...
 /// }
 ///
-/// // Single definition.
-/// mcslock::thread_local_node!(pub static OTHER_NODE2);
-///
 /// let mutex = Mutex::new(0);
 /// // Keys are provided to APIs by reference.
 /// mutex.lock_with_local_then(&NODE, |data| *data = 10);
@@ -63,14 +61,14 @@ type Key = &'static LocalMutexNode;
 macro_rules! thread_local_node {
     // Empty (base for recursion).
     () => {};
-    // Process multiply definitions (recursive).
+    // Process multiple declarations (recursive).
     ($vis:vis static $node:ident; $($rest:tt)*) => {
-        $crate::__thread_local_node_inner!($vis $node, raw);
-        $crate::thread_local_node!($($rest)*);
+        $crate::__thread_local_node_inner! { $vis $node, raw }
+        $crate::thread_local_node! { $($rest)* }
     };
     // Process single declaration.
     ($vis:vis static $node:ident) => {
-        $crate::__thread_local_node_inner!($vis $node, raw);
+        $crate::__thread_local_node_inner! { $vis $node, raw }
     };
 }
 
@@ -158,7 +156,7 @@ impl<T: ?Sized, R: Relax> Mutex<T, R> {
     ///
     /// use mcslock::raw::spins::Mutex;
     ///
-    /// mcslock::thread_local_node!(static NODE);
+    /// mcslock::thread_local_node! { static NODE }
     ///
     /// let mutex = Arc::new(Mutex::new(0));
     /// let c_mutex = Arc::clone(&mutex);
@@ -182,7 +180,7 @@ impl<T: ?Sized, R: Relax> Mutex<T, R> {
     /// ```compile_fail,E0515
     /// use mcslock::raw::spins::Mutex;
     ///
-    /// mcslock::thread_local_node!(static NODE);
+    /// mcslock::thread_local_node! { static NODE }
     ///
     /// let mutex = Mutex::new(1);
     /// let borrow = mutex.try_lock_with_local_then(&NODE, |data| &*data.unwrap());
@@ -194,7 +192,7 @@ impl<T: ?Sized, R: Relax> Mutex<T, R> {
     #[doc = concat!("```should_panic(expected = ", already_borrowed_error!(), ")")]
     /// use mcslock::raw::spins::Mutex;
     ///
-    /// mcslock::thread_local_node!(static NODE);
+    /// mcslock::thread_local_node! { static NODE }
     ///
     /// let mutex = Mutex::new(0);
     ///
@@ -205,7 +203,7 @@ impl<T: ?Sized, R: Relax> Mutex<T, R> {
     ///     let mutex = Mutex::new(());
     ///     mutex.try_lock_with_local_then(&NODE, |_data| ());
     /// });
-    /// ```
+    #[doc = "```"]
     #[inline]
     #[track_caller]
     pub fn try_lock_with_local_then<F, Ret>(&self, node: Key, f: F) -> Ret
@@ -250,7 +248,7 @@ impl<T: ?Sized, R: Relax> Mutex<T, R> {
     ///
     /// use mcslock::raw::spins::Mutex;
     ///
-    /// mcslock::thread_local_node!(static NODE);
+    /// mcslock::thread_local_node! { static NODE }
     ///
     /// let mutex = Arc::new(Mutex::new(0));
     /// let c_mutex = Arc::clone(&mutex);
@@ -274,11 +272,11 @@ impl<T: ?Sized, R: Relax> Mutex<T, R> {
     /// ```compile_fail,E0515
     /// use mcslock::raw::spins::Mutex;
     ///
-    /// mcslock::thread_local_node!(static NODE);
+    /// mcslock::thread_local_node! { static NODE }
     ///
     /// let mutex = Mutex::new(1);
     /// let data = unsafe {
-    ///     mutex.try_lock_with_local_then_unchecked(&NODE, |g| &*g.unwrap())
+    ///     mutex.try_lock_with_local_then_unchecked(&NODE, |d| &*d.unwrap())
     /// };
     /// ```
     ///
@@ -288,7 +286,7 @@ impl<T: ?Sized, R: Relax> Mutex<T, R> {
     /// ```no_run
     /// use mcslock::raw::spins::Mutex;
     ///
-    /// mcslock::thread_local_node!(static NODE);
+    /// mcslock::thread_local_node! { static NODE }
     ///
     /// let mutex = Mutex::new(0);
     ///
@@ -339,7 +337,7 @@ impl<T: ?Sized, R: Relax> Mutex<T, R> {
     ///
     /// use mcslock::raw::spins::Mutex;
     ///
-    /// mcslock::thread_local_node!(static NODE);
+    /// mcslock::thread_local_node! { static NODE }
     ///
     /// let mutex = Arc::new(Mutex::new(0));
     /// let c_mutex = Arc::clone(&mutex);
@@ -357,7 +355,7 @@ impl<T: ?Sized, R: Relax> Mutex<T, R> {
     /// ```compile_fail,E0515
     /// use mcslock::raw::spins::Mutex;
     ///
-    /// mcslock::thread_local_node!(static NODE);
+    /// mcslock::thread_local_node! { static NODE }
     ///
     /// let mutex = Mutex::new(1);
     /// let borrow = mutex.lock_with_local_then(&NODE, |data| &*data);
@@ -369,7 +367,7 @@ impl<T: ?Sized, R: Relax> Mutex<T, R> {
     #[doc = concat!("```should_panic(expected = ", already_borrowed_error!(), ")")]
     /// use mcslock::raw::spins::Mutex;
     ///
-    /// mcslock::thread_local_node!(static NODE);
+    /// mcslock::thread_local_node! { static NODE }
     ///
     /// let mutex = Mutex::new(0);
     ///
@@ -380,7 +378,7 @@ impl<T: ?Sized, R: Relax> Mutex<T, R> {
     ///     let mutex = Mutex::new(());
     ///     mutex.lock_with_local_then(&NODE, |_data| ());
     /// });
-    /// ```
+    #[doc = "```"]
     #[inline]
     #[track_caller]
     pub fn lock_with_local_then<F, Ret>(&self, node: Key, f: F) -> Ret
@@ -424,7 +422,7 @@ impl<T: ?Sized, R: Relax> Mutex<T, R> {
     ///
     /// use mcslock::raw::spins::Mutex;
     ///
-    /// mcslock::thread_local_node!(static NODE);
+    /// mcslock::thread_local_node! { static NODE }
     ///
     /// let mutex = Arc::new(Mutex::new(0));
     /// let c_mutex = Arc::clone(&mutex);
@@ -442,7 +440,7 @@ impl<T: ?Sized, R: Relax> Mutex<T, R> {
     /// ```compile_fail,E0515
     /// use mcslock::raw::spins::Mutex;
     ///
-    /// mcslock::thread_local_node!(static NODE);
+    /// mcslock::thread_local_node! { static NODE }
     ///
     /// let mutex = Mutex::new(1);
     /// let data = unsafe {
@@ -456,7 +454,7 @@ impl<T: ?Sized, R: Relax> Mutex<T, R> {
     /// ```no_run
     /// use mcslock::raw::spins::Mutex;
     ///
-    /// mcslock::thread_local_node!(static NODE);
+    /// mcslock::thread_local_node!{ static NODE }
     ///
     /// let mutex = Mutex::new(0);
     ///
@@ -482,7 +480,8 @@ impl<T: ?Sized, R: Relax> Mutex<T, R> {
     ///
     /// ```compile_fail
     /// use mcslock::raw::spins::Mutex;
-    /// mcslock::thread_local_node!(static NODE);
+    ///
+    /// mcslock::thread_local_node! { static NODE }
     ///
     /// let mutex = Mutex::new(1);
     /// let borrow = mutex.lock_with_local_then(&NODE, |data| data);
@@ -491,7 +490,8 @@ impl<T: ?Sized, R: Relax> Mutex<T, R> {
     /// ```compile_fail,E0521
     /// use std::thread;
     /// use mcslock::raw::spins::Mutex;
-    /// mcslock::thread_local_node!(static NODE);
+    ///
+    /// mcslock::thread_local_node! { static NODE }
     ///
     /// let mutex = Mutex::new(1);
     /// mutex.lock_with_local_then(&NODE, |data| {
@@ -506,9 +506,11 @@ impl<T: ?Sized, R: Relax> Mutex<T, R> {
 }
 
 // A thread local node definition used for testing.
+//
+// NOTE: Be mindfull of usage since it is a module global name.
 #[cfg(test)]
 #[cfg(not(tarpaulin_include))]
-thread_local_node!(static TEST_NODE);
+thread_local_node! { static TEST_NODE }
 
 /// A Mutex wrapper type that calls `lock_with_local_then` and
 /// `try_lock_with_local_then` when implementing testing traits.
@@ -598,8 +600,8 @@ impl<T: ?Sized, R: Relax> LockWithThen for MutexUnchecked<T, R> {
     where
         F: FnOnce(&mut Self::Target) -> Ret,
     {
-        // SAFETY: caller must guarantee that this thread local node is not
-        // already mutably borrowed for some other lock acquisition.
+        // SAFETY: The thread local node is not borrowed to any other
+        // locking operation for all duration of this call.
         unsafe { self.0.lock_with_local_then_unchecked(&TEST_NODE, f) }
     }
 }
@@ -610,8 +612,8 @@ impl<T: ?Sized, R: Relax> TryLockWithThen for MutexUnchecked<T, R> {
     where
         F: FnOnce(Option<&mut Self::Target>) -> Ret,
     {
-        // SAFETY: caller must guarantee that this thread local node is not
-        // already mutably borrowed for some other lock acquisition.
+        // SAFETY: The thread local node is not borrowed to any other
+        // locking operation for all duration of this call.
         unsafe { self.0.try_lock_with_local_then_unchecked(&TEST_NODE, f) }
     }
 

src/thread_local.rs

@@ -21,7 +21,7 @@ macro_rules! __thread_local_node_inner {
 
 /// Non-recursive, Loom based inner definition of `thread_local_node!`.
 ///
-/// This node definition uses Loom primitives and it can't be evaluated at
+/// This node declaration uses Loom primitives and it can't be evaluated at
 /// compile-time since Loom does not support that feature. Loom's `thread_local!`
 /// macro defines a `static` value as oppose to std's `const` value.
 #[cfg(all(loom, test))]