From 17dab88a7b4bc86cf156a1e0ac1bac19e6f9f5c6 Mon Sep 17 00:00:00 2001 From: Botahamec Date: Sat, 29 Mar 2025 17:34:10 -0400 Subject: Clean up existing documentation --- src/rwlock/rwlock.rs | 74 ++++++++++++++++++++++++++++++++-------------------- 1 file changed, 46 insertions(+), 28 deletions(-) (limited to 'src/rwlock/rwlock.rs') diff --git a/src/rwlock/rwlock.rs b/src/rwlock/rwlock.rs index f1cdca5..0dce710 100644 --- a/src/rwlock/rwlock.rs +++ b/src/rwlock/rwlock.rs @@ -147,6 +147,8 @@ impl RwLock { /// use happylock::RwLock; /// /// let lock = RwLock::new(5); + /// + /// /// ``` #[must_use] pub const fn new(data: T) -> Self { @@ -211,9 +213,9 @@ impl RwLock { /// ``` /// use happylock::{RwLock, ThreadKey}; /// + /// let key = ThreadKey::get().unwrap(); /// let lock = RwLock::new(String::new()); /// { - /// let key = ThreadKey::get().unwrap(); /// let mut s = lock.write(key); /// *s = "modified".to_owned(); /// } @@ -228,7 +230,7 @@ impl RwLock { impl RwLock { /// Returns a mutable reference to the underlying data. /// - /// Since this call borrows `RwLock` mutably, no actual locking is taking + /// Since this call borrows `RwLock` mutably, no actual locking needs to take /// place. The mutable borrow statically guarantees that no locks exist. /// /// # Examples @@ -237,9 +239,9 @@ impl RwLock { /// use happylock::{ThreadKey, RwLock}; /// /// let key = ThreadKey::get().unwrap(); - /// let mut mutex = RwLock::new(0); - /// *mutex.get_mut() = 10; - /// assert_eq!(*mutex.read(key), 10); + /// let mut lock = RwLock::new(0); + /// *lock.get_mut() = 10; + /// assert_eq!(*lock.read(key), 10); /// ``` #[must_use] pub fn get_mut(&mut self) -> &mut T { @@ -349,7 +351,9 @@ impl RwLock { /// /// The calling thread will be blocked until there are no more writers /// which hold the lock. There may be other readers currently inside the - /// lock when this method returns. + /// lock when this method returns. This method does not provide any guarantees + /// with respect to the ordering of whether contentious readers or writers + /// will acquire the lock first. /// /// Returns an RAII guard which will release this thread's shared access /// once it is dropped. @@ -360,21 +364,21 @@ impl RwLock { /// # Examples /// /// ``` - /// use std::sync::Arc; /// use std::thread; /// use happylock::{RwLock, ThreadKey}; /// /// let key = ThreadKey::get().unwrap(); - /// let lock = Arc::new(RwLock::new(1)); - /// let c_lock = Arc::clone(&lock); + /// let lock = RwLock::new(1); /// /// let n = lock.read(key); /// assert_eq!(*n, 1); /// - /// thread::spawn(move || { - /// let key = ThreadKey::get().unwrap(); - /// let r = c_lock.read(key); - /// }).join().unwrap(); + /// thread::scope(|s| { + /// s.spawn(|| { + /// let key = ThreadKey::get().unwrap(); + /// let r = lock.read(key); + /// }); + /// }); /// ``` /// /// [`ThreadKey`]: `crate::ThreadKey` @@ -400,8 +404,8 @@ impl RwLock { /// /// # Errors /// - /// If the `RwLock` could not be acquired because it was already locked - /// exclusively, then an error will be returned containing the given key. + /// This function will return an error containing the [`ThreadKey`] if the + /// `RwLock` could not be acquired because it was already locked exclusively. /// /// # Examples /// @@ -470,10 +474,11 @@ impl RwLock { /// let key = ThreadKey::get().unwrap(); /// let lock = RwLock::new(1); /// - /// match lock.try_write(key) { - /// Ok(n) => assert_eq!(*n, 1), - /// Err(_) => unreachable!(), - /// }; + /// let mut n = lock.write(key); + /// *n = 2; + /// + /// let key = RwLock::unlock_write(n); + /// assert_eq!(*lock.read(key), 2); /// ``` /// /// [`ThreadKey`]: `crate::ThreadKey` @@ -486,10 +491,11 @@ impl RwLock { } } - /// Attempts to lock this `RwLock` with exclusive write access. + /// Attempts to lock this `RwLock` with exclusive write access, without + /// blocking. /// /// This function does not block. If the lock could not be acquired at this - /// time, then `None` is returned. Otherwise, an RAII guard is returned + /// time, then `Err` is returned. Otherwise, an RAII guard is returned /// which will release the lock when it is dropped. /// /// This function does not provide any guarantees with respect to the @@ -498,8 +504,8 @@ impl RwLock { /// /// # Errors /// - /// If the `RwLock` could not be acquired because it was already locked, - /// then an error will be returned containing the given key. + /// This function will return an error containing the [`ThreadKey`] if the + /// `RwLock` could not be acquired because it was already locked exclusively. /// /// # Examples /// @@ -509,8 +515,17 @@ impl RwLock { /// let key = ThreadKey::get().unwrap(); /// let lock = RwLock::new(1); /// + /// let key = match lock.try_write(key) { + /// Ok(mut n) => { + /// assert_eq!(*n, 1); + /// *n = 2; + /// RwLock::unlock_write(n) + /// } + /// Err(_) => unreachable!(), + /// }; + /// /// let n = lock.read(key); - /// assert_eq!(*n, 1); + /// assert_eq!(*n, 2); /// ``` pub fn try_write(&self, key: ThreadKey) -> Result, ThreadKey> { unsafe { @@ -532,7 +547,7 @@ impl RwLock { /// Immediately drops the guard, and consequently releases the shared lock. /// /// This function is equivalent to calling [`drop`] on the guard, except - /// that it returns the key that was used to create it. Alternately, the + /// that it returns the key that was used to create it. Alternatively, the /// guard will be automatically dropped when it goes out of scope. /// /// # Examples @@ -556,9 +571,9 @@ impl RwLock { /// Immediately drops the guard, and consequently releases the exclusive /// lock. /// - /// This function is equivalent to calling [`drop`] on the guard, except - /// that it returns the key that was used to create it. Alternately, the - /// guard will be automatically dropped when it goes out of scope. + /// This function is equivalent to calling [`drop`] on the guard, except that + /// it returns the key that was used to create it. Alternatively, the guard + /// will be automatically dropped when it goes out of scope. /// /// # Examples /// @@ -571,6 +586,9 @@ impl RwLock { /// let mut guard = lock.write(key); /// *guard += 20; /// let key = RwLock::unlock_write(guard); + /// + /// let guard = lock.read(key); + /// assert_eq!(*guard, 20); /// ``` #[must_use] pub fn unlock_write(guard: RwLockWriteGuard<'_, T, R>) -> ThreadKey { -- cgit v1.2.3