Wikipedia link to write-preferring in RwLock documentation is inconsistent with Tokio's definition

[lieuwex]

The RwLock documentation links to this Wikipedia section: https://en.wikipedia.org/wiki/Readers%E2%80%93writer_lock#Priority_policies.
Which says:

Write-preferring RW locks avoid the problem of writer starvation by preventing any new readers from acquiring the lock if there is a writer queued and waiting for the lock

However, the Tokio documentation says:

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.

If I am not mistaken, the difference is that Wikipedia says that if there is a writer anywhere in the queue no new readers can acquire the lock, while the Tokio documentation seems to say that only when the writer is at the head of the queue no new readers can acquire the lock.

[nurmohammed840]

This issue tracker is intended for bug reports and feature requests.
For general questions or discussions, we recommend joining our Discord community

The question seems unclear, But the parking_lot library provides helpful documentation on Fairness lock.

Documentation is inconsistent with Tokio's definition

Both versions of the documentation are correct, it just different variant of the lock, Some implementations offer fairness, some don't.

[lieuwex]

I don't have a question. I think Tokio's documentation is confusing.

The documentation of Tokio's RwLock says it is write-preferring and links to a Wikipedia article explaining what that means.
However, Tokio's implementation seems to use a different policy than Wikipedia does.
This is fine, but it might be confusing to people because both are mentioned as being true for Tokio's RwLock at the same time.

I think the documentations is clearer when the link to Wikipedia is removed.

it just different variant of the lock

Are you talking about Readers-Writer locks in general? Or is there a way in Tokio to switch priority policies?

[Darksonn]

Tokio's rwlock is using a write-preferring fairness policy. Whenever a writer tries to acquire the lock, it's guaranteed to get it eventually. This happens at the expense of readers, since a reader may fail to acquire the lock despite the lock being in use by other readers.

[lieuwex]

I agree that RwLock is write-preferring and I'm not claiming that Tokio's documentation (or the code, for that matter) is wrong — I just noticed that the Tokio's definition of write-preferring is different from Wikipedia's definition.
Specifically, the Wikipedia version is unfair, whereas Tokio's is fair.

If users click the link in Tokio's documentation, believing that it is appropriate for RwLock, they may get the (false) impression that Tokio's lock is unfair.

[Darksonn]

In my opinion, it makes more sense to update the wikipedia article than to remove the link from Tokio's docs.

[cip999]

Late to this party, but here are my two cents.

• I thinkg that the documentation of RwLock in Tokio reflects the implementation, except that the following is slighly inaccurate:

  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

  It's not wrong, but it's deceptive nonetheless, because the fact that the pending writer is first in the queue is irrelevant — all that matters is that it's queued ahead of the task that wants to read.

  Possible rephrasing: "A read lock won't be given out until all previously requested write locks have been released" (but open to alternatives of course).

• Wikipedia is indeed more confusing. My guess is that the author was trying to describe the same implementation, but the wording is inaccurate — especially "the writer will acquire the lock as soon as all readers which were already holding the lock have completed" (that doesn't include possible readers queued after a previous writer).

  I would even suggest to get rid of the link. It's not really adding much to what the documentation already says, and on the other hand the content could diverge even more in the future.