skip to content

In Rust, when does replacing a `Mutex` with `std::sync::RwLock` actually help, and what does std promise about waiting writers and a thread calling `read()` twice?

level: seniorimportance: should knowfreq 45%

answer

  1. many readers or one writer
  2. read-mostly and long reads
  3. T: Send + Sync for Sync
  4. priority policy is platform-defined
  5. a queued writer blocks readers

basics

~20 s

RwLock helps only for read-mostly data with substantial read sections, and it needs T: Send + Sync. std promises no priority policy, so a waiting writer may block new readers, and a second read() on the same thread can deadlock.

solid answer

~40 s

`RwLock<T>` lets many `RwLockReadGuard`s coexist or one `RwLockWriteGuard`, so it helps only when reads dominate and each read does real work; for per-request counters, where every access writes, a `Mutex` is just as good. It is `Sync` only when `T: Send + Sync`, unlike `Mutex<T>`'s `T: Send`. std's docs say the priority policy depends on the OS: a writer waiting in `write()` might or might not block new `read()` calls, so correct code relies on neither policy: no recursive reads, and no assumption that writers get through promptly. If a writer queues between a thread's two `read()` calls, the second one can deadlock. There is no read-to-write upgrade; drop the read guard, take `write()` and recheck. `RwLockWriteGuard::downgrade`, stable since Rust 1.92, goes the other way safely.

code

rust · 35 lines
rust
use std::collections::HashMap;
use std::sync::{Arc, RwLock};
use std::thread;

struct Limits {
    per_minute: HashMap<String, u32>,
}

fn table(free: u32) -> Arc<Limits> {
    Arc::new(Limits { per_minute: HashMap::from([("free".into(), free), ("pro".into(), 600)]) })
}

fn main() {
    let limits = Arc::new(RwLock::new(table(60)));

    let readers: Vec<_> = (0..4)
        .map(|_| {
            let limits = Arc::clone(&limits);
            thread::spawn(move || {
                // Hold the read guard only long enough to clone the inner Arc.
                let snapshot: Arc<Limits> = Arc::clone(&*limits.read().unwrap());
                snapshot.per_minute["free"]
            })
        })
        .collect();

    // An admin reload swaps the whole table under a brief write lock.
    *limits.write().unwrap() = table(30);

    for r in readers {
        let v = r.join().unwrap();
        assert!(v == 60 || v == 30);
    }
    println!("free tier now {}", limits.read().unwrap().per_minute["free"]);
}

go deeper

for a junior

Recall that RwLock allows many readers or one writer, with read() and write() returning different guards.

for a middle

Explain why RwLock needs T: Send + Sync, why write-heavy data gains nothing from it, and why std offers no upgrade from read to write.

for a senior

Show you know std leaves the priority policy to the platform, can explain the recursive-read deadlock with a queued writer, and use the Arc-snapshot pattern to keep read sections short.

for a principal

Decide when a read-mostly structure deserves an RwLock, an Arc snapshot swap or parking_lot's documented fairness, based on measured read and write rates.

## What `RwLock` changes `std::sync::RwLock<T>` allows **many readers or one writer** at a time. `read()` returns a `RwLockReadGuard` that derefs to `&T`, and several of those may exist at once; `write()` returns a `RwLockWriteGuard` that derefs to `&mut T` and excludes everyone else. A `Mutex` makes no such distinction: every access is exclusive. For a rate limiter, two pieces of state look alike but are not: - The **per-client counters** change on every request. Every access is a write, so an `RwLock` buys nothing over a `Mutex`. - The **limits table** (requests per minute per tier) is read by every request and replaced only when an operator reloads the config. That is the read-mostly shape where an `RwLock` can help. ## When it actually helps An `RwLock` pays off only when all of these hold: 1. Reads vastly outnumber writes. 2. Read critical sections are long enough that running them in parallel matters. 3. There are enough cores reading at once for the parallelism to show. A reader still updates the lock's internal state on every `read()` and on every guard drop, so very short read sections on many cores contend on that shared word much as a `Mutex` would. Before switching, measure: compare lock wait time and throughput with the real read-to-write ratio, because a swap that looks obviously better on paper often changes nothing. The pattern in the example sidesteps most of this: the lock holds an `Arc<Limits>`, a reader clones the `Arc` and drops the read guard at once, and a reload swaps in a new `Arc` under a brief write lock. ## The stricter `Sync` bound std implements `Sync` for `RwLock<T>` only when `T: Send + Sync`, while `Mutex<T>` needs only `T: Send`. The reason is that several readers share `&T` at the same moment, so `T` must tolerate shared access from many threads. Wrapping a `Cell<u32>` shows the difference: `Arc<Mutex<Cell<u32>>>` moves into `thread::spawn`, while `Arc<RwLock<Cell<u32>>>` fails with E0277: ```plaintext error[E0277]: `Cell<u32>` cannot be shared between threads safely = note: required for `std::sync::RwLock<Cell<u32>>` to implement `Sync` ``` ## What std promises about writers The std docs say the priority policy **depends on the operating system's implementation**, and the type does not guarantee any particular policy. In particular, a writer waiting in `write()` *might or might not* block concurrent calls to `read()`. | Policy | Risk | |---|---| | Reader-preferring | a steady stream of readers can starve a writer indefinitely | | Writer-preferring | a queued writer blocks new readers, so a second `read()` on one thread can deadlock | | Unspecified (std's contract) | code must be correct under both | In the 1.99.1 source, the futex-based implementation (Linux, Windows and others) refuses new readers while a writer waits, and the queue-based one (macOS and other Unix targets) describes itself as writer-preferring, "even if some readers may still slip through". That is an implementation detail, not a promise — but it means the deadlock below is real today. ## Recursive reads and upgrades The std docs give the hazard directly: thread 1 holds a read guard, thread 2 blocks in `write()`, and thread 1 calls `read()` again — that second read **may deadlock**, because the queued writer can block it while the writer itself waits for thread 1. Related rules: - std's docs also say `read()` and `write()` might panic when the current thread already holds the lock, so a recursive call may fail loudly rather than hang. - Calling `write()` while the same thread holds a read guard never succeeds: `write()` does not return while any reader, this thread included, has access, and it may panic instead. - std has **no upgrade** from read to write. Drop the read guard, take `write()`, and recheck the condition, because another writer may have run in between. - Going the other way is safe: `RwLockWriteGuard::downgrade`, stable since **Rust 1.92**, turns a write guard into a read guard atomically, with no window for another writer. - Poisoning differs too: only a panic while holding the **write** guard poisons an `RwLock`. `parking_lot::RwLock` makes different choices: a documented task-fair policy, an `upgradable_read()` guard that can be upgraded, and a `read_recursive()` method for the recursive case. With either lock, a thread that holds a read guard and then calls `write()` cannot proceed.

  • A thread holds a `std::sync::RwLock` read guard, finds an entry missing and wants to insert it; what is the correct sequence?
    Drop the read guard, call `write()`, and check again whether the entry is still missing before inserting, because another writer may have inserted it in the gap. std has no atomic upgrade, and calling `write()` while still holding the read guard on the same thread never succeeds. When the write path is common, a `Mutex` or the entry API under one write lock is simpler.
  • Why does a `RwLock<Arc<Config>>` often beat a `RwLock<Config>` for a hot read path?
    With `RwLock<Arc<Config>>` a reader holds the read guard only long enough to clone the `Arc`, then works on its snapshot unlocked, so writers wait only for those brief clones. With `RwLock<Config>` every reader holds the guard for its whole lookup, and a reload must wait for all of them. The price is that a reader may finish on the old snapshot.

  • Switching any contended Mutex to an RwLock always improves throughput
  • std's RwLock guarantees writers are never starved
  • A thread can always take read() twice because read guards are shared
  • std's RwLock can upgrade a read guard to a write guard in place
  • RwLock<T> has the same Send and Sync bounds as Mutex<T>

Assumes Rust 1.99; RwLockWriteGuard::downgrade is stable since 1.92, and the writer-preferring behaviour described is the 1.99.1 implementation, not a documented guarantee.