Write guard to read guard downgrading for sync::RwLock

[max-heller]

Motivation

The asynchronous sync::RwLock currently provides no way to atomically downgrade a write guard into a read guard, forcing a pattern of dropping the write guard and reacquiring a read guard to achieve a downgrade. In addition to being non-atomic, this makes it easy to accidentally induce a deadlock by forgetting to drop an existing read guard before attempting to acquire a write guard--this is particularly tricky and non-obvious when shadowing the name of the old read guard.

Solution

This implements an atomic downgrade operation by taking ownership of a write guard, releasing all but one of the permits it holds, and returning a read guard holding the remaining permit.

[hawkw]

Hmm, because Tokio's locks are fairly queued, if the next queued waiter is a writer, no additional waiters will be allowed access. I'm not sure if that behavior is actually an issue, or not, but it's worth noting.

[max-heller]

It's the same behavior as if the holder of the (to be downgraded) write guard had initially acquired a read guard instead. It might not always be ideal, but it's the behavior required to avoid starving writers. I'll add a note.

[hawkw]

looks good to me — @carllerche may want to sign off, since this adds a new public API function.

[Darksonn]

This has conflicted with #2615, #2445. Sorry about that. I will try to get Carl's attention.

[carllerche]

@hawkw I'm OK w/ this 👍 merge whenever it is ready.

[max-heller]

@hawkw rebased onto master and fixed things up