skip to content

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?

level: seniorimportance: should knowfreq 38%

answer

  1. same thread, same mutex, twice
  2. a precondition, not a feature
  3. recursive_mutex counts levels
  4. split locked and unlocked layers

basics

~20 s

Relocking 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
cpp
#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

for a junior

Know that a std::mutex cannot be locked twice by the same thread and that this usually hangs.

for a middle

Explain the precondition, what recursive_mutex allows and that each lock level needs its own unlock.

for a senior

Diagnose the self-deadlock from a stack trace and fix it by splitting public locking functions from private helpers.

for a principal

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.