# Mutexes and locks

> A mutex turns a region of code into a critical section and creates happens-before between whoever unlocks and whoever locks next. This page covers the mutex kinds, the RAII lock wrappers, deadlock and std::lock, the undefined behavior that is easy to write, and one-time initialization.

- **Source:** C++ Atlas (https://cppatlas.com/topics/mutexes-and-locks)
- **Track:** Concurrency
- **Estimated reading time:** 13 minutes
- **ISO C++ clauses:** [thread.req.lockable] (https://eel.is/c++draft/thread.req.lockable), [thread.mutex.requirements] (https://eel.is/c++draft/thread.mutex.requirements), [thread.mutex.class] (https://eel.is/c++draft/thread.mutex.class), [thread.mutex.recursive] (https://eel.is/c++draft/thread.mutex.recursive), [thread.timedmutex.requirements] (https://eel.is/c++draft/thread.timedmutex.requirements), [thread.sharedmutex.requirements] (https://eel.is/c++draft/thread.sharedmutex.requirements), [thread.lock.guard] (https://eel.is/c++draft/thread.lock.guard), [thread.lock.scoped] (https://eel.is/c++draft/thread.lock.scoped), [thread.lock.unique] (https://eel.is/c++draft/thread.lock.unique), [thread.lock.shared] (https://eel.is/c++draft/thread.lock.shared), [thread.lock.algorithm] (https://eel.is/c++draft/thread.lock.algorithm), [thread.once.callonce] (https://eel.is/c++draft/thread.once.callonce), [stmt.dcl] (https://eel.is/c++draft/stmt.dcl)
- **cppreference links:** [std::mutex](https://en.cppreference.com/w/cpp/thread/mutex), [std::shared_mutex](https://en.cppreference.com/w/cpp/thread/shared_mutex), [Named requirements: Lockable](https://en.cppreference.com/w/cpp/named_req/Lockable), [std::scoped_lock](https://en.cppreference.com/w/cpp/thread/scoped_lock), [std::unique_lock](https://en.cppreference.com/w/cpp/thread/unique_lock), [std::lock](https://en.cppreference.com/w/cpp/thread/lock), [std::call_once](https://en.cppreference.com/w/cpp/thread/call_once), [Storage class specifiers (static local variables)](https://en.cppreference.com/w/cpp/language/storage_duration)
- **Prerequisites:** threads-and-jthread, atomics-and-memory-ordering, raii-and-resource-management

## The one idea

A mutex is a token that at most one thread holds at a time. Code that runs only while holding it is a critical section, and two critical sections guarded by the same mutex never overlap. That is the half everyone knows. The other half is ordering: every `lock` and `unlock` on a given mutex falls into one total order, and each `unlock` synchronizes with the next `lock` that acquires the mutex. So whatever a thread wrote before unlocking is visible to whoever locks after it. That is why plain, non-atomic data guarded consistently by one mutex has no data race. The definitions of data race and happens-before are in atomics-and-memory-ordering.

> **Mental model.** A mutex guards an invariant, not a variable. Lock, find the invariant true, break it briefly, restore it, unlock. Every access to the data the invariant covers, reads included, must hold the same mutex.

The rest is plumbing: which kind of mutex, which RAII wrapper, how to lock several without deadlock, and the handful of mistakes the standard declares undefined.

## The mutex family and the Lockable requirements

The library describes lockable things by named requirements rather than by a base class, so your own types can take part.

| Requirement | Operations | Examples |
|---|---|---|
| *Cpp17BasicLockable* | `lock`, `unlock` | anything `lock_guard` accepts |
| *Cpp17Lockable* | adds `try_lock` | what `std::lock` and a multi-mutex `scoped_lock` need |
| *Cpp17TimedLockable* | adds `try_lock_for`, `try_lock_until` | `timed_mutex` |

The standard mutex types build on those:

- `std::mutex` is the plain exclusive mutex. Its default constructor is `constexpr`, so a namespace-scope `std::mutex` is constant-initialized and has no static initialization order problem.
- `std::recursive_mutex` lets the owning thread lock again; it must unlock as many times as it locked. The maximum depth is unspecified, and exceeding it makes `lock` throw `std::system_error` and `try_lock` return false.
- `std::timed_mutex` and `std::recursive_timed_mutex` add timed attempts.
- `std::shared_timed_mutex` (C++14) and `std::shared_mutex` (C++17) add a shared mode: many threads may hold `lock_shared` at once, but `lock` excludes everyone. There is no upgrade from shared to exclusive, and the standard does not specify whether readers or writers get priority.

None of these is copyable or movable. A mutex is an identity; its address is what threads agree on.

One detail of `try_lock` surprises people: [thread.mutex.requirements.mutex] allows it to fail even when no other thread owns the mutex. A failed `try_lock` also does not synchronize with anything. Use it to avoid blocking, never to learn what another thread is doing.

```cpp
#include <map>
#include <mutex>
#include <shared_mutex>
#include <string>

class Registry {
  mutable std::shared_mutex m_;
  std::map<std::string, int> items_;
public:
  int find(const std::string& k) const {
    std::shared_lock lock(m_);   // many readers at once
    auto it = items_.find(k);
    return it == items_.end() ? -1 : it->second;
  }
  void set(const std::string& k, int v) {
    std::unique_lock lock(m_);   // one writer, and no readers
    items_[k] = v;
  }
};
```

## Lock wrappers: lock_guard, unique_lock, scoped_lock, shared_lock

Calling `lock` and `unlock` by hand is fragile, because an exception or early return between them leaves the mutex locked. The wrappers tie ownership to scope.

- `std::lock_guard<M>` locks in its constructor and unlocks in its destructor. It is neither copyable nor movable. The `std::adopt_lock` tag makes it take over a mutex the thread already holds.
- `std::scoped_lock<Ms...>` (C++17) is the variadic successor. With one mutex it behaves like `lock_guard`; with several it locks them all through the deadlock-avoiding `std::lock` algorithm.
- `std::unique_lock<M>` is movable and may or may not own the mutex at any moment. It accepts `std::defer_lock`, `std::try_to_lock`, `std::adopt_lock` and timeouts, and offers `lock`, `unlock`, `owns_lock` and `release`, which gives up the association *without* unlocking. It is the type `std::condition_variable` requires, and it costs a flag and a branch more than `lock_guard`.
- `std::shared_lock<M>` (C++14) is the shared-mode counterpart of `unique_lock`, calling `lock_shared` and `unlock_shared`.

`unique_lock` checks its own state. Calling `unlock` when it does not own the mutex throws `std::system_error` with `operation_not_permitted`, and calling `lock` when it already owns throws with `resource_deadlock_would_occur`.

> **Pitfall.** A lock wrapper must be a named variable. `std::scoped_lock{m};` creates a temporary that locks and unlocks within that one statement. `std::unique_lock<std::mutex>(m);` is worse: the parentheses are redundant declarator parentheses, so it declares a new, default-constructed `unique_lock` named `m` that owns nothing and shadows the mutex. Both compile, and both leave the code that follows unprotected. GCC's `-Wparentheses` and Clang's `-Wvexing-parse` catch the second form.

## Deadlock and std::lock

Deadlock needs a cycle: thread 1 holds A and waits for B, while thread 2 holds B and waits for A. The classic cure is a global lock order, so a cycle cannot form. When the order is not knowable, as when transferring between two accounts chosen at run time, `std::lock(m1, m2, ...)` locks any number of *Cpp17Lockable* objects without deadlock. The standard leaves its algorithm unspecified, saying only that it uses `lock`, `try_lock` and `unlock` and avoids deadlock. Typical implementations lock one mutex, `try_lock` the rest, and on failure release everything and retry, starting with the mutex that could not be taken. If an exception escapes, every mutex it had locked is unlocked again.

```cpp
#include <mutex>

struct Account {
  std::mutex m;
  long balance = 0;
};

void transfer(Account& from, Account& to, long amount) {
  // Two threads calling transfer(a, b) and transfer(b, a) cannot deadlock.
  std::scoped_lock lock(from.m, to.m);   // uses the std::lock algorithm
  from.balance -= amount;
  to.balance += amount;
}
```

Before C++17 the same thing took two steps: `std::lock(a, b)` followed by two `lock_guard`s with `std::adopt_lock`, or two `unique_lock`s with `std::defer_lock` passed to `std::lock`. `std::try_lock(m1, m2, ...)` is the non-blocking relative: it returns -1 if it locked everything, or the zero-based index of the first argument it failed to lock, having unlocked the rest.

Note that `std::lock` only prevents deadlock among the mutexes passed to one call. A thread that already holds some other mutex can still be part of a cycle.

## Undefined behavior you can write in one line

The mutex requirements are stated as preconditions, and breaking a precondition of a standard library function is undefined behavior. Four cases account for most real bugs.

- Locking a `std::mutex`, `timed_mutex`, `shared_mutex` or `shared_timed_mutex` that the calling thread already owns. Many implementations deadlock, and a note in [thread.mutex.class] says one that detects it might report `resource_deadlock_would_occur`, but the standard promises neither.
- Calling `unlock` from a thread that does not own the mutex. A mutex is not a semaphore, and there is no handing it to another thread to release.
- Destroying a mutex while any thread owns it.
- Letting a thread end while it owns a mutex.

```cpp
#include <mutex>

std::mutex m;

void helper() { std::lock_guard lk(m); /* ... */ }

void api() {
  std::lock_guard lk(m);
  helper();   // undefined behavior: m is a std::mutex and this thread owns it
}
```

> **Standardese.** [thread.mutex.requirements.mutex] makes "the calling thread does not own the mutex" a precondition of `lock` for the non-recursive types and "the calling thread owns the mutex" a precondition of `unlock`. [thread.mutex.class] separately says that the behavior is undefined if a program destroys a mutex owned by any thread, or if a thread terminates while owning one.

`std::recursive_mutex` makes the first case legal, but it usually hides a design problem: a function that is entered with the invariant already broken. Splitting the code into a public function that locks and a private one that assumes the lock is held is almost always cleaner.

## call_once and thread-safe statics

Lazy one-time initialization has two standard forms. The first is a block-scope static. Since C++11, if several threads reach the declaration at once, one initializes the variable and the rest wait for it to finish. If the initializer throws, the variable is not initialized, and the next thread to arrive tries again. Re-entering the declaration recursively while it is being initialized is undefined behavior. In testing for this page, the GCC 16 build hung, while the Clang build with libc++ aborted with a diagnostic.

```cpp
struct Config { int verbosity = 1; };

Config& config() {
  static Config c;   // initialized exactly once, thread-safe since C++11
  return c;
}
```

The second is `std::call_once` with a `std::once_flag`, for when the state is not a single static, for example a member of an object. All calls on one flag are ordered. The call that runs the callable and returns normally is a *returning* execution, and it synchronizes with every *passive* call that finds the work already done. If the callable throws, the execution is *exceptional*: the exception propagates to that caller, the flag stays unset, and a later call runs the callable again.

```cpp
#include <mutex>
#include <vector>

class Table {
  std::once_flag built_;
  std::vector<int> data_;
public:
  const std::vector<int>& get() {
    std::call_once(built_, [this] { data_.assign(1024, 0); });
    return data_;   // every caller sees the fully built vector
  }
};
```

## Granularity, and calling code you do not control

A mutex serializes everything it covers, so hold it for the shortest stretch that keeps the invariant intact. Prepare values before locking, and do slow work such as I/O and allocation-heavy formatting after unlocking. Splitting one big lock into several finer ones increases concurrency, but every extra mutex is another edge in the lock-order graph.

The most dangerous thing to do under a lock is to call code you did not write: a callback, a virtual function, a signal or observer list. That code might take a lock of its own, which creates a lock-order cycle you cannot see, or call back into your object and relock a non-recursive mutex. Copy what the callback needs while holding the lock, unlock, then call.

```cpp
#include <functional>
#include <mutex>
#include <vector>

class Notifier {
  std::mutex m_;
  std::vector<std::function<void(int)>> listeners_;
public:
  void publish(int v) {
    std::vector<std::function<void(int)>> copy;
    {
      std::lock_guard lk(m_);
      copy = listeners_;      // snapshot under the lock
    }
    for (auto& f : copy) f(v);   // unknown code runs with no lock held
  }
};
```

The same reasoning rules out returning a pointer or reference to guarded data from a locked accessor. Once the lock is released, the caller holds a path into the data that no mutex protects.

## What to remember

- Each `unlock` synchronizes with the next `lock` of the same mutex; that is what makes guarded non-atomic data race-free.
- Lockable types are defined by requirements: *BasicLockable* (`lock`, `unlock`), *Lockable* (adds `try_lock`), *TimedLockable* (adds timed tries).
- `try_lock` may fail spuriously, and a failed `try_lock` synchronizes with nothing.
- `std::mutex` has a `constexpr` constructor. Mutexes are neither copyable nor movable.
- Prefer `scoped_lock`; use `unique_lock` when you need to unlock early, move ownership, or wait on a condition variable; use `shared_lock` for readers.
- A lock wrapper that is a temporary, or a parenthesized declaration, protects nothing.
- `std::lock` and multi-mutex `scoped_lock` avoid deadlock among their arguments; the algorithm is unspecified.
- Relocking a non-recursive mutex, unlocking one you do not own, destroying one that is owned, and exiting a thread while owning one are all undefined behavior.
- Block-scope static initialization is thread-safe since C++11, retries after an exception, and is undefined if it recurses.
- `call_once` retries after an exceptional execution and synchronizes the returning execution with all passive calls.
- Never call unknown code while holding a lock. Snapshot, unlock, then call.

## Concept Map Outline

- **Mutexes and locks:** A mutex makes critical sections exclusive, and each unlock synchronizes with the next lock.
  - **Mutex kinds:** All are neither copyable nor movable; their identity is what threads agree on.
    - **std::mutex:** Plain exclusive mutex with a constexpr constructor, so globals are constant-initialized.
    - **recursive_mutex:** The owner may relock; unlock as many times; exceeding the unspecified depth throws.
    - **Timed mutexes:** timed_mutex and recursive_timed_mutex add try_lock_for and try_lock_until.
    - **Shared mutexes:** shared_mutex (C++17) allows many lock_shared holders or one exclusive owner; no upgrade.
    - **Spurious try_lock:** try_lock may fail on a free mutex, and a failed try_lock synchronizes with nothing.
  - **Lock wrappers:** RAII types that tie ownership to a scope, satisfying the Lockable requirements on the inside.
    - **lock_guard:** Locks in the constructor, unlocks in the destructor; not movable; adopt_lock takes over.
    - **scoped_lock (C++17):** Variadic; with several mutexes it uses the std::lock algorithm.
    - **unique_lock:** Movable, optional ownership, defer_lock and try_to_lock; required by condition_variable.
    - **shared_lock (C++14):** Calls lock_shared and unlock_shared, for readers of a shared mutex.
    - **Unnamed wrappers:** scoped_lock{m}; unlocks at once; unique_lock<mutex>(m); declares a new variable m.
  - **Deadlock:** A cycle of threads each holding a mutex the next one wants.
    - **Lock ordering:** A global acquisition order makes cycles impossible.
    - **std::lock:** Locks several Lockables without deadlock by an unspecified algorithm; unlocks all on exception.
    - **std::try_lock:** Returns -1 on success, or the zero-based index of the first mutex it could not lock.
  - **Undefined behavior:** Mutex rules are preconditions, so breaking them is undefined, not an error code.
    - **Relocking:** Locking a non-recursive mutex the thread already owns; deadlock is common, not guaranteed.
    - **Foreign unlock:** Only the owning thread may unlock a mutex.
    - **Owned at death:** Destroying an owned mutex, or a thread ending while it owns one.
  - **One-time initialization:** Two standard ways to run initialization exactly once under concurrency.
    - **Magic statics:** Since C++11 concurrent callers wait; a throw means retry; recursive re-entry is undefined.
    - **call_once:** Exceptional executions leave the flag unset; the returning one synchronizes with passive calls.
  - **Granularity:** Hold a lock for the shortest stretch that keeps the invariant intact.
    - **No unknown code:** Callbacks under a lock can relock or invert lock order; snapshot, unlock, then call.
    - **No leaked references:** A reference to guarded data returned from a locked accessor is unprotected afterwards.

## Standardese Quiz Questions

### Question 1 [warmup] ([thread.mutex.requirements.mutex], [thread.mutex.class])

What does the standard say about calling `f()`?

```cpp
#include <mutex>

std::mutex m;

void g() { std::lock_guard lk(m); }
void f() { std::lock_guard lk(m); g(); }

int main() { f(); }
```

A. It deadlocks, guaranteed
B. It works: a thread may relock a mutex it already owns
C. `g` throws `std::system_error` with `resource_deadlock_would_occur`
D. Undefined behavior

**Answer (D):** Undefined behavior

**Why:** For `std::mutex`, the calling thread not owning the mutex is a precondition of `lock`, so the second lock in `g` is undefined behavior. Deadlock is the common outcome and a note allows an implementation that detects it to report `resource_deadlock_would_occur`, but neither is guaranteed, which is why the first and third options are wrong. Only the recursive mutex types allow the owner to lock again.

### Question 2 [warmup] ([thread.lock.unique])

In C++17 or later, what does this program print?

```cpp
#include <iostream>
#include <mutex>

std::mutex m;

int main() {
  std::unique_lock lk(m, std::defer_lock);
  std::cout << lk.owns_lock();
  lk.lock();
  std::cout << lk.owns_lock() << '\n';
}
```

A. `11`
B. `01`
C. `00`
D. Nothing; `lk.lock()` deadlocks because the constructor already locked `m`

**Answer (B):** `01`

**Why:** `std::defer_lock` associates the `unique_lock` with the mutex without locking it, so `owns_lock()` is false at first. The explicit `lk.lock()` then acquires `m`, and the destructor unlocks it at the end of `main`. The deadlock option assumes every `unique_lock` constructor locks, which is only true for the untagged one.

### Question 3 [warmup] ([thread.lock.scoped], [thread.lock.algorithm])

What does this program print?

```cpp
#include <cstdio>
#include <mutex>
#include <thread>

std::mutex a, b;
long n = 0;

void forward() {
  for (int i = 0; i < 100000; ++i) {
    std::scoped_lock lk(a, b);
    ++n;
  }
}

void backward() {
  for (int i = 0; i < 100000; ++i) {
    std::scoped_lock lk(b, a);
    ++n;
  }
}

int main() {
  std::thread t1(forward), t2(backward);
  t1.join();
  t2.join();
  std::printf("%ld\n", n);
}
```

A. It may deadlock, because the two threads take the mutexes in opposite orders
B. Some value up to 200000, because `++n` is not atomic
C. `200000`
D. Ill-formed: `scoped_lock` arguments must be listed in a consistent order

**Answer (C):** `200000`

**Why:** With more than one mutex, `scoped_lock` acquires them using the `std::lock` algorithm, which avoids deadlock whatever order the arguments are given in. Every `++n` happens while holding both mutexes, so the increments are serialized and ordered by unlock-to-lock synchronization, and no update is lost. Opposite-order deadlock is exactly the problem `std::lock` exists to solve; it would be the right answer with two nested `lock_guard`s.

### Question 4 [tricky] ([stmt.ambig], [dcl.ambig.res], [thread.lock.unique])

What does the first statement of `bump` do?

```cpp
#include <mutex>

std::mutex m;
int counter = 0;

void bump() {
  std::unique_lock<std::mutex>(m);
  ++counter;
}
```

A. Locks `m` until the end of `bump`
B. Declares a default-constructed `unique_lock` named `m`, so nothing is locked
C. Locks `m` and unlocks it again at the end of the statement
D. Nothing: it is ill-formed because `unique_lock` has no default constructor

**Answer (B):** Declares a default-constructed `unique_lock` named `m`, so nothing is locked

**Why:** A statement that can be read as a declaration is a declaration, and `T(m);` declares a variable `m` of type `T` with redundant parentheses. So it declares a new local `unique_lock` named `m` that shadows the mutex and owns nothing, and `++counter` runs unprotected. The third option describes `std::unique_lock<std::mutex>{m};`, which creates a temporary. `unique_lock` does have a default constructor; `lock_guard` does not, which is why the compiler rejects the same mistake with `lock_guard`.

### Question 5 [tricky] ([thread.mutex.requirements.mutex])

No other thread exists. What does the standard guarantee this program prints?

```cpp
#include <cstdio>
#include <mutex>

std::mutex m;

int main() {
  if (m.try_lock()) {
    std::puts("locked");
    m.unlock();
  } else {
    std::puts("not locked");
  }
}
```

A. `locked`, because the mutex is free
B. `not locked`, because `try_lock` on a static mutex fails before `main`
C. Undefined behavior, because `try_lock` needs a `unique_lock`
D. Either `locked` or `not locked`

**Answer (D):** Either `locked` or `not locked`

**Why:** [thread.mutex.requirements.mutex] allows `try_lock` to fail to obtain the lock even when no thread owns the mutex. Implementations do this rarely, and on a quiet mutex you will practically always see `locked`, but the standard does not promise it. That is the reason a failed `try_lock` must never be read as evidence that another thread holds the lock.

### Question 6 [tricky] ([thread.once.callonce])

According to the standard, what does this program print?

```cpp
#include <iostream>
#include <mutex>

std::once_flag flag;
int calls = 0;

void init() {
  ++calls;
  if (calls == 1) throw 1;
}

int main() {
  for (int i = 0; i < 3; ++i) {
    try {
      std::call_once(flag, init);
    } catch (int) {
    }
  }
  std::cout << calls << '\n';
}
```

A. `1`: the flag is set once `init` has been called, even if it threw
B. `2`
C. `3`: an exception makes the flag unusable, so every call runs `init`
D. Undefined behavior: the callable of `call_once` must not throw

**Answer (B):** `2`

**Why:** The first call is an exceptional execution: the exception propagates and the flag is not set. The second call is then an active execution that returns normally, which makes it the returning execution and sets the flag, so the third call is passive and does not run `init`. Throwing is explicitly allowed. Be aware that libstdc++ on targets that implement `call_once` with `pthread_once` has a long-standing bug here: on this page's macOS test machine the GCC build was killed instead of printing, while the Clang build with libc++ printed `2`.

### Question 7 [standardese] ([stmt.dcl])

What does the standard say about calling `f(0)`?

```cpp
int f(int n) {
  static int cached = f(n + 1);
  return cached + n;
}

int main() { return f(0); }
```

A. Undefined behavior
B. It returns 1, because `cached` is zero-initialized when the recursive call reads it
C. It is guaranteed to deadlock, because the static's guard waits for itself
D. It throws an exception reporting recursive initialization

**Answer (A):** Undefined behavior

**Why:** [stmt.dcl] says that if control re-enters the declaration recursively while the variable is being initialized, the behavior is undefined. Deadlocking and throwing are both things real implementations do, but neither is required. The zero-initialized reading would be the answer only if recursion simply skipped the initializer, which the standard does not say.

### Question 8 [standardese] ([thread.mutex.class])

What does the standard say about this program?

```cpp
#include <mutex>
#include <thread>

std::mutex m;

int main() {
  std::thread t([] { m.lock(); });
  t.join();
}
```

A. It is fine: the mutex is unlocked automatically when its owner exits
B. It is fine as long as no other thread tries to lock `m`
C. Undefined behavior
D. It is ill-formed, because `m.lock()` without a lock wrapper is not allowed

**Answer (C):** Undefined behavior

**Why:** [thread.mutex.class] says the behavior is undefined if a thread terminates while owning a mutex, and also if a mutex owned by any thread is destroyed, which would happen later when `m` is destroyed at program exit. Nothing unlocks a mutex when its owner ends, which rules out the first option, and the undefined behavior does not depend on whether anyone else contends. Calling `lock` directly is legal; the wrappers are a convenience.
