sync: update RwLock doc to mention possibility of deadlock
@@ -245,7 +245,7 @@ impl<'a, T: ?Sized> RwLockWriteGuard<'a, T> {
/// locks, since [`RwLock`] is fair and it is possible that a writer is next
/// in line.
///
- /// Returns an RAII guard which will drop the read access of this rwlock
+ /// Returns an RAII guard which will drop this read access of the `RwLock`
/// when dropped.
///
/// # Examples
@@ -398,12 +398,20 @@ impl<T: ?Sized> RwLock<T> {
}
}
- /// Locks this rwlock with shared read access, causing the current task
+ /// Locks this `RwLock` with shared read access, causing the current task
/// to yield until the lock has been acquired.
///
- /// The calling task will yield until there are no more writers which
- /// hold the lock. There may be other readers currently inside the lock when
- /// this method returns.
+ /// The calling task will yield until there are no writers which hold the
+ /// lock. There may be other readers inside the lock when the task resumes.
+ ///
+ /// Note that under the priority policy of [`RwLock`], read locks are not
+ /// granted until prior write locks, to prevent starvation. Therefore
+ /// deadlock may occur if a read lock is held by the current task, a write
+ /// lock attempt is made, and then a subsequent read lock attempt is made
+ /// by the current task.
+ ///
+ /// Returns an RAII guard which will drop this read access of the `RwLock`
+ /// when dropped.
///
/// # Examples
///
@@ -429,6 +437,7 @@ impl<T: ?Sized> RwLock<T> {
/// drop(n);
///}
/// ```
+ ///
pub async fn read(&self) -> RwLockReadGuard<'_, T> {
self.s.acquire(1).await.unwrap_or_else(|_| {
// The semaphore was closed. but, we never explicitly close it, and we have a
@@ -488,13 +497,13 @@ impl<T: ?Sized> RwLock<T> {
})
}
- /// Locks this rwlock with exclusive write access, causing the current task
- /// to yield until the lock has been acquired.
+ /// Locks this `RwLock` with exclusive write access, causing the current
+ /// task to yield until the lock has been acquired.
///
- /// This function will not return while other writers or other readers
+ /// The calling task will yield while other writers or readers
/// currently have access to the lock.
///
- /// Returns an RAII guard which will drop the write access of this rwlock
+ /// Returns an RAII guard which will drop the write access of this `RwLock`
/// when dropped.
///
/// # Examples
