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.
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::mutexis the plain exclusive mutex. Its default constructor isconstexpr, so a namespace-scopestd::mutexis constant-initialized and has no static initialization order problem.std::recursive_mutexlets the owning thread lock again; it must unlock as many times as it locked. The maximum depth is unspecified, and exceeding it makeslockthrowstd::system_errorandtry_lockreturn false.std::timed_mutexandstd::recursive_timed_mutexadd timed attempts.std::shared_timed_mutex(C++14) andstd::shared_mutex(C++17) add a shared mode: many threads may holdlock_sharedat once, butlockexcludes 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.
#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. Thestd::adopt_locktag 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 likelock_guard; with several it locks them all through the deadlock-avoidingstd::lockalgorithm.std::unique_lock<M>is movable and may or may not own the mutex at any moment. It acceptsstd::defer_lock,std::try_to_lock,std::adopt_lockand timeouts, and offerslock,unlock,owns_lockandrelease, which gives up the association without unlocking. It is the typestd::condition_variablerequires, and it costs a flag and a branch more thanlock_guard.std::shared_lock<M>(C++14) is the shared-mode counterpart ofunique_lock, callinglock_sharedandunlock_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.
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.
#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_guards with std::adopt_lock, or two unique_locks 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_mutexorshared_timed_mutexthat the calling thread already owns. Many implementations deadlock, and a note in [thread.mutex.class] says one that detects it might reportresource_deadlock_would_occur, but the standard promises neither. - Calling
unlockfrom 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.
#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
}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.
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.
#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.
#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
unlocksynchronizes with the nextlockof the same mutex; that is what makes guarded non-atomic data race-free. - Lockable types are defined by requirements: BasicLockable (
lock,unlock), Lockable (addstry_lock), TimedLockable (adds timed tries). try_lockmay fail spuriously, and a failedtry_locksynchronizes with nothing.std::mutexhas aconstexprconstructor. Mutexes are neither copyable nor movable.- Prefer
scoped_lock; useunique_lockwhen you need to unlock early, move ownership, or wait on a condition variable; useshared_lockfor readers. - A lock wrapper that is a temporary, or a parenthesized declaration, protects nothing.
std::lockand multi-mutexscoped_lockavoid 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_onceretries 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.