Threads for Dummies using C++20
You’ve heard threads are hard.
You’ve probably also heard they cause bugs nobody can reproduce, and that you should leave them to the experts.
Some of that is true. Most of it is just what people say about things they haven’t looked at closely.
So let’s look closely.
Every example here is a complete program. Copy it, run it, and watch what happens. Watching is underrated.
What is a thread?#
Picture a kitchen with one cook. Pasta, then salad, then soup. Very orderly. Very slow.
A thread is a second cook. Or a third.
Now the pasta, salad and soup happen at the same time, and dinner is on the table sooner.
But you’ve already spotted the problem, haven’t you? Three cooks, one kitchen. Sooner or later, two of them reach for the same pan.
Most of this post is about that pan.
Compiling the examples#
You need a compiler that supports C++20. Recent GCC, Clang and MSVC all do.
g++ -std=c++20 -pthread hello.cpp -o hello
./hello
-std=c++20 turns on C++20. -pthread turns on thread support on Linux and macOS.
Your first thread#
#include <iostream>
#include <thread>
void say_hello() {
std::cout << "Hello from the thread!\n";
}
int main() {
std::jthread worker(say_hello); // starts running say_hello right now
std::cout << "Hello from main!\n";
} // main waits here for worker to finish
When I ran it, I got:
Hello from main!
Hello from the thread!
Run it again. And again. Sometimes the two lines swap places.
That isn’t a bug. It’s the first thing threads teach you, and the thing people most want to ignore: once two threads are running, you don’t decide who finishes first. You only decide who waits for whom.
Here’s what actually happened:
std::jthread worker(say_hello);creates a new thread and immediately starts runningsay_helloon it.- Meanwhile,
maindoesn’t wait around. It moves on to the next line and prints its own message.
At the closing }, worker goes out of scope. A jthread won’t leave without its thread, so it waits until the work is done. That waiting is called joining.
Why jthread and not thread?#
You’ll meet std::thread in older code and tutorials. It looks identical. It isn’t.
int main() {
std::thread worker(say_hello);
} // crash! std::thread doesn't wait on its own
Let a std::thread go out of scope without calling worker.join(), and your program crashes. No warning. Just gone.
Everyone forgets the join() eventually. The answer isn’t to try harder to remember. It’s to use something that can’t forget.
std::jthread (new in C++20) joins by itself. That’s what the “j” stands for.
Rule for beginners: use std::jthread.
Passing arguments#
Put the arguments after the function name:
#include <iostream>
#include <string>
#include <thread>
void greet(std::string name, int times) {
for (int i = 0; i < times; ++i) {
std::cout << "Hi, " << name << "!\n";
}
}
int main() {
std::jthread t(greet, "Alice", 3); // same as calling greet("Alice", 3)
t.join(); // wait right here until t is done
std::cout << "Done greeting Alice.\n";
}Hi, Alice!
Hi, Alice!
Hi, Alice!
Done greeting Alice.
This time I called t.join() myself. It means: stop here, and wait until t is finished.
Take it out, and “Done greeting Alice.” might announce itself before Alice has been greeted at all. Confident, and wrong. We’ve all met people like that.
Several threads at once#
Back to the kitchen. Three dishes, three cooks:
#include <chrono>
#include <iostream>
#include <string>
#include <syncstream>
#include <thread>
void cook(std::string dish, int seconds) {
std::osyncstream(std::cout) << "Started " << dish << '\n';
std::this_thread::sleep_for(std::chrono::seconds(seconds));
std::osyncstream(std::cout) << "Finished " << dish << '\n';
}
int main() {
auto start = std::chrono::steady_clock::now();
{
std::jthread a(cook, "pasta", 3);
std::jthread b(cook, "salad", 1);
std::jthread c(cook, "soup", 2);
} // all three cooks are waited for here
auto took = std::chrono::steady_clock::now() - start;
auto secs = std::chrono::duration_cast<std::chrono::seconds>(took).count();
std::cout << "Dinner ready in " << secs << " seconds\n";
}Started soup
Started salad
Started pasta
Finished salad
Finished soup
Finished pasta
Dinner ready in 3 seconds
Add it up: 3 + 1 + 2 is 6 seconds of cooking. Dinner took 3.
Nobody worked any faster. They just stopped waiting for each other. That’s all threads really are.
Two new things in this example:
std::this_thread::sleep_for(...)pauses the current thread. Here it stands in for real work.std::osyncstream(std::cout)is a thread-friendlystd::cout. Without it, two threads printing at the same moment can interrupt each other mid-sentence. Rude, and very hard to read.osyncstreammakes sure each line comes out in one piece.
When threads share things: the bug#
Now, the pan.
Two threads, one shared counter. Each thread adds 1 to it a hundred thousand times. You already know the answer: 200,000.
#include <iostream>
#include <thread>
int counter = 0;
void add_a_lot() {
for (int i = 0; i < 100000; ++i) {
++counter;
}
}
int main() {
{
std::jthread a(add_a_lot);
std::jthread b(add_a_lot);
}
std::cout << "counter = " << counter << '\n'; // we expect 200000
}
I ran it five times:
counter = 158516
counter = 143822
counter = 121359
counter = 116680
counter = 134344
Wrong every time. And wrong differently every time. That second part is the tell.
When the result changes from run to run but the code doesn’t, something is happening that you can’t see. So let’s make it visible.
++counter looks like one move. It’s actually three:
- Read
counter(say it’s 5). - Add 1 (now 6).
- Write 6 back.
Now picture both threads doing it at the same moment:
Thread A: reads 5
Thread B: reads 5
Thread A: writes 6
Thread B: writes 6 <- should be 7! one +1 was lost
Neither thread did anything wrong on its own. The problem is the gap between reading and writing. That’s where the other thread slips in.
This is called a data race. In C++ it’s undefined behaviour, which means the program is broken even on the runs where it happens to print the right number. Especially on those runs, really, because that’s when you believe it.
The rule: if two threads use the same variable and at least one of them changes it, you need protection.
There are two easy kinds.
Fix #1: a mutex#
A mutex is a lock, and only one thread can hold it at a time.
Think of the key to a café bathroom. There’s only one. Whoever has it goes in. Everyone else waits, and nobody walks in on anybody.
#include <iostream>
#include <mutex>
#include <thread>
int counter = 0;
std::mutex counter_mutex;
void add_a_lot() {
for (int i = 0; i < 100000; ++i) {
std::lock_guard lock(counter_mutex); // lock...
++counter;
} // ...unlocked automatically here
}
int main() {
{
std::jthread a(add_a_lot);
std::jthread b(add_a_lot);
}
std::cout << "counter = " << counter << '\n';
}counter = 200000
std::lock_guard takes the key when it’s created and hands it back at the }. You never have to remember to return it. Which is good, because people don’t.
Use a mutex whenever a few lines of code need to run without another thread getting in the middle.
Fix #2: an atomic#
For a single number, there’s something simpler: std::atomic.
#include <atomic>
#include <iostream>
#include <thread>
std::atomic<int> counter = 0;
void add_a_lot() {
for (int i = 0; i < 100000; ++i) {
++counter; // safe: atomic
}
}
int main() {
{
std::jthread a(add_a_lot);
std::jthread b(add_a_lot);
}
std::cout << "counter = " << counter << '\n';
}counter = 200000
Spot the difference. int became std::atomic<int>. That’s it.
An atomic does the read, the add and the write in one move, with no gap in between. No gap, nowhere for the other thread to slip in.
Atomics are great for simple counters and on/off flags. For anything bigger, like updating two variables together, use a mutex.
Stopping a thread#
Some threads are meant to keep going until you say so: a timer, a background download, a game loop.
You can’t just kill a thread mid-task. It might be holding the bathroom key. So you don’t force it. You ask, and let it finish on its own terms.
C++20 has this built in, through std::stop_token:
#include <chrono>
#include <iostream>
#include <thread>
void tick(std::stop_token token) {
int seconds = 0;
while (!token.stop_requested()) {
std::cout << "tick " << ++seconds << '\n';
std::this_thread::sleep_for(std::chrono::seconds(1));
}
std::cout << "timer stopped\n";
}
int main() {
std::jthread timer(tick); // jthread passes the stop_token in for us
std::this_thread::sleep_for(std::chrono::milliseconds(3500));
timer.request_stop(); // politely ask the thread to finish
}tick 1
tick 2
tick 3
tick 4
timer stopped
How it works:
- If your function’s first parameter is a
std::stop_token,jthreadhands one in automatically. timer.request_stop()raises a flag.- The thread checks
token.stop_requested()in its loop, sees the flag, and wraps up.
Notice the “tick 4”. The thread was asleep when we asked, and only noticed when it woke up and checked again. A request is only as fast as whoever’s listening for it.
One more thing: when a jthread goes out of scope, it calls request_stop() and then joins. So even without timer.request_stop(), the timer would still stop cleanly at the end of main.
Waiting for everyone: std::latch#
Sometimes you need to wait until several threads have all done something.
You’re meeting three friends at the cinema. You don’t go in until everyone’s there. And you already know Chen will be last.
#include <chrono>
#include <functional>
#include <iostream>
#include <latch>
#include <string>
#include <syncstream>
#include <thread>
void get_ready(std::string name, int seconds, std::latch& everyone_here) {
std::this_thread::sleep_for(std::chrono::seconds(seconds));
std::osyncstream(std::cout) << name << " arrived\n";
everyone_here.count_down(); // one less person to wait for
}
int main() {
std::latch everyone_here(3); // we're waiting for 3 friends
std::jthread a(get_ready, "Asha", 2, std::ref(everyone_here));
std::jthread b(get_ready, "Ben", 1, std::ref(everyone_here));
std::jthread c(get_ready, "Chen", 3, std::ref(everyone_here));
everyone_here.wait(); // block until the count reaches 0
std::cout << "Everyone's here. Movie time!\n";
}Ben arrived
Asha arrived
Chen arrived
Everyone's here. Movie time!
Told you.
A std::latch is just a countdown:
std::latch everyone_here(3)starts it at 3.- Each
count_down()takes 1 off. wait()blocks until it reaches 0.
Now look at std::ref(everyone_here). A thread normally gets its own copy of every argument. Three separate copies of a countdown wouldn’t help anyone. std::ref says: don’t copy this, share the one we’ve got. Leave it out and the compiler refuses, for good reason.
The usual mistakes#
I’ll tell you what you’re going to get wrong. Not because I’m psychic. There’s no such thing. It’s just that everyone gets the same things wrong.
Using std::thread and forgetting join(). The program crashes. Use std::jthread.
Sharing a variable without protection. If more than one thread touches it and anyone writes to it, use a std::mutex or a std::atomic.
Expecting a fixed order. Threads run at the same time. If something must happen after something else, wait for it with join(), a latch, or a lock.
Passing a reference to something that dies first. If a thread holds a reference to a local variable, that variable must outlive the thread. Declaring it before the jthread, like everyone_here above, takes care of that.
Creating thousands of threads. Each thread costs memory and setup time, and your CPU only runs a handful at once. std::thread::hardware_concurrency() tells you roughly how many.
Cheat sheet#
| I want to… | Use |
|---|---|
| Run a function in the background | std::jthread t(func, args...) |
| Wait for a thread to finish | t.join(), or let t go out of scope |
| Protect a block of code | std::mutex + std::lock_guard |
| Safely share a counter or flag | std::atomic<int>, std::atomic<bool> |
| Ask a thread to stop | t.request_stop() + a std::stop_token parameter |
| Wait for N threads to reach a point | std::latch |
| Print from several threads | std::osyncstream(std::cout) |
Where to go next#
Once these feel comfortable, have a look at std::condition_variable (a thread sleeps until another wakes it up), std::barrier (a latch you can reuse), std::counting_semaphore (at most N threads at once) and std::async (run something and collect its result later).
But jthread, mutex, atomic and stop_token will take you a surprisingly long way.
Threads were never magic. They’re just several things happening at once, plus a few rules about who waits for whom.
More cooks.
One bathroom key.
And nobody leaves the kitchen until everyone’s done.