sync: clarify RwLock fairness documentation (#7919)

The previous wording 'if a task that wishes to acquire the write lock is
at the head of the queue, read locks will not be given out' was
misleading: it implied that readers are only blocked when the writer is
first in the queue. In reality, due to the FIFO ordering, any write
request queued *before* a read request will block that reader.

Replace with a more accurate description: 'a read lock will not be given
out until all write lock requests that were queued before it have been
acquired and released.'

Closes #6901

tokio/src/sync/rwlock.rs

@@ -41,11 +41,10 @@ const MAX_READS: u32 = 10;
 /// The priority policy of Tokio's read-write lock is _fair_ (or
 /// [_write-preferring_]), in order to ensure that readers cannot starve
 /// writers. Fairness is ensured using a first-in, first-out queue for the tasks
-/// awaiting the lock; if a task that wishes to acquire the write lock is at the
-/// head of the queue, read locks will not be given out until the write lock has
-/// been released. This is in contrast to the Rust standard library's
-/// `std::sync::RwLock`, where the priority policy is dependent on the
-/// operating system's implementation.
+/// awaiting the lock; a read lock will not be given out until all write lock
+/// requests that were queued before it have been acquired and released. This is
+/// in contrast to the Rust standard library's `std::sync::RwLock`, where the
+/// priority policy is dependent on the operating system's implementation.
 ///
 /// The type parameter `T` represents the data that this lock protects. It is
 /// required that `T` satisfies [`Send`] to be shared across threads. The RAII guards