C++ concurrency basics: threads, mutexes and condition variables
An introduction to multithreaded C++: std::thread, data races, std::mutex, condition variables with predicates, futures, clean shutdown and how to test concurrent code.
Multithreaded code lets a program do several things at once, and introduces a new class of bugs that only show up sometimes. The standard library gives you everything you need; the hard part is using it with discipline.
Threads
std::thread worker([] { process_queue(); });
// ...
worker.join(); // wait for it to finish; every thread must be joined (or detached)std::jthread (C++20) joins automatically in its destructor.
Data races and mutexes
If two threads touch the same data and one of them writes, you need synchronisation. A
std::mutex with an RAII lock is the standard tool:
std::mutex mutex;
std::deque<std::string> items;
void push(std::string message) {
std::lock_guard lock(mutex); // unlocked automatically at the end of the scope
items.push_back(std::move(message));
}Rule of thumb: every piece of shared state has exactly one mutex that protects it, and you never touch the state without holding it.
Waiting for something: condition variables
To wait until "the queue isn't empty" without busy-looping:
std::condition_variable not_empty;
std::string pop() {
std::unique_lock lock(mutex);
not_empty.wait(lock, [&] { return !items.empty(); }); // releases the lock while waiting
auto message = std::move(items.front());
items.pop_front();
return message;
}
// in push(), after adding: not_empty.notify_one();Always pass a predicate: waits can wake spuriously. Build a full bounded, closable queue in a message queue for Relaybox.
Waiting with a deadline
wait_for and wait_until stop waiting when time runs out. With a predicate, they return
whether the condition became true:
bool pop_until(std::string& out, std::chrono::steady_clock::time_point deadline) {
std::unique_lock lock(mutex);
if (!not_empty.wait_until(lock, deadline, [&] { return !items.empty() || closed; })) {
return false; // timed out, still empty
}
if (items.empty()) return false; // woken because the queue was closed
out = std::move(items.front());
items.pop_front();
return true;
}Compute the deadline once (steady_clock::now() + timeout) and wait until it. Calling
wait_for(timeout) in a loop restarts the clock after every spurious wake-up. To take a
batch, wait for the first item, then take up to n without waiting again.
A pool of worker threads
A thread pool is a fixed set of threads that loop over a shared queue of tasks:
void worker_loop() {
for (;;) {
std::function<void()> task;
{
std::unique_lock lock(mutex);
has_work.wait(lock, [&] { return stopping || !tasks.empty(); });
if (stopping && tasks.empty()) return;
task = std::move(tasks.front());
tasks.pop_front();
++running;
}
try { task(); } catch (...) { /* record it; never let it kill the worker */ }
{
std::lock_guard lock(mutex);
--running;
if (tasks.empty() && running == 0) idle.notify_all();
}
}
}Three details matter: run the task outside the lock (or tasks run one at a time), catch
everything a task throws (an exception escaping a thread calls std::terminate), and count
running tasks so wait_idle() can wait for "queue empty and nobody busy". To return results,
wrap tasks in std::packaged_task; see
storing callables.
Futures: results from other threads
auto future = std::async(std::launch::async, [] { return render_thumbnail(); });
auto image = future.get(); // waits; rethrows if the task threwA thread pool returns futures the same way; see a thread pool for Batchworks.
Shutting down cleanly
Most concurrency bugs live in shutdown. Decide explicitly:
- What happens to work that's queued but not started?
- How do waiting threads find out they should stop? (Set a flag under the lock, then
notify_all.) - Who joins the threads, and when?
Testing concurrent code
- Test guarantees, not timing: nothing lost, nothing duplicated, everyone woken on close.
- Use generous timeouts and lower bounds only (
elapsed >= 50ms), never tight upper bounds. - Run tests repeatedly:
ctest --repeat until-fail:20. - Build once with
-fsanitize=thread(GCC and Clang): it reports data races your tests missed.
When the shared state is a single number, std::atomic is enough. When it isn't, start with a
mutex, and measure before reaching for anything cleverer.
Questions and answers
- What is a data race?
- Two threads access the same memory at the same time, at least one of them writes, and nothing orders the accesses. In C++ that's undefined behaviour. Protect shared data with a mutex, or use std::atomic for single values.
- Why must condition_variable::wait be called with a predicate?
- Waits can wake up spuriously, or another thread may have taken the item first. wait(lock, predicate) re-checks the condition after every wake-up and only returns when it's true.
Practise it in a project
These projects put this guide to work, with tickets, tests and code review.
Relaybox
A message queue for Relaybox
Build the bounded, blocking, closable queue between Relaybox's receivers and senders: mutexes, condition variables, backpressure, shutdown, timeouts and batches.
- threads
- mutexes
- condition variables
- backpressure
Batchworks
A thread pool for Batchworks
Replace thread-per-job with a fixed pool of workers: a shared task queue, graceful shutdown, failure accounting, futures for results and a parallel_for.
- threads
- task queues
- futures
- shutdown semantics
Gatekeep
Rate limiting for Gatekeep
Protect Gatekeep's customers from traffic floods with token buckets: exact integer refills, a testable clock, per-client limits and bounded memory.
- token buckets
- injected time
- integer arithmetic
- memory bounds