Promise made by the std::sync::RwLock documentation contradicted on next line and by pthread

[yaksher]

Location

The relevant documentation page is: Struct std::sync::RwLock

The error is in the second paragraph (0 indexed or not counting the one line "A reader-writer lock" at the start, whichever makes you happier) on the final sentence: "An RwLock will allow any number of readers to acquire the lock as long as a writer is not holding the lock."

Summary

The line in question states that "the lock will allow any number of readers to acquire the lock as long as a writer is not holding the lock." This has one error I'm sure of, along with I believe a second error.

1. The following line states that "the priority policy of the lock is dependent on the underlying operating system" and that the lock can potentially block on a read request even if the lock is not held by a writer, as long as writer is waiting for the lock. One of these lines must be wrong, and given that I believe this issue implies that on some platforms, RwLock serves as wrapper for the pthread implementation which itself says that this policy is "implementation dependent", it appears that the former is wrong.

2. The line in question also states that "any number of readers..." which itself may be wrong in cases where RwLock serves as a pthread wrapper because the pthread standard states that "the maximum number of simultaneous read locks that an implementation guarantees can be applied to a read-write lock shall be implementation-defined" and certainly doesn't promise that it is unbounded.

[m-ou-se]

Yeah, you're right. That documentation should be clarified/corrected.

"An RwLock will allow any number of readers to acquire the lock as long as a writer is not holding the lock."

I think that sentence's only purpose was to explain the "multiple readers xor one writer" behaviour, but was accidentally written in a way that seems to imply more properties (unbounded readers, not prioritizing writers, ..) that an RwLock doesn't have or guarantee.