feat(rwlock): Upgradeable RwLock + perf improvements in standard implementation

.github/workflows/ci.yml

@@ -103,20 +103,42 @@ jobs:
       - uses: swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
       - run: cargo x bench
 
+  loom:
+    name: Loom concurrency check
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    env:
+      RUSTUP_TOOLCHAIN: stable
+      RUSTFLAGS: --cfg loom
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Install stable toolchain
+        run: >-
+          rustup toolchain install stable
+          --profile minimal
+          --no-self-update
+      - uses: swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
+      - name: Explore modeled interleavings
+        run: >-
+          cargo test -p asyncband --lib --all-features loom_ --release
+          -- --test-threads=1
+
   required:
     name: Required
     runs-on: ubuntu-24.04
     if: ${{ always() }}
     needs:
       - benchmark
       - check
+      - loom
       - test
     steps:
       - name: Guardian
         run: |
           if [[ ! ( \
                  "${{ needs.benchmark.result }}" == "success" \
               && "${{ needs.check.result }}" == "success" \
+              && "${{ needs.loom.result }}" == "success" \
               && "${{ needs.test.result }}" == "success" \
               ) ]]; then
             echo "Required jobs haven't been completed successfully."

CHANGELOG.md

@@ -10,6 +10,7 @@ All notable changes to this project will be documented in this file.
 
 * Add an opt-in `asyncband::blocking::FutureExt` bridge with `block_on` and `wait_timeout` methods for waiting on runtime-agnostic futures from synchronous code.
 * Add opt-in bounded and unbounded runtime-agnostic object pools under `asyncband::pool`.
+* Add borrowed and owned upgradable read guards to `asyncband::rwlock::RwLock`, with atomic upgrade and downgrade operations.
 
 ### Breaking changes
 
@@ -28,4 +29,5 @@ All notable changes to this project will be documented in this file.
 
 ### Improvements
 
+* Replace `RwLock`'s semaphore-based coordination with a mode-aware scheduler that avoids locking the waiter queue on uncontended acquisition and release.
 * Remove the `slab` dependency in favor of a focused internal waiter arena.

Cargo.toml

@@ -38,6 +38,7 @@ hashbrown = { version = "0.17.1", default-features = false }
 cargo_metadata = { version = "0.23.1" }
 clap = { version = "4.6.5" }
 divan = { version = "0.1.21" }
+loom = { version = "0.7.2", features = ["futures"] }
 pollster = { version = "1.0.1" }
 semver = { version = "1.0.28" }
 serde = { version = "1.0.229" }
@@ -47,6 +48,7 @@ ureq = { version = "3.3.0", default-features = false }
 which = { version = "8.0.5" }
 
 [workspace.lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = ["cfg(loom)"] }
 unknown_lints = "deny"
 
 [workspace.lints.clippy]

README.md

@@ -61,7 +61,7 @@ Public paths stay direct—such as `asyncband::mutex`, `asyncband::pool`, and `a
 | Area                    | API                                                                                  | Feature        | Use                                                                     |
 | ----------------------- | ------------------------------------------------------------------------------------ | -------------- | ----------------------------------------------------------------------- |
 | Shared state            | [`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.                                   |
+|                         | [`RwLock`](https://docs.rs/asyncband/*/asyncband/rwlock/struct.RwLock.html)          | `rwlock`       | Allow readers, a writer, or one atomically upgradable reader.            |
 |                         | [`Condvar`](https://docs.rs/asyncband/*/asyncband/condvar/struct.Condvar.html)       | `condvar`      | Wait for notifications while releasing a mutex.                         |
 | Initialization          | [`Once`](https://docs.rs/asyncband/*/asyncband/once/struct.Once.html)                | `once`         | Run asynchronous initialization exactly once.                           |
 |                         | [`OnceCell`](https://docs.rs/asyncband/*/asyncband/once/struct.OnceCell.html)        | `once-cell`    | Initialize and store one asynchronous value.                            |
@@ -113,6 +113,18 @@ The `blocking` module is a lightweight, thread-parking single-future executor, n
 
 Asyncband types implement `Send` and `Sync` only when the protected, transferred, or managed value satisfies the necessary bounds. See each API's documentation for its exact contract.
 
+### Loom model checking
+
+Asyncband uses bounded [Loom](https://github.com/tokio-rs/loom) models for concurrency-critical internals. During model checking, participating components conditionally replace their synchronization primitives with Loom's instrumented atomics, mutexes, threads, cells, and future executor. This allows focused models to explore relevant execution orderings.
+
+Run all current and future models separately from the normal test suite:
+
+```shell
+RUSTFLAGS="--cfg loom" cargo test -p asyncband --lib --all-features loom_ --release -- --test-threads=1
+```
+
+Models remain small and bounded so they are practical in CI. Set `LOOM_MAX_PREEMPTIONS` or `LOOM_MAX_BRANCHES` to request a deeper local run. Tests intended for the shared CI job use the `loom_` name prefix so models for additional primitives are discovered automatically.
+
 ## Minimum Supported Rust Version (MSRV)
 
 This crate is built against the latest stable release, and its minimum supported rustc version is 1.86.0.