From e5873660fc872f92e904bac385645750eb4f84c4 Mon Sep 17 00:00:00 2001 From: Taylor Yu Date: Thu, 20 May 2021 17:15:39 -0500 Subject: [PATCH 1/2] doc: clarify Mutex::try_lock, etc. errors Clarify error returns from Mutex::try_lock, RwLock::try_read, RwLock::try_write to make it more obvious that both poisoning and the lock being already locked are possible errors. --- library/std/src/sync/mutex.rs | 10 ++++++++-- library/std/src/sync/rwlock.rs | 27 ++++++++++++++++++++------- 2 files changed, 28 insertions(+), 9 deletions(-) diff --git a/library/std/src/sync/mutex.rs b/library/std/src/sync/mutex.rs index 773ab18b2ce65..5ebb87792f2a2 100644 --- a/library/std/src/sync/mutex.rs +++ b/library/std/src/sync/mutex.rs @@ -294,8 +294,14 @@ impl Mutex { /// # Errors /// /// If another user of this mutex panicked while holding the mutex, then - /// this call will return an error if the mutex would otherwise be - /// acquired. + /// this call will return the error [`Poisoned`] if the mutex would + /// otherwise be acquired. + /// + /// If the mutex could not be acquired because it is already locked, then + /// this call will return [`WouldBlock`]. + /// + /// [`Poisoned`]: TryLockError::Poisoned + /// [`WouldBlock`]: TryLockError::WouldBlock /// /// # Examples /// diff --git a/library/std/src/sync/rwlock.rs b/library/std/src/sync/rwlock.rs index b01bcec1361d7..161d2789c27ef 100644 --- a/library/std/src/sync/rwlock.rs +++ b/library/std/src/sync/rwlock.rs @@ -199,11 +199,17 @@ impl RwLock { /// /// # Errors /// - /// This function will return an error if the RwLock is poisoned. An RwLock - /// is poisoned whenever a writer panics while holding an exclusive lock. An - /// error will only be returned if the lock would have otherwise been + /// This function will return the error [`Poisoned`] if the RwLock is poisoned. + /// An RwLock is poisoned whenever a writer panics while holding an exclusive + /// lock. `Poisoned` will only be returned if the lock would have otherwise been /// acquired. /// + /// This function will return the error [`WouldBlock`] if the RwLock could not + /// be acquired because it was already locked exclusively. + /// + /// [`Poisoned`]: TryLockError::Poisoned + /// [`WouldBlock`]: TryLockError::WouldBlock + /// /// # Examples /// /// ``` @@ -281,10 +287,17 @@ impl RwLock { /// /// # Errors /// - /// This function will return an error if the RwLock is poisoned. An RwLock - /// is poisoned whenever a writer panics while holding an exclusive lock. An - /// error will only be returned if the lock would have otherwise been - /// acquired. + /// This function will return the error [`Poisoned`] if the RwLock is + /// poisoned. An RwLock is poisoned whenever a writer panics while holding + /// an exclusive lock. `Poisoned` will only be returned if the lock would have + /// otherwise been acquired. + /// + /// This function will return the error [`WouldBlock`] if the RwLock could not + /// be acquired because it was already locked exclusively. + /// + /// [`Poisoned`]: TryLockError::Poisoned + /// [`WouldBlock`]: TryLockError::WouldBlock + /// /// /// # Examples /// From 0e4f8cb661f66be0d02961d25b8f30d2b13c7af9 Mon Sep 17 00:00:00 2001 From: Taylor Yu Date: Mon, 24 May 2021 09:24:35 -0500 Subject: [PATCH 2/2] minor rewording after review Use "the `WouldBlock` error" instead of "the error `WouldBlock`", etc. --- library/std/src/sync/mutex.rs | 4 ++-- library/std/src/sync/rwlock.rs | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/library/std/src/sync/mutex.rs b/library/std/src/sync/mutex.rs index 5ebb87792f2a2..e7c5479ab9bb6 100644 --- a/library/std/src/sync/mutex.rs +++ b/library/std/src/sync/mutex.rs @@ -294,11 +294,11 @@ impl Mutex { /// # Errors /// /// If another user of this mutex panicked while holding the mutex, then - /// this call will return the error [`Poisoned`] if the mutex would + /// this call will return the [`Poisoned`] error if the mutex would /// otherwise be acquired. /// /// If the mutex could not be acquired because it is already locked, then - /// this call will return [`WouldBlock`]. + /// this call will return the [`WouldBlock`] error. /// /// [`Poisoned`]: TryLockError::Poisoned /// [`WouldBlock`]: TryLockError::WouldBlock diff --git a/library/std/src/sync/rwlock.rs b/library/std/src/sync/rwlock.rs index 161d2789c27ef..9d521ab14cbf3 100644 --- a/library/std/src/sync/rwlock.rs +++ b/library/std/src/sync/rwlock.rs @@ -199,12 +199,12 @@ impl RwLock { /// /// # Errors /// - /// This function will return the error [`Poisoned`] if the RwLock is poisoned. + /// This function will return the [`Poisoned`] error if the RwLock is poisoned. /// An RwLock is poisoned whenever a writer panics while holding an exclusive /// lock. `Poisoned` will only be returned if the lock would have otherwise been /// acquired. /// - /// This function will return the error [`WouldBlock`] if the RwLock could not + /// This function will return the [`WouldBlock`] error if the RwLock could not /// be acquired because it was already locked exclusively. /// /// [`Poisoned`]: TryLockError::Poisoned @@ -287,12 +287,12 @@ impl RwLock { /// /// # Errors /// - /// This function will return the error [`Poisoned`] if the RwLock is + /// This function will return the [`Poisoned`] error if the RwLock is /// poisoned. An RwLock is poisoned whenever a writer panics while holding /// an exclusive lock. `Poisoned` will only be returned if the lock would have /// otherwise been acquired. /// - /// This function will return the error [`WouldBlock`] if the RwLock could not + /// This function will return the [`WouldBlock`] error if the RwLock could not /// be acquired because it was already locked exclusively. /// /// [`Poisoned`]: TryLockError::Poisoned