maitake_sync: add a bunch of new APIs to locks

maitake-sync/src/loom.rs

@@ -234,6 +234,14 @@ mod inner {
             }
         }
 
+        impl<T> UnsafeCell<T> {
+            #[inline(always)]
+            #[must_use]
+            pub(crate) fn into_inner(self) -> T {
+                self.0.into_inner()
+            }
+        }
+
         #[derive(Debug)]
         pub(crate) struct ConstPtr<T: ?Sized>(*const T);
 

maitake-sync/src/mutex.rs

@@ -104,7 +104,7 @@ pub struct Mutex<T: ?Sized> {
 /// [`lock`]: Mutex::lock
 /// [`try_lock`]: Mutex::try_lock
 /// [RAII]: https://rust-unofficial.github.io/patterns/patterns/behavioural/RAII.html
-#[must_use = "if unused, the Mutex will immediately unlock"]
+#[must_use = "if unused, the `Mutex` will immediately unlock"]
 pub struct MutexGuard<'a, T: ?Sized> {
     /// /!\ WARNING: semi-load-bearing drop order /!\
     ///
@@ -155,14 +155,21 @@ impl<T> Mutex<T> {
         #[must_use]
         pub fn new(data: T) -> Self {
             Self {
-                // The queue must start with a single stored wakeup, so that the
+                // The queue must start with a single store d wakeup, so that the
                 // first task that tries to acquire the lock will succeed
                 // immediately.
                 wait: WaitQueue::new_woken(),
                 data: UnsafeCell::new(data),
             }
         }
     }
+
+    /// Consumes this `Mutex`, returning the guarded data.
+    #[inline]
+    #[must_use]
+    pub fn into_inner(self) -> T {
+        self.data.into_inner()
+    }
 }
 
 impl<T: ?Sized> Mutex<T> {
@@ -227,6 +234,27 @@ impl<T: ?Sized> Mutex<T> {
         }
     }
 
+    /// Returns a mutable reference to the underlying data.
+    ///
+    /// Since this call borrows the `Mutex` mutably, no actual locking needs to
+    /// take place -- the mutable borrow statically guarantees no locks exist.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let mut lock = maitake_sync::spin::Mutex::new(0);
+    /// *lock.get_mut() = 10;
+    /// assert_eq!(*lock.try_lock().unwrap(), 10);
+    /// ```
+    pub fn get_mut(&mut self) -> &mut T {
+        unsafe {
+            // Safety: since this call borrows the `Mutex` mutably, no actual
+            // locking needs to take place -- the mutable borrow statically
+            // guarantees no locks exist.
+            self.data.with_mut(|data| &mut *data)
+        }
+    }
+
     /// Constructs a new `MutexGuard` for this `Mutex`.
     ///
     /// # Safety
@@ -240,6 +268,12 @@ impl<T: ?Sized> Mutex<T> {
     }
 }
 
+impl<T: Default> Default for Mutex<T> {
+    fn default() -> Self {
+        Self::new(Default::default())
+    }
+}
+
 impl<T: ?Sized + fmt::Debug> fmt::Debug for Mutex<T> {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         let Self { data: _, wait } = self;

maitake-sync/src/rwlock.rs

@@ -192,6 +192,13 @@ impl<T> RwLock<T> {
             }
         }
     }
+
+    /// Consumes this `RwLock`, returning the guarded data.
+    #[inline]
+    #[must_use]
+    pub fn into_inner(self) -> T {
+        self.data.into_inner()
+    }
 }
 
 impl<T: ?Sized> RwLock<T> {
@@ -401,6 +408,33 @@ impl<T: ?Sized> RwLock<T> {
             }
         }
     }
+
+    /// Returns a mutable reference to the underlying data.
+    ///
+    /// Since this call borrows the `RwLock` mutably, no actual locking needs to
+    /// take place -- the mutable borrow statically guarantees no locks exist.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let mut lock = maitake_sync::RwLock::new(0);
+    /// *lock.get_mut() = 10;
+    /// assert_eq!(*lock.try_read().unwrap(), 10);
+    /// ```
+    pub fn get_mut(&mut self) -> &mut T {
+        unsafe {
+            // Safety: since this call borrows the `RwLock` mutably, no actual
+            // locking needs to take place -- the mutable borrow statically
+            // guarantees no locks exist.
+            self.data.with_mut(|data| &mut *data)
+        }
+    }
+}
+
+impl<T: Default> Default for RwLock<T> {
+    fn default() -> Self {
+        Self::new(Default::default())
+    }
 }
 
 impl<T: ?Sized + fmt::Debug> fmt::Debug for RwLock<T> {

maitake-sync/src/spin/mutex.rs

@@ -3,12 +3,9 @@ use crate::{
         cell::{MutPtr, UnsafeCell},
         sync::atomic::{AtomicBool, Ordering::*},
     },
-    util::Backoff,
-};
-use core::{
-    fmt,
-    ops::{Deref, DerefMut},
+    util::{fmt, Backoff},
 };
+use core::ops::{Deref, DerefMut};
 
 /// A spinlock-based mutual exclusion lock for protecting shared data
 ///
@@ -29,7 +26,6 @@ use core::{
 ///
 /// [`lock`]: Mutex::lock
 /// [`try_lock`]: Mutex::try_lock
-#[derive(Debug)]
 pub struct Mutex<T> {
     locked: AtomicBool,
     data: UnsafeCell<T>,
@@ -46,6 +42,7 @@ pub struct Mutex<T> {
 ///
 /// [`lock`]: Mutex::lock
 /// [`try_lock`]: Mutex::try_lock
+#[must_use = "if unused, the `Mutex` will immediately unlock"]
 pub struct MutexGuard<'a, T> {
     ptr: MutPtr<T>,
     locked: &'a AtomicBool,
@@ -139,6 +136,48 @@ impl<T> Mutex<T> {
     pub unsafe fn force_unlock(&self) {
         self.locked.store(false, Release);
     }
+
+    /// Consumes this `Mutex`, returning the guarded data.
+    #[inline]
+    #[must_use]
+    pub fn into_inner(self) -> T {
+        self.data.into_inner()
+    }
+
+    /// Returns a mutable reference to the underlying data.
+    ///
+    /// Since this call borrows the `Mutex` mutably, no actual locking needs to
+    /// take place -- the mutable borrow statically guarantees no locks exist.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let mut lock = maitake_sync::spin::Mutex::new(0);
+    /// *lock.get_mut() = 10;
+    /// assert_eq!(*lock.lock(), 10);
+    /// ```
+    pub fn get_mut(&mut self) -> &mut T {
+        unsafe {
+            // Safety: since this call borrows the `Mutex` mutably, no actual
+            // locking needs to take place -- the mutable borrow statically
+            // guarantees no locks exist.
+            self.data.with_mut(|data| &mut *data)
+        }
+    }
+}
+
+impl<T: Default> Default for Mutex<T> {
+    fn default() -> Self {
+        Self::new(Default::default())
+    }
+}
+
+impl<T: fmt::Debug> fmt::Debug for Mutex<T> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("Mutex")
+            .field("data", &fmt::opt(&self.try_lock()).or_else("<locked>"))
+            .finish()
+    }
 }
 
 unsafe impl<T: Send> Send for Mutex<T> {}

maitake-sync/src/spin/rwlock.rs

@@ -1,14 +1,16 @@
+/// A spinlock-based [readers-writer lock].
+///
+/// See the documentation for the [`RwLock`] type for more information.
+///
+/// [readers-writer lock]: https://en.wikipedia.org/wiki/Readers%E2%80%93writer_lock
 use crate::{
     loom::{
         cell::{ConstPtr, MutPtr, UnsafeCell},
         sync::atomic::{AtomicUsize, Ordering::*},
     },
-    util::Backoff,
-};
-use core::{
-    fmt,
-    ops::{Deref, DerefMut},
+    util::{fmt, Backoff},
 };
+use core::ops::{Deref, DerefMut};
 
 /// A spinlock-based [readers-writer lock].
 ///
@@ -49,7 +51,7 @@ pub struct RwLock<T: ?Sized> {
 ///
 /// [`read`]: RwLock::read
 /// [`try_read`]: RwLock::try_read
-#[must_use]
+#[must_use = "if unused, the `RwLock` will immediately unlock"]
 pub struct RwLockReadGuard<'lock, T: ?Sized> {
     ptr: ConstPtr<T>,
     state: &'lock AtomicUsize,
@@ -66,7 +68,7 @@ pub struct RwLockReadGuard<'lock, T: ?Sized> {
 ///
 /// [`write`]: RwLock::write
 /// [`try_write`]: RwLock::try_write
-#[must_use = "if unused the RwLock will immediately unlock"]
+#[must_use = "if unused, the `RwLock` will immediately unlock"]
 pub struct RwLockWriteGuard<'lock, T: ?Sized> {
     ptr: MutPtr<T>,
     state: &'lock AtomicUsize,
@@ -184,6 +186,34 @@ impl<T: ?Sized> RwLock<T> {
         }
     }
 
+    /// Returns the current number of readers holding a read lock.
+    ///
+    /// # Note
+    ///
+    /// This method is not synchronized with attempts to increment the reader
+    /// count, and its value may become out of date as soon as it is read. This
+    /// is **not** intended to be used for synchronization purposes! It is
+    /// intended only for debugging purposes or for use as a heuristic.
+    #[inline]
+    #[must_use]
+    pub fn reader_count(&self) -> usize {
+        self.state.load(Relaxed) >> 1
+    }
+
+    /// Returns `true` if there is currently a writer holding a write lock.
+    ///
+    /// # Note
+    ///
+    /// This method is not synchronized its value may become out of date as soon
+    /// as it is read. This is **not** intended to be used for synchronization
+    /// purposes! It is intended only for debugging purposes or for use as a
+    /// heuristic.
+    #[inline]
+    #[must_use]
+    pub fn has_writer(&self) -> bool {
+        self.state.load(Relaxed) & WRITER == 1
+    }
+
     /// Attempts to acquire this `RwLock` for exclusive write access.
     ///
     /// If the access could not be granted at this time, this method returns
@@ -205,17 +235,62 @@ impl<T: ?Sized> RwLock<T> {
 
         None
     }
+
+    /// Returns a mutable reference to the underlying data.
+    ///
+    /// Since this call borrows the `RwLock` mutably, no actual locking needs to
+    /// take place -- the mutable borrow statically guarantees no locks exist.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let mut lock = maitake_sync::spin::RwLock::new(0);
+    /// *lock.get_mut() = 10;
+    /// assert_eq!(*lock.read(), 10);
+    /// ```
+    pub fn get_mut(&mut self) -> &mut T {
+        unsafe {
+            // Safety: since this call borrows the `RwLock` mutably, no actual
+            // locking needs to take place -- the mutable borrow statically
+            // guarantees no locks exist.
+            self.data.with_mut(|data| &mut *data)
+        }
+    }
+}
+
+impl<T> RwLock<T> {
+    /// Consumes this `RwLock`, returning the guarded data.
+    #[inline]
+    #[must_use]
+    pub fn into_inner(self) -> T {
+        self.data.into_inner()
+    }
 }
 
 impl<T: fmt::Debug> fmt::Debug for RwLock<T> {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        let mut s = f.debug_struct("RwLock");
-        s.field("state", &self.state.load(Relaxed));
-        match self.try_read() {
-            Some(read) => s.field("data", &read),
-            None => s.field("data", &format_args!("<write locked>")),
-        };
-        s.finish()
+        let state = &self.state.load(Relaxed);
+        f.debug_struct("RwLock")
+            // N.B.: this does *not* use the `reader_count` and `has_writer`
+            // methods *intentionally*, because those two methods perform
+            // independent reads of the lock's state, and may race with other
+            // lock operations that occur concurrently. If, for example, we read
+            // a non-zero reader count, and then read the state again to check
+            // for a writer, the reader may have been released and a write lock
+            // acquired between the two reads, resulting in the `Debug` impl
+            // displaying an invalid state when the lock was not actually *in*
+            // such a state!
+            //
+            // Therefore, we instead perform a single load to snapshot the state
+            // and unpack both the reader count and the writer count from the
+            // lock.
+            .field("readers", &(state >> 1))
+            .field("writer", &(state & WRITER))
+            .field(
+                "data",
+                &fmt::opt(&self.try_read()).or_else("<write locked>"),
+            )
+            .finish()
     }
 }
 

maitake-sync/src/wait_queue.rs

@@ -564,7 +564,7 @@ impl WaitQueue {
         }
 
         let mut batch = WakeBatch::new();
-        self.drain_to_wake_batch(&mut batch, self.queue.lock(), Wakeup::Closed);
+        let _ = self.drain_to_wake_batch(&mut batch, self.queue.lock(), Wakeup::Closed);
 
         // wake any tasks that were woken in the last iteration of the batch loop.
         batch.wake_all();
@@ -772,7 +772,7 @@ impl WaitQueue {
             let Some(waker) = Waiter::wake(node, &mut queue, wakeup.clone()) else {
                 // this waiter was enqueued by `Wait::register` and doesn't have
                 // a waker, just keep going.
-                continue
+                continue;
             };
 
             if batch.add_waker(waker) {