feat(rwlock): add an upgradable readers-writer lock

CHANGELOG.md

@@ -23,6 +23,10 @@ All notable changes to this project will be documented in this file.
 
 ## Unreleased
 
+### New features
+
+* Add `rwlock::UpgradableRwLock` with a single upgradable reader, atomic upgrade and downgrade, and cancellation that releases a pending upgrade's guard; writers and upgradable readers share a FIFO reservation while ordinary readers use the data-permit queue.
+
 ### Improvements
 
 * Reduce the cost of polling a pending oneshot receive again from the same task, which now keeps its registered waker instead of cloning and dropping it.

README.md

@@ -81,33 +81,34 @@ Runnable examples live in the [`examples`](examples) workspace crate. They demon
 
 ## API map
 
-| Area                 | API                                                                                            | Feature        | Use                                                                                                             |
-|----------------------|------------------------------------------------------------------------------------------------|----------------|-----------------------------------------------------------------------------------------------------------------|
-| Locks and conditions | [`Mutex`](https://docs.rs/asyncband/*/asyncband/mutex/struct.Mutex.html)                       | `mutex`        | Protect shared data with asynchronous mutual exclusion.                                                         |
-|                      | [`RwLock`](https://docs.rs/asyncband/*/asyncband/rwlock/struct.RwLock.html)                    | `rwlock`       | Allow multiple readers or one writer.                                                                           |
-|                      | [`Condvar`](https://docs.rs/asyncband/*/asyncband/condvar/struct.Condvar.html)                 | `condvar`      | Wait for notifications while releasing a mutex.                                                                 |
-| Coordination         | [`Semaphore`](https://docs.rs/asyncband/*/asyncband/semaphore/struct.Semaphore.html)           | `semaphore`    | Limit concurrent work by acquiring permits.                                                                     |
-|                      | [`Barrier`](https://docs.rs/asyncband/*/asyncband/barrier/struct.Barrier.html)                 | `barrier`      | Synchronize a fixed number of participants at a reusable rendezvous.                                            |
-|                      | [`ManualResetEvent`](https://docs.rs/asyncband/*/asyncband/event/struct.ManualResetEvent.html) | `event`        | Signal current and future waits until explicitly reset.                                                         |
-|                      | [`AutoResetEvent`](https://docs.rs/asyncband/*/asyncband/event/struct.AutoResetEvent.html)     | `event`        | Retain one signal and release one waiter per consumed signal.                                                   |
-|                      | [`Latch`](https://docs.rs/asyncband/*/asyncband/latch/struct.Latch.html)                       | `latch`        | Wait until a fixed one-way countdown reaches zero.                                                              |
-|                      | [`Phaser`](https://docs.rs/asyncband/*/asyncband/phaser/struct.Phaser.html)                    | `phaser`       | Coordinate repeated phases with a dynamic participant set.                                                      |
-|                      | [`WaitGroup`](https://docs.rs/asyncband/*/asyncband/waitgroup/struct.WaitGroup.html)           | `waitgroup`    | Dynamically register participants and wait until all have completed.                                            |
-|                      | [`Shutdown`](https://docs.rs/asyncband/*/asyncband/shutdown/struct.Shutdown.html)              | `shutdown`     | Request shutdown and wait until all completion guards are dropped.                                              |
-| Work coalescing      | [`Once`](https://docs.rs/asyncband/*/asyncband/once/struct.Once.html)                          | `once`         | Complete one asynchronous initialization; cancelled or panicked attempts may be retried.                        |
-|                      | [`OnceCell`](https://docs.rs/asyncband/*/asyncband/once/struct.OnceCell.html)                  | `once-cell`    | Store one value from an access-time initializer; failed, cancelled, or panicked attempts may be retried.        |
-|                      | [`LazyCell`](https://docs.rs/asyncband/*/asyncband/once/struct.LazyCell.html)                  | `lazy-cell`    | Initialize one value with a stored function and resume the same in-flight future after caller cancellation.     |
-|                      | [`OnceMap`](https://docs.rs/asyncband/*/asyncband/once/struct.OnceMap.html)                    | `once-map`     | Coalesce work per key and retain each successful value until explicitly removed.                                |
-|                      | [`Group`](https://docs.rs/asyncband/*/asyncband/singleflight/struct.Group.html)                | `singleflight` | Coalesce overlapping work per key without retaining completed values.                                           |
-| Communication        | [`Completion`](https://docs.rs/asyncband/*/asyncband/completion/struct.Completion.html)        | `completion`   | Publish one shared result to any number of current and future observers.                                        |
-|                      | [`oneshot`](https://docs.rs/asyncband/*/asyncband/oneshot/)                                    | `oneshot`      | Send one value from one sender to one receiver.                                                                 |
-|                      | [`mpmc`](https://docs.rs/asyncband/*/asyncband/mpmc/)                                          | `mpmc`         | Distribute each value to exactly one of multiple competing receivers.                                           |
-|                      | [`mpsc`](https://docs.rs/asyncband/*/asyncband/mpsc/)                                          | `mpsc`         | Send each value from multiple producers to one receiver with bounded backpressure or an unbounded queue.        |
-|                      | [`spmc`](https://docs.rs/asyncband/*/asyncband/spmc/)                                          | `spmc`         | Distribute work from one exclusive sender to multiple competing receivers, with bounded or unbounded storage.   |
-|                      | [`broadcast`](https://docs.rs/asyncband/*/asyncband/broadcast/)                                | `broadcast`    | Deliver every value to active receivers with bounded backpressure or unbounded retention.                       |
-|                      | [`watch`](https://docs.rs/asyncband/*/asyncband/watch/)                                        | `watch`        | Publish cloneable latest state from one or more senders; receivers independently coalesce intermediate updates. |
-| Object reuse         | [`pool`](https://docs.rs/asyncband/*/asyncband/pool/)                                          | `pool`         | Reuse objects through bounded or unbounded pool variants.                                                       |
-| Sync interop         | [`FutureExt`](https://docs.rs/asyncband/*/asyncband/blocking/trait.FutureExt.html)             | `blocking`     | Drive one runtime-agnostic future from a blocking thread.                                                       |
+| Area                 | API                                                                                             | Feature        | Use                                                                                                             |
+|----------------------|-------------------------------------------------------------------------------------------------|----------------|-----------------------------------------------------------------------------------------------------------------|
+| Locks and conditions | [`Mutex`](https://docs.rs/asyncband/*/asyncband/mutex/struct.Mutex.html)                        | `mutex`        | Protect shared data with asynchronous mutual exclusion.                                                         |
+|                      | [`RwLock`](https://docs.rs/asyncband/*/asyncband/rwlock/struct.RwLock.html)                     | `rwlock`       | Allow multiple readers or one writer.                                                                           |
+|                      | [`UpgradableRwLock`](https://docs.rs/asyncband/*/asyncband/rwlock/struct.UpgradableRwLock.html) | `rwlock`       | Allow multiple readers or one writer, with one upgradable reader.                                               |
+|                      | [`Condvar`](https://docs.rs/asyncband/*/asyncband/condvar/struct.Condvar.html)                  | `condvar`      | Wait for notifications while releasing a mutex.                                                                 |
+| Coordination         | [`Semaphore`](https://docs.rs/asyncband/*/asyncband/semaphore/struct.Semaphore.html)            | `semaphore`    | Limit concurrent work by acquiring permits.                                                                     |
+|                      | [`Barrier`](https://docs.rs/asyncband/*/asyncband/barrier/struct.Barrier.html)                  | `barrier`      | Synchronize a fixed number of participants at a reusable rendezvous.                                            |
+|                      | [`ManualResetEvent`](https://docs.rs/asyncband/*/asyncband/event/struct.ManualResetEvent.html)  | `event`        | Signal current and future waits until explicitly reset.                                                         |
+|                      | [`AutoResetEvent`](https://docs.rs/asyncband/*/asyncband/event/struct.AutoResetEvent.html)      | `event`        | Retain one signal and release one waiter per consumed signal.                                                   |
+|                      | [`Latch`](https://docs.rs/asyncband/*/asyncband/latch/struct.Latch.html)                        | `latch`        | Wait until a fixed one-way countdown reaches zero.                                                              |
+|                      | [`Phaser`](https://docs.rs/asyncband/*/asyncband/phaser/struct.Phaser.html)                     | `phaser`       | Coordinate repeated phases with a dynamic participant set.                                                      |
+|                      | [`WaitGroup`](https://docs.rs/asyncband/*/asyncband/waitgroup/struct.WaitGroup.html)            | `waitgroup`    | Dynamically register participants and wait until all have completed.                                            |
+|                      | [`Shutdown`](https://docs.rs/asyncband/*/asyncband/shutdown/struct.Shutdown.html)               | `shutdown`     | Request shutdown and wait until all completion guards are dropped.                                              |
+| Work coalescing      | [`Once`](https://docs.rs/asyncband/*/asyncband/once/struct.Once.html)                           | `once`         | Complete one asynchronous initialization; cancelled or panicked attempts may be retried.                        |
+|                      | [`OnceCell`](https://docs.rs/asyncband/*/asyncband/once/struct.OnceCell.html)                   | `once-cell`    | Store one value from an access-time initializer; failed, cancelled, or panicked attempts may be retried.        |
+|                      | [`LazyCell`](https://docs.rs/asyncband/*/asyncband/once/struct.LazyCell.html)                   | `lazy-cell`    | Initialize one value with a stored function and resume the same in-flight future after caller cancellation.     |
+|                      | [`OnceMap`](https://docs.rs/asyncband/*/asyncband/once/struct.OnceMap.html)                     | `once-map`     | Coalesce work per key and retain each successful value until explicitly removed.                                |
+|                      | [`Group`](https://docs.rs/asyncband/*/asyncband/singleflight/struct.Group.html)                 | `singleflight` | Coalesce overlapping work per key without retaining completed values.                                           |
+| Communication        | [`Completion`](https://docs.rs/asyncband/*/asyncband/completion/struct.Completion.html)         | `completion`   | Publish one shared result to any number of current and future observers.                                        |
+|                      | [`oneshot`](https://docs.rs/asyncband/*/asyncband/oneshot/)                                     | `oneshot`      | Send one value from one sender to one receiver.                                                                 |
+|                      | [`mpmc`](https://docs.rs/asyncband/*/asyncband/mpmc/)                                           | `mpmc`         | Distribute each value to exactly one of multiple competing receivers.                                           |
+|                      | [`mpsc`](https://docs.rs/asyncband/*/asyncband/mpsc/)                                           | `mpsc`         | Send each value from multiple producers to one receiver with bounded backpressure or an unbounded queue.        |
+|                      | [`spmc`](https://docs.rs/asyncband/*/asyncband/spmc/)                                           | `spmc`         | Distribute work from one exclusive sender to multiple competing receivers, with bounded or unbounded storage.   |
+|                      | [`broadcast`](https://docs.rs/asyncband/*/asyncband/broadcast/)                                 | `broadcast`    | Deliver every value to active receivers with bounded backpressure or unbounded retention.                       |
+|                      | [`watch`](https://docs.rs/asyncband/*/asyncband/watch/)                                         | `watch`        | Publish cloneable latest state from one or more senders; receivers independently coalesce intermediate updates. |
+| Object reuse         | [`pool`](https://docs.rs/asyncband/*/asyncband/pool/)                                           | `pool`         | Reuse objects through bounded or unbounded pool variants.                                                       |
+| Sync interop         | [`FutureExt`](https://docs.rs/asyncband/*/asyncband/blocking/trait.FutureExt.html)              | `blocking`     | Drive one runtime-agnostic future from a blocking thread.                                                       |
 
 ## Synchronous interoperability