skip to content

In Rust, why do request threads sharing a rate limiter's `HashMap` need `Arc<Mutex<HashMap<String, u32>>>` instead of a plain `Arc<HashMap<String, u32>>`?

level: juniorimportance: must knowfreq 80%

answer

  1. shared ownership vs exclusive access
  2. Arc derefs to &T only
  3. no DerefMut on Arc
  4. lock() hands out a MutexGuard
  5. Mutex<T> is Sync when T: Send

basics

~10 s

Arc only shares ownership: every thread gets a &HashMap, so insert fails with E0596. Mutex adds exclusive access: lock() turns &Mutex into a MutexGuard that derefs mutably and unlocks when dropped.

solid answer

~40 s

`Arc<T>` is an atomically reference-counted pointer: `Arc::clone` gives each thread its own owning handle, and the map is freed when the last handle drops. But `Arc` implements `Deref` and never `DerefMut`, so through it you only get `&HashMap`, and rustc rejects `insert` with E0596, "cannot borrow data in an `Arc` as mutable". `Mutex<T>` supplies the missing piece: `lock(&self)` blocks until this thread holds the lock and returns `LockResult<MutexGuard<'_, T>>`; the guard implements `DerefMut`, and dropping it unlocks. The bounds line up as well: `Mutex<T>` is `Sync` when `T: Send`, which makes `Arc<Mutex<T>>` `Send`, so it can move into `thread::spawn`. `Rc` would not do, because it is not `Send`.

code

rust · 23 lines
rust
use std::collections::HashMap;
use std::sync::{Arc, Mutex};
use std::thread;

fn main() {
    // client id -> requests seen in the current window
    let limiter: Arc<Mutex<HashMap<String, u32>>> = Arc::new(Mutex::new(HashMap::new()));
    let mut handles = Vec::new();
    for t in 0..4 {
        let limiter = Arc::clone(&limiter);
        handles.push(thread::spawn(move || {
            for _ in 0..25 {
                let mut map = limiter.lock().unwrap();
                *map.entry(format!("client-{}", t % 2)).or_insert(0) += 1;
            } // guard dropped here each iteration: the mutex unlocks
        }));
    }
    for h in handles {
        h.join().unwrap();
    }
    let map = limiter.lock().unwrap();
    println!("{:?} strong={}", map.get("client-0"), Arc::strong_count(&limiter));
}

go deeper

for a junior

Recall the split of jobs: Arc for shared ownership across threads, Mutex for one-at-a-time mutation, and the guard returned by lock() unlocking when it is dropped.

for a middle

Explain why Arc alone fails with E0596 (Deref but no DerefMut) and walk the Send and Sync chain that lets Arc<Mutex<T>> move into thread::spawn with only T: Send.

for a senior

Show you keep guards short-lived, know how to recover the value with Arc::try_unwrap and Mutex::into_inner, and recognise when a scoped thread, a static or an atomic removes the need for Arc.

for a principal

Frame Arc<Mutex<T>> as the correct starting point, then say what evidence, such as measured contention on one hot lock, would make you move to sharding or another structure.

## Two jobs, two types A rate limiter keyed by client id is a `HashMap<String, u32>` that every request thread reads **and** writes. Sharing it across threads needs two separate guarantees, and Rust gives each one its own type: - **Shared ownership** — several threads must keep the map alive, and nobody can know which thread finishes last. `Arc<T>` (atomically reference-counted) solves this: `Arc::clone` copies a pointer and increments an atomic strong count, and the map is dropped when the last handle goes. - **Exclusive access for writes** — two threads must never mutate the map at once. `std::sync::Mutex<T>` solves this: it owns the value and hands out mutable access to one thread at a time. Neither type does the other's job, which is why the idiom is the pair `Arc<Mutex<T>>`. | Type | What it adds | What you get through `&` | |---|---|---| | `Arc<HashMap<..>>` | shared ownership across threads | `&HashMap` only | | `Mutex<HashMap<..>>` | one-at-a-time access | `MutexGuard`, which derefs to `&mut HashMap` | | `Arc<Mutex<HashMap<..>>>` | both | every thread can lock and mutate | ## What rustc says without the Mutex `Arc<T>` implements `Deref` but not `DerefMut`. Any method that needs `&mut self`, such as `HashMap::insert`, is therefore unreachable through it, and rustc stops the build: ```plaintext error[E0596]: cannot borrow data in an `Arc` as mutable = help: trait `DerefMut` is required to modify through a dereference, but it is not implemented for `Arc<HashMap<String, u32>>` ``` This is the borrow rules doing their job: an `Arc` means many owners, and many owners may only share `&T`. The std docs say it plainly — `Arc` makes it thread-safe to have multiple ownership of the same data, but it does not add thread safety to the data itself. ## How `lock()` and the guard work `Mutex::lock(&self)` takes a **shared** reference, which is exactly what each thread has through its `Arc`. It blocks the calling thread until the lock is free and returns `LockResult<MutexGuard<'_, T>>`. The `Result` exists because of poisoning (a thread that panicked while holding the lock); most code calls `.unwrap()` on it. The `MutexGuard` is the only door to the data: 1. It implements `Deref` and `DerefMut`, so `map.entry(id).or_insert(0)` works on it like on the map. 2. It borrows the mutex, so the data cannot escape the critical section by reference. 3. When the guard is dropped — at the end of its scope or by `drop(guard)` — its `Drop` unlocks the mutex. std's `Mutex` has no `unlock` method at all. So a request handler is: clone the `Arc` into the thread, call `lock()`, update the count through the guard, and let the guard fall out of scope. ## Why the combination is `Send` `thread::spawn` requires its closure to be `Send + 'static`, so everything the closure captures must be `Send`. The bounds chain as follows, read from the std source: - `Mutex<T>` is `Send` and `Sync` whenever `T: Send` — it only ever gives `&mut T` to one thread at a time, so `T` does not need to be `Sync`. - `Arc<U>` is `Send` and `Sync` when `U: Send + Sync`. - `HashMap<String, u32>` is `Send`, so `Mutex<HashMap<..>>` is `Send + Sync`, so `Arc<Mutex<HashMap<..>>>` is `Send`. That is also why a `Mutex<Cell<u32>>` can be shared even though `Cell<u32>` is not `Sync`. ## Arc vs Rc, and when Arc is not needed `Rc` does the same shared-ownership job with non-atomic counts and is not `Send`, so rustc refuses to move it into `thread::spawn` (the material on `Rc` covers why). `Arc` pays for atomic increments and decrements, which is why the docs recommend `Rc` for single-threaded sharing. `Arc` is not mandatory for every threaded program, though: - With `std::thread::scope`, threads may borrow a local `Mutex` directly, because the scope joins them before the mutex goes away — covered with scoped threads. - A `static LIMITER: Mutex<..>` lives forever and needs no reference count. - A single counter with no map behind it is often an atomic integer rather than a lock — the subject of the atomics material. For a map shared by an open-ended set of request threads, `Arc<Mutex<HashMap<String, u32>>>` is the plain, correct default. ## Mistakes reviewers catch - **Slow work under the guard.** Formatting log lines, allocating keys or doing I/O while holding the guard makes every other request thread wait for it. - **Moving the only `Arc` into the first thread.** Clone before each `spawn` (`let limiter = Arc::clone(&limiter);`) so the closure moves the clone and the outer handle survives for the next thread. - **Locking the same mutex twice in one expression or scope.** std's `Mutex` is not reentrant; a second `lock()` on the thread that holds it never returns.

  • Once every worker has finished, how do you take the `HashMap` back out of the `Arc<Mutex<..>>` without cloning it?
    Join the threads so their clones drop, then `Arc::try_unwrap(limiter)` returns `Ok(mutex)` when the strong count is one, or gives the `Arc` back as `Err`. `Mutex::into_inner` then consumes the mutex and returns `LockResult<HashMap<..>>`, which is `Err` only if a thread panicked while holding the lock. No locking happens, because owning the mutex proves nobody else can touch it.
  • Does `Arc<Mutex<T>>` require `T: Sync`?
    No. std implements `Send` and `Sync` for `Mutex<T>` whenever `T: Send`, because the lock hands `&mut T` to one thread at a time. `Arc<U>` is `Send` when `U: Send + Sync`, and `Mutex<T>` meets both for any `T: Send`. That is why `Mutex<Cell<u32>>` can be shared although `Cell<u32>` is not `Sync`; `std::sync::RwLock<T>` is stricter and needs `T: Send + Sync`.
  • Why do many codebases write `Arc::clone(&limiter)` rather than `limiter.clone()`?
    Both call the same `Clone` impl: only the pointer is copied and the atomic strong count goes up by one. The fully qualified form is a readability convention that shows a reviewer no `HashMap` is being deep-copied, which `limiter.clone()` on an `Arc<Mutex<HashMap<..>>>` does not make obvious at a glance.

  • Arc makes whatever it wraps thread-safe, so an Arc<HashMap> can be mutated from threads
  • Arc<Mutex<T>> only works when T is both Send and Sync
  • You unlock a std Mutex by calling an unlock method when you are done
  • Cloning the Arc gives each thread its own copy of the HashMap
  • Rc<Mutex<T>> is fine across threads because the Mutex protects the count