sync: update RwLock doc to mention possibility of deadlock (#3389)

tokio/src/sync/rwlock.rs

@@ -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