feat: add RwSpinlock readers-writer lock

Cargo.toml

@@ -15,6 +15,9 @@ owning_ref = ["lock_api/owning_ref"]
 [dependencies]
 lock_api = "0.4.7"
 
+[dev-dependencies]
+rand = "0.8"
+
 [package.metadata.release]
 dev-version = false
 pre-release-replacements = [

src/lib.rs

@@ -1,10 +1,12 @@
-//! Provides a simple spinlock based on the abstractions provided by the [`lock_api`] crate.
+//! Provides simple spinlocks based on the abstractions provided by the [`lock_api`] crate.
 //!
 //! [`lock_api`]: https://docs.rs/lock_api/
 //!
-//! ## Usage Example
+//! # Examples
 //!
-//! ```rust
+//! Use [`Spinlock`] for mutual exclusion:
+//!
+//! ```
 //! use spinning_top::Spinlock;
 //!
 //! fn main() {
@@ -24,22 +26,52 @@
 //!     // the guard automatically frees the lock at the end of the scope
 //! }
 //! ```
+//!
+//! Use [`RwSpinlock`] if you need a readers-writer lock:
+//!
+//! ```
+//! use spinning_top::RwSpinlock;
+//!
+//! let lock = RwSpinlock::new(5);
+//!
+//! // many reader locks can be held at once
+//! {
+//!     let r1 = lock.read();
+//!     let r2 = lock.read();
+//!     assert_eq!(*r1, 5);
+//!     assert_eq!(*r2, 5);
+//! } // read locks are dropped at this point
+//!
+//! // only one write lock may be held, however
+//! {
+//!     let mut w = lock.write();
+//!     *w += 1;
+//!     assert_eq!(*w, 6);
+//! } // write lock is dropped here
+//! ```
 
-#![no_std]
+#![cfg_attr(not(test), no_std)]
 #![warn(missing_docs)]
 #![warn(missing_debug_implementations)]
 
 /// The spinlock implemenation is based on the abstractions provided by the `lock_api` crate.
 pub use lock_api;
 
+pub use rw_spinlock::{BackoffRwSpinlock, RawRwSpinlock, RwSpinlock};
 pub use spinlock::{BackoffSpinlock, RawSpinlock, Spinlock};
 
 /// Type aliases for guards.
 pub mod guard {
+    pub use super::rw_spinlock::{
+        BackoffRwSpinlockReadGuard, BackoffRwSpinlockUpgradableReadGuard,
+        BackoffRwSpinlockWriteGuard, RwSpinlockReadGuard, RwSpinlockUpgradableReadGuard,
+        RwSpinlockWriteGuard,
+    };
     pub use super::spinlock::{
         BackoffSpinlockGuard, MappedBackoffSpinlockGuard, MappedSpinlockGuard, SpinlockGuard,
     };
 }
 
 pub mod relax;
+mod rw_spinlock;
 mod spinlock;