A C++ inventory class hangs when one locked member function calls another that locks the same std::mutex; why, and is std::recursive_mutex the fix?
answer
- same thread, same mutex, twice
- a precondition, not a feature
- recursive_mutex counts levels
- split locked and unlocked layers
basics
~20 sRelocking a std::mutex the thread already owns breaks lock()'s precondition: undefined behaviour, usually a self-deadlock. std::recursive_mutex makes it legal, but the usual fix splits each operation into a locking public function and a private helper that assumes the lock.
solid answer
~40 s`std::mutex` is non-recursive: `lock()` requires that the calling thread does not own it. `add_pallet()` holding the lock and calling `add()`, which locks again, breaks that precondition. The behaviour is undefined, the standard's note says the program can deadlock, and on common implementations the thread blocks on itself forever. `std::recursive_mutex` lets the owning thread take additional levels of ownership, each matched by an `unlock()`, up to an unspecified maximum after which `lock()` throws `std::system_error`. It hides the design problem, though: the inner call runs on data the outer call may have left half-updated, the lock's extent becomes unclear, and it composes badly with `std::condition_variable`, which requires `std::unique_lock<std::mutex>`. The usual fix keeps `std::mutex` and splits the class: public members lock and call private `*_locked` helpers that assume the lock is held and never lock.
code
cpp · 30 lines#include <iostream>
#include <mutex>
class Bin {
std::mutex mu_;
int units_ = 0;
// Callers must already hold mu_; never locks.
void add_locked(int qty) { units_ += qty; }
public:
void add(int qty) {
std::lock_guard<std::mutex> lock(mu_);
add_locked(qty);
}
void add_pallet(int pallets) {
std::lock_guard<std::mutex> lock(mu_);
for (int i = 0; i < pallets; ++i)
add_locked(48); // calling add() here would lock mu_ again: UB
}
int units() {
std::lock_guard<std::mutex> lock(mu_);
return units_;
}
};
int main() {
Bin bin;
bin.add(2);
bin.add_pallet(3);
std::cout << "units " << bin.units() << '\n';
}go deeper
Know that a std::mutex cannot be locked twice by the same thread and that this usually hangs.
Explain the precondition, what recursive_mutex allows and that each lock level needs its own unlock.
Diagnose the self-deadlock from a stack trace and fix it by splitting public locking functions from private helpers.
Decide whether recursive mutexes are banned, tolerated in legacy code, or enforced against with thread-safety annotations.
## The symptom An `InventoryBin` class protects its count with a `std::mutex`. `add(qty)` locks and adds. Later someone writes `add_pallet(n)`, which locks, validates, and calls `add(48)` in a loop. The first call to `add_pallet` never returns; a stack dump shows the thread waiting inside `add`, on a mutex that it owns itself. ## Why std::mutex does this The standard's mutex requirements give `lock()`, for `std::mutex`, `std::timed_mutex`, `std::shared_mutex` and `std::shared_timed_mutex`, a **precondition**: the calling thread does not own the mutex. Violating a standard library precondition is **undefined behaviour**. A note on `std::mutex` spells out the likely result: the program can deadlock, and an implementation that detects it may report `resource_deadlock_would_occur`. Common implementations on top of a default operating-system mutex simply block the thread on itself. Debug builds and tools may report it; release builds hang. ## What std::recursive_mutex changes `std::recursive_mutex` lets the owning thread acquire **additional levels of ownership** by calling `lock()` or `try_lock()` again: - each `lock()` or successful `try_lock()` must be matched by one `unlock()`; - other threads can acquire it only when **all** levels are released; - the maximum number of levels is unspecified; past it, `try_lock()` fails and `lock()` throws `std::system_error`. `std::recursive_timed_mutex` adds `try_lock_for` and `try_lock_until`. So recursion makes the program legal. It does not make it good. ## Why recursive locking is usually a smell 1. **Broken invariants.** The outer function took the lock to make several changes atomically. When it calls back into a public function, that function assumes the invariants hold, but the outer one may be halfway through. 2. **Unclear lock extent.** Readers can no longer tell from a function's body whether it runs with the lock held, which makes future changes risky. 3. **Condition variables.** `std::condition_variable::wait` takes a `std::unique_lock<std::mutex>`, and with `std::condition_variable_any` a wait unlocks only one level of a recursive mutex, so a nested caller sleeps while still holding the lock. 4. **Hidden reentry from callbacks.** If a callback invoked under the lock calls back into the class, recursion silently permits it, where a non-recursive mutex would at least surface the design problem. ## The structural fix Separate **locking** from **work**: | Layer | Locks? | May call | |---|---|---| | public `add()`, `add_pallet()`, `units()` | yes, once, with `std::lock_guard` | private helpers only | | private `add_locked()` | never; documents that the caller holds `mu_` | other `*_locked` helpers | Public functions take the lock exactly once and do their work through helpers that never lock. Calls between public functions disappear, and the lock's extent is visible at a glance. Clang's thread-safety analysis (`-Wthread-safety`) can enforce the convention with annotations; when compiled with clang, libc++'s mutex types carry the capability attributes it needs. ## Where recursion sneaks in The direct case, one public member calling another, is easy to spot. The indirect ones are not: - an **observer or callback** invoked while the lock is held, whose handler queries the same object; - a **virtual hook** a derived class overrides to call a public member of the base; - a **logging or validation helper** that calls a public getter for a nicer message; - a **destructor** of an element removed under the lock that calls back into its container. Each turns into a self-deadlock with `std::mutex`. The general rule from the deadlock literature applies here concretely: do not call code you do not control while holding the lock. Collect the notifications under the lock, release it, then invoke the callbacks. ## When recursive_mutex is acceptable Legacy code with deep call graphs that cannot be restructured right away, or callback-heavy APIs where reentry is part of the contract, can justify `std::recursive_mutex` as a deliberate, documented choice. Treat it as a known debt: the invariants still have to be re-established before every call that could re-enter. ## Diagnosing a self-deadlock - A stack trace shows the waiting thread is also the owner of the mutex it waits on. - Some native mutexes record their owner, and a debugger then shows the waiting thread as the owner of the mutex it waits on. - A timed mutex with `try_lock_for` in a test build turns the hang into a reportable failure.
- How many times can a thread lock a std::recursive_mutex it already owns?The standard leaves the maximum number of ownership levels unspecified. Once a thread reaches it, further `try_lock()` calls fail and further `lock()` calls throw `std::system_error`. Each acquired level needs its own `unlock()`, and other threads get the mutex only after the last one.
- Why does a recursive mutex combine badly with condition variables?`std::condition_variable::wait` only takes `std::unique_lock<std::mutex>`, so it cannot be used with a recursive mutex at all. `std::condition_variable_any` can, but its wait unlocks the lock object once, so if the thread holds several levels it sleeps still owning the mutex and the notifier can never get in.
- How can the locked-helper convention be checked by tools?Clang's thread-safety analysis (`-Wthread-safety`) reads attributes, usually wrapped in macros such as `GUARDED_BY` on data and `REQUIRES` on helpers as in clang's documentation, and warns when guarded data or a helper is used without the lock, or a mutex is locked twice. libc++ annotates its mutex types for it when compiled with clang.
- Locking a std::mutex twice from the same thread is harmless; the second call returns immediately.
- The standard guarantees an exception when a thread relocks its own std::mutex.
- std::recursive_mutex releases the mutex after the first unlock() call.
- Switching to recursive_mutex fixes the design, not just the hang.
- std::recursive_mutex allows unlimited nesting depth.