Skip to content
Tutorials Center
My learning

Topics

Lesson 132 of 171 ยท Concurrency

Threads

Learn C++ threads - start work with std::thread, join and detach, pass arguments safely, split work across cores, and stop std::jthread workers cleanly with stop tokens.

A thread is an independent flow of execution inside your program. Every program starts with one thread, the one that runs main. When you start more, they run concurrently: the operating system switches between them, and on a machine with several CPU cores they truly run at the same moment. Threads let you use all the cores for heavy computation, keep a user interface responsive while work happens in the background, and handle many network clients at once.

All threads of a program share the same memory: globals, the heap, and any object whose address they're given. That's what makes threads powerful (no copying needed to share data) and what makes them dangerous (two threads touching the same data at once is a bug). This lesson covers starting and finishing threads with std::thread and the C++20 std::jthread, passing arguments correctly, splitting work so threads don't step on each other, stopping threads cleanly, and handling exceptions. The next lessons cover sharing data safely: Mutexes and Locks, Condition Variables and Atomics.

Starting a thread and joining it

std::thread from <thread> starts a new thread as soon as it's constructed. You give it a callable: a function, a lambda, or any function object, plus the arguments to call it with. The new thread runs that callable and ends when it returns.

Before the std::thread object is destroyed, you must decide what happens to the thread:

  • t.join() waits until the thread finishes. This is what you want almost always.
  • t.detach() lets the thread run on its own; the std::thread object no longer represents it.

If a std::thread is destroyed while it still represents a running (or finished but not joined) thread, the program calls std::terminate and crashes. This rule forces you to make the choice explicitly.

C++ Starting and joining threads

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

Run it several times. The lines from rocket and balloon interleave, and the order can change between runs: the scheduler decides who runs when. The only order guaranteed here is the one the code enforces: each thread's own lines appear in order, and "everyone finished" comes last because both join() calls happen before it. Never write code that assumes an interleaving.

Two practical notes. std::println writes each call's whole line in one go, so lines from different threads don't get mixed character by character; with std::cout << a << b, each << is a separate write, and output from two threads can be shredded in the middle of a line. And std::this_thread offers get_id(), sleep_for(), sleep_until() and yield() for the current thread.

Why detach is almost always wrong

A detached thread keeps running after the code that started it has moved on, and nobody can wait for it. When main returns, the process ends and detached threads are killed mid-work, without running their destructors. Worse, a detached thread that refers to a local variable of the function that started it keeps using that variable after it's gone, which is undefined behavior:

C++
void start_logger() {
    std::string prefix = "[log] ";
    std::thread t{[&prefix] {                // captures a local by reference
        std::this_thread::sleep_for(std::chrono::seconds{1});
        std::println("{}hello", prefix);     // prefix was destroyed long ago: UB
    }};
    t.detach();
}                                            // prefix dies here

Detach only makes sense for a thread that owns everything it uses and may safely be killed at exit. In practice, prefer std::jthread (below), which joins automatically.

Passing arguments: copies, references and moves

The arguments you pass to the std::thread constructor are copied (or moved) into storage owned by the new thread, then passed to the function from there. This is a safety feature: the thread doesn't depend on the caller's variables. It has consequences:

  • A function taking int& won't silently bind to your variable. To really pass a reference, wrap it: std::ref(x) (or std::cref(x) for const). Then you guarantee x outlives the thread.
  • Move-only objects such as std::unique_ptr must be passed with std::move.
  • A pointer is copied as a pointer: the data it points to must stay alive.
  • To run a member function, pass the member pointer, then the object (usually its address): std::thread{&Robot::run, &robot, 5}.
C++ Passing arguments to threads

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

The commented-out line is worth understanding. Because arguments are copied into the thread first, add_bonus would receive a reference to that internal copy, which is a temporary. The library rejects this at compile time (with a long template error) rather than letting you silently update a copy.

One more subtle trap: std::thread t{f, buffer} where f takes a std::string and buffer is a local char array. The pointer is copied, and the conversion to std::string happens inside the new thread, possibly after buffer is gone. Convert first: std::thread t{f, std::string{buffer}}.

Splitting work across threads

The main reason to use threads is speed: divide a big job into parts and run them in parallel. The safest pattern is to give each thread its own data to write: its own slot in a results vector, or its own output object. Then threads never write the same memory, there's nothing to synchronize, and join() makes all results visible to the main thread.

std::thread::hardware_concurrency() returns a hint for how many threads the hardware can run at once (it may return 0 if unknown). A common choice is to start that many workers for CPU-bound work.

C++ A parallel sum with one slot per thread

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

Our code server gives each program a single CPU core, so hardware_concurrency may report more cores than the program can actually use, and the threads take turns instead of running in parallel. The result is still correct, which is the point of this pattern; on your own multi-core machine the parallel version finishes several times faster. Two habits make such code robust: handle a hint of 0, and don't start more threads than there are cores for CPU-bound work, since extra threads only add switching overhead.

The lambda captures values and partial by reference, and that's safe here because every thread is joined before those vectors go out of scope. Each thread also reads values concurrently, which is fine: concurrent reads of data nobody writes are never a race. Splitting work by hand like this is educational; in real code also consider the parallel algorithms (std::reduce(std::execution::par, ...)) and std::async.

std::jthread: joining and stopping made easy (C++20)

std::jthread ("joining thread") fixes the two biggest annoyances of std::thread:

  1. It joins automatically in its destructor, so forgetting join() can't crash your program, and an exception that leaves the scope still waits for the thread. It's RAII applied to threads.
  2. It supports cooperative cancellation. Each jthread owns a stop source. If the thread's function takes a std::stop_token as its first parameter, jthread passes one in automatically. The function checks token.stop_requested() from time to time and exits when it's true. Anyone can call t.request_stop(), and the destructor calls it before joining.

"Cooperative" means C++ never kills a thread from the outside: the thread must check the token and stop itself, which guarantees destructors run and data stays consistent.

C++ Stopping a jthread with a stop token

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

The number of beats differs from run to run (around ten): it depends on how the 5 ms sleeps line up with the 50 ms that main waits. In the second block, main never calls request_stop(): leaving the scope does it. A std::stop_callback registered on the token runs its function when stop is requested (in the thread that requests it), which is handy for waking up something the worker is blocked on. Condition variables have a wait overload that takes a stop token directly, shown in Condition Variables.

Prefer std::jthread in new code. Use std::thread when you need compatibility with C++17 or older libraries; the two are otherwise used the same way.

Exceptions and thread-local storage

An exception that escapes a thread's function calls std::terminate: there is nobody to catch it, because the thread that started the work is busy elsewhere. If a worker can fail, catch inside the thread and pass the error back. std::exception_ptr holds any exception: std::current_exception() captures it in a catch block and std::rethrow_exception() throws it again in the other thread. (std::async and futures do this automatically.)

A variable declared thread_local exists once per thread: each thread gets its own copy, created when the thread first uses it and destroyed when the thread ends. It's ideal for per-thread caches, counters or random engines.

C++ Passing an exception back and thread_local data

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

std::stoi("abc") throws std::invalid_argument with the message stoi, the GCC library's terse wording; the other failure carries our own message. Each thread's calls_in_this_thread starts at 0, so thread a counts 5, thread b counts 2, and the main thread, which never called tracked_work, counts 0.

A first look at data races

Everything so far avoided one thing: two threads accessing the same variable at the same time, with at least one of them writing. That's a data race, and in C++ it's undefined behavior, not just "a slightly wrong number". Even ++counter is a read, an add and a write, and another thread can sneak in between them:

C++
int counter = 0;
auto bump = [&counter] {
    for (int i = 0; i < 100'000; ++i) {
        ++counter;                // data race: undefined behavior
    }
};
std::jthread t1{bump}, t2{bump};  // the final value is unpredictable

The fix is to synchronize access, with a mutex, an atomic, or by not sharing at all (the one-slot-per-thread pattern above). The next lesson shows such races happening and fixes them.

Common mistakes

  • Forgetting to join a std::thread: the destructor calls std::terminate. Use std::jthread.
  • Detaching and then using locals (references, pointers, std::string_views) that die before the thread is done.
  • Expecting int& parameters to work without std::ref, or passing std::ref to something that doesn't outlive the thread.
  • Letting exceptions escape a thread function. Catch them and pass them back.
  • Too many threads. Thousands of threads for CPU work only add switching costs; use about hardware_concurrency() threads, or a thread pool.
  • Relying on output order or timing with sleep_for as "synchronization". Sleeping makes a race less likely, not impossible.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What happens if a std::thread object that still represents a running thread is destroyed without join() or detach()?

    std::thread's destructor terminates the program if the thread is still joinable. std::jthread joins in its destructor instead.
  2. 2. Given void inc(int& x); and int n = 0;, which line runs inc on n in a new thread?

    Arguments are copied into the thread, so a plain n does not bind to int& and fails to compile. std::ref passes a reference. The last option calls inc immediately in the current thread.
  3. 3. Two threads print lines with std::println and are both joined at the end of main. What can you say about the order of their lines?

    Only the order enforced by the code is guaranteed. The scheduler decides when each thread runs.
  4. 4. How does a std::jthread worker usually stop?

    Cancellation is cooperative. request_stop() (called automatically by the destructor) sets the flag, and the worker function must notice and return.
  5. 5. Several threads each write only results[i] for their own i, and main reads results after joining all of them. Is there a data race?

    Different elements are different memory locations, so the threads never conflict, and join() synchronizes the finished thread with the joining one. (Resizing the vector while they run would be a race.)

Summary

  • std::thread{callable, args...} starts a thread immediately; call join() before it's destroyed (or detach(), which is rarely right).
  • Arguments are copied into the thread: use std::ref for references, std::move for move-only types, and &Class::method, &obj for member functions. Keep anything shared alive until the thread is joined.
  • Split work so each thread writes its own data; join() makes the results visible. hardware_concurrency() is a hint and may be 0.
  • std::jthread (C++20) joins automatically and supports cooperative cancellation with std::stop_token, request_stop() and std::stop_callback.
  • Exceptions must not escape a thread; carry them back with std::exception_ptr. thread_local gives each thread its own variable.
  • Two threads accessing the same data with at least one writer, without synchronization, is a data race and undefined behavior.

Next: Mutexes and Locks, where you'll protect shared data with std::mutex, std::lock_guard and std::scoped_lock.