[Kaileshwar16]

Closes #169.

Add UpgradableRwLock with ordinary readers, exclusive writers, and one upgradable
reader. Support asynchronous upgrade, guard-preserving try_upgrade(), and downgrade to
an ordinary reader.

Cancelling a pending upgrade releases the consumed guard and its permits. Include rustdoc
examples and deterministic tests for ordering, cancellation, reader limits, cross-thread
visibility, and guard traits.

Design Notes

Reuse the existing RwLock and semaphore implementation. Writers and upgradable readers
acquire a FIFO reservation before requesting data permits, preventing an upgrade from
queuing behind a writer waiting for the upgrader’s read permit.

Ordering is FIFO within each queue, rather than globally: ordinary readers can pass
writers waiting for the reservation. Existing RwLock behavior remains unchanged.

Validation:

• cargo x lint and cargo x check passed.
• cargo x test: 625 passed.
• cargo x miri: 194 passed, 10 existing skips.
• All 24 feature tests passed 20 repetitions and four Miri seeds.

This is an initial implementation intended to help settle the API design in #169. I'd especially appreciate feedback on the two-queue fairness model, cancellation semantics for a pending upgrade, and whether borrowed guards are sufficient for the first version. I'm happy to adjust the design based on maintainer feedback.

[orthur2]

Thanks for taking this on. The reservation protocol and the cancellation paths look sound to me.

On the borrowed guards question, I think they’re fine for a first version. The existing owned guards hold an Arc<RwLock>, which we can’t get by projecting an Arc<UpgradableRwLock>, so owned support couldn’t reuse them as they are.

Please also add UpgradableRwLock to the API map in lib.rs and README.

[orthur2]

Thanks, looks good to me now.