diff options
| author | Taylor Yu <tlyu@mit.edu> | 2021-05-20 17:15:39 -0500 |
|---|---|---|
| committer | Taylor Yu <tlyu@mit.edu> | 2021-05-20 17:36:48 -0500 |
| commit | e5873660fc872f92e904bac385645750eb4f84c4 (patch) | |
| tree | 58c55d249dcfe966ded023ff9b73263e1ebd85c3 | |
| parent | 99e3aef02079e9c10583638520cd0c134dc3a01d (diff) | |
| download | rust-e5873660fc872f92e904bac385645750eb4f84c4.tar.gz rust-e5873660fc872f92e904bac385645750eb4f84c4.zip | |
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.
| -rw-r--r-- | library/std/src/sync/mutex.rs | 10 | ||||
| -rw-r--r-- | 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 773ab18b2ce..5ebb87792f2 100644 --- a/library/std/src/sync/mutex.rs +++ b/library/std/src/sync/mutex.rs @@ -294,8 +294,14 @@ impl<T: ?Sized> Mutex<T> { /// # 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 b01bcec1361..161d2789c27 100644 --- a/library/std/src/sync/rwlock.rs +++ b/library/std/src/sync/rwlock.rs @@ -199,11 +199,17 @@ impl<T: ?Sized> RwLock<T> { /// /// # 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<T: ?Sized> RwLock<T> { /// /// # 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 /// |