feat(maitake): add maitake::sync::RwLock

This branch adds an async read-write lock implementation in
`maitake::sync`. This lock is implemented using the `Semaphore` type
added in #301. The rwlock is modeled using a `Semaphore` with
`Semaphore::MAX_PERMITS` permits in it; a reader must acquire a single
permit to gain read access, while a writer must acquire all the permits.

maitake/src/loom.rs

@@ -141,12 +141,35 @@ mod inner {
                 f(self.0.get())
             }
 
+            #[inline(always)]
+            pub(crate) fn get(&self) -> ConstPtr<T> {
+                ConstPtr(self.0.get())
+            }
+
             #[inline(always)]
             pub(crate) fn get_mut(&self) -> MutPtr<T> {
                 MutPtr(self.0.get())
             }
         }
 
+        #[derive(Debug)]
+        pub(crate) struct ConstPtr<T: ?Sized>(*const T);
+
+        impl<T: ?Sized> ConstPtr<T> {
+            #[inline(always)]
+            pub(crate) unsafe fn deref(&self) -> &T {
+                &*self.0
+            }
+
+            #[inline(always)]
+            pub fn with<F, R>(&self, f: F) -> R
+            where
+                F: FnOnce(*const T) -> R,
+            {
+                f(self.0)
+            }
+        }
+
         #[derive(Debug)]
         pub(crate) struct MutPtr<T: ?Sized>(*mut T);
 

maitake/src/sync.rs

@@ -4,6 +4,9 @@
 //!
 //! - [`Mutex`]: a fairly queued, asynchronous [mutual exclusion lock], for
 //!       protecting shared data
+//! - [`RwLock`]: a fairly queued, asynchronous [readers-writer lock], which
+//!       allows concurrent read access to shared data while ensuring write
+//!       access is exclusive
 //! - [`Semaphore`]: an asynchronous [counting semaphore], for limiting the
 //!       number of tasks which may run concurrently
 //! - [`WaitCell`], a cell that stores a *single* waiting task's [`Waker`], so
@@ -13,11 +16,13 @@
 //! - [`WaitMap`], a set of waiting tasks associated with keys, in which a task
 //!       can be woken by its key
 //!
-//! [mutual exclusion lock]:https://en.wikipedia.org/wiki/Mutual_exclusion
+//! [mutual exclusion lock]: https://en.wikipedia.org/wiki/Mutual_exclusion
+//! [readers-writer lock]: https://en.wikipedia.org/wiki/Readers%E2%80%93writer_lock
 //! [counting semaphore]: https://en.wikipedia.org/wiki/Semaphore_(programming)
 //! [`Waker`]: core::task::Waker
 #![warn(missing_docs, missing_debug_implementations)]
 pub mod mutex;
+pub mod rwlock;
 pub mod semaphore;
 pub mod wait_cell;
 pub mod wait_map;
@@ -29,6 +34,8 @@ pub use self::mutex::OwnedMutexGuard;
 #[doc(inline)]
 pub use self::mutex::{Mutex, MutexGuard};
 #[doc(inline)]
+pub use self::rwlock::{RwLock, RwLockReadGuard, RwLockWriteGuard};
+#[doc(inline)]
 pub use self::semaphore::Semaphore;
 #[doc(inline)]
 pub use self::wait_cell::WaitCell;

maitake/src/sync/mutex.rs

@@ -1,6 +1,8 @@
-//! An asynchronous mutual exclusion lock.
+//! An asynchronous [mutual exclusion lock][mutex].
 //!
 //! See the documentation on the [`Mutex`] type for details.
+//!
+/// [mutex]: https://en.wikipedia.org/wiki/Mutual_exclusion
 use crate::{
     loom::cell::{MutPtr, UnsafeCell},
     sync::wait_queue::{self, WaitQueue},