From e65040f061008ca5a94d21721aa8b544c078c606 Mon Sep 17 00:00:00 2001
From: Maxime Grenu <69890511+cluster2600@users.noreply.github.com>
Date: Thu, 19 Feb 2026 15:57:42 +0100
Subject: [PATCH] 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 | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/tokio/src/sync/rwlock.rs b/tokio/src/sync/rwlock.rs
index c8a35db2a..9bc0a1146 100644
--- a/tokio/src/sync/rwlock.rs
+++ b/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