std::thread and std::jthread: start, join and stop a thread

To start a thread in C++20, construct a std::jthread from a function and its arguments: std::jthread worker(drain, std::ref(queue));. The function runs on a new thread, its arguments are copied in the calling thread first (std::ref passes a reference), and when worker goes out of scope its destructor asks the thread to stop and joins it. std::thread (C++11) starts a thread the same way but must be joined by hand: destroying one that is still joinable calls std::terminate. So does an exception that leaves the thread’s function, with either class.

This answer is written for C++20, which added std::jthread, std::stop_token and std::stop_callback (P0660R10) to the C++11 std::thread. C++23 reworded how the constructor copies its arguments and added a std::formatter for std::thread::id; thread attributes such as std::thread::name_hint came after C++26, in the working draft. cppreference’s std::jthread page lists every member. Since When’s C++20 table gives the first releases of std::jthread, and its C++11 table the support for std::thread.

The samples were built with four compilers on three standard libraries: MSVC 19.44 and Clang 19.1 on Microsoft’s STL (Windows x64), GCC 16.2 with libstdc++ and Clang 23.1 with libc++ (Compiler Explorer, Linux x86-64). Each output shown is what all four printed, unless the text says otherwise. The std::thread samples are C++11 code, built as C++14 on all four (MSVC has no C++11 mode) and also as C++11 with GCC and libc++.

The Linux builds of the samples that end normally also ran clean under ThreadSanitizer, one of the sanitizers on the Toolchain page.

What changed: a thread is started with std::thread, and join() on every path std::jthread, which joins itself.

since C++20

Start a thread with std::jthread

Any callable starts a thread: a function and its arguments, a lambda or another of the function objects C++ has, or a member function followed by a pointer to its object. The running example processes jobs, each an id and a size in bytes:

struct Job {
    int id;
    std::size_t size;
};

void process(const Job& job) {
    std::cout << "job " << job.id << ": " << job.size << " bytes\n";
}
// ...
{
    std::jthread worker(process, Job{1, 4096});  // started
}   // ~jthread(): waits for the thread here
std::cout << "main: job 1 is done\n";
// ...
{
    Job job{2, 512};
    std::jthread worker([job] { process(job); });
}
// ...
Worker worker(std::vector<Job>{{3, 128}, {4, 64}});
{
    std::jthread t(&Worker::run, &worker);
}
// ...
std::thread t(process, Job{5, 1024});
t.join();                       // std::thread: join by hand
std::cout << "main: joined\n";

Worker::run() calls process() on each of its own jobs. It printed:

job 1: 4096 bytes
main: job 1 is done
job 2: 512 bytes
job 3: 128 bytes
job 4: 64 bytes
job 5: 1024 bytes
main: joined

~jthread() calls request_stop(), then join() ([thread.jthread.class]); std::thread takes the same arguments and leaves the join() to you.

Forget to join a std::thread and the program ends

Destroying a std::thread that is still joinable calls std::terminate ([thread.thread.destr]). The shortest way there:

int main() {
    std::thread worker(process, Job{1, 4096});
    std::cout << "leaving main" << std::endl;
}   // ~thread(): still joinable, so std::terminate()

All four printed leaving main; what came after is each runtime’s own:

No tool caught it: no warning at /W4 or -Wall -Wextra, nothing from MSVC’s /analyze, and style findings only from clang-tidy 19.1.5 with every check on.

The usual way there: the join() is written, but an exception or an early return skips it:

std::size_t total_bytes(const std::vector<Job>& jobs) {
    std::size_t bytes = 0;
    std::thread worker([&] {
        for (const Job& job : jobs)
            bytes += job.size;
    });
    check(jobs);        // throws: worker.join() is never reached
    worker.join();
    return bytes;
}

check() throws for an empty job, and the caller’s catch (const std::exception&) never ran: unwinding destroyed the joinable worker first, and the release and Linux builds ended as above. libstdc++ printed terminate called without an active exception here too: to it an exception is active only once a catch has it ([except.handle]), and this one was still on its way to the caller’s handler. The message points away from the cause.

As a std::jthread, worker joins on the way out and the exception reaches the caller: all four printed caught: job 2 is empty.

Pass arguments: copies, std::ref and lambda captures

The constructor copies (or moves) every argument in the calling thread, and the function receives those copies ([thread.thread.constr]). A const& parameter binds to the thread’s copy unless the argument is wrapped in std::cref:

void tally(const std::vector<Job>& jobs, std::size_t& bytes) {
    for (const Job& job : jobs)
        bytes += job.size;
}
// ...
std::thread first(tally, jobs, std::ref(bytes));  // jobs: a copy
jobs.push_back({3, 128});    // first counts its own copy
first.join();
std::cout << "first: " << bytes << " bytes\n";
// ...
bytes = 0;
std::thread second(tally, std::cref(jobs), std::ref(bytes));
second.join();               // jobs stays untouched until here
std::cout << "second: " << bytes << " bytes\n";

It printed first: 4608 bytes and second: 4736 bytes. A non-const reference parameter without std::ref does not compile:

std::thread worker(tally, jobs, bytes);  // error: needs std::ref

No compiler’s message names std::ref. GCC’s comes closest:

error: static assertion failed: std::thread arguments must be invocable after conversion to rvalues

libc++ fails a static_assert with an empty message; MSVC reports error C2672: 'invoke': no matching overloaded function found.

Counted with a Batch type whose constructors record the thread they run on, all three libraries did the same:

So a copy constructor that throws does so in the calling thread: the constructor throws, no thread starts, and the caller’s catch gets it (all four, in every mode built). A move-only argument goes in with std::move: std::thread worker(process, std::move(job)); handed a std::unique_ptr<Job> to the thread and left main’s pointer empty.

A lambda that captures by reference shares the caller’s objects instead, and their lifetime is then yours (CP.31: pass small amounts of data by value). A jthread joins in its destructor, and locals are destroyed in reverse order of declaration, so what the thread uses comes first:

struct Totals {
    std::size_t bytes = 0;
    ~Totals() { std::cout << "totals destroyed\n"; }
};

void run(const std::vector<Job>& jobs) {
    Totals totals;                  // declared first: destroyed last
    std::jthread worker([&] {
        for (const Job& job : jobs)
            totals.bytes += job.size;
        std::cout << "worker done: " << totals.bytes << " bytes\n";
    });
}   // ~jthread() joins the worker, then ~Totals() runs

All four printed worker done: 4736 bytes before totals destroyed. Here the compiler enforces the order: declared after worker, totals cannot be captured at all, and all four rejected it.

A class is where it bites. Members are constructed in declaration order and destroyed in reverse ([class.base.init], [class.dtor]), so a std::jthread member declared before the members its thread uses starts before they are constructed and joins after they are destroyed. A thread that touches them in either window has undefined behavior:

class Pipeline {
// ...
private:
    std::jthread worker;   // declared first: destroyed last
    Totals totals;         // declared last: destroyed first
};

This thread never touches totals: it waits for its stop, then prints. All four printed totals destroyed before worker: stop requested. Declare the jthread member last.

Get a result back from a thread

The function’s return value is thrown away. Write the result into an object the caller owns, one slot per thread, and read it after the join: the end of the thread synchronizes with the return of join() ([thread.thread.member]), which is what makes the read safe. total() adds up the sizes in a span of jobs:

std::span<const Job> all(jobs);
std::size_t half = all.size() / 2;
std::array<std::size_t, 2> bytes{};    // one slot per thread
{
    std::jthread a([&] { bytes[0] = total(all.first(half)); });
    std::jthread b([&] { bytes[1] = total(all.subspan(half)); });
}   // both joined: now the slots can be read
std::cout << bytes[0] << " + " << bytes[1] << " = "
          << bytes[0] + bytes[1] << " bytes\n";

It printed 4608 + 2176 = 6784 bytes. Two threads writing one object, or a read of a slot before its thread is joined, with no mutex, atomic or join to order them, is a data race, and a data race is undefined behavior ([intro.races]). Share data through a std::mutex or a std::atomic; for one result from one task, std::async hands it back in a future.

For any number of threads, fill a std::vector<std::jthread> with emplace_back; its destructor joins every one:

std::vector<std::size_t> sizes{4096, 512, 128, 2048};
std::vector<std::size_t> doubled(sizes.size());   // one slot per thread
{
    std::vector<std::jthread> workers;
    for (std::size_t i = 0; i < sizes.size(); ++i)
        workers.emplace_back([&, i] { doubled[i] = sizes[i] * 2; });
}   // ~vector(): every ~jthread() joins

All four printed the sum, 13568 bytes.

A jthread does not make the result readable at return: the return expression is evaluated before the locals’ destructors run. This worker loops until its stop is requested:

std::size_t read(const std::size_t& bytes) {
    std::cout << "return: bytes read\n";
    return bytes;
}

std::size_t total_bytes() {
    std::size_t bytes = 0;
    std::jthread worker([](std::stop_token token) {
        while (!token.stop_requested())
            std::this_thread::sleep_for(std::chrono::milliseconds(5));
        std::cout << "worker: stopped by ~jthread()\n";
    });
    return read(bytes);   // evaluated before ~jthread() runs
}

All four printed return: bytes read before worker: stopped by ~jthread(). A function that returns what its worker wrote calls worker.join() before the return, jthread or not.

An exception that leaves a thread ends the program

An exception that leaves the thread’s function calls std::terminate ([thread.thread.constr]), with std::jthread too: the same end as an exception thrown out of a noexcept destructor, which a destructor is by default since C++11. A try around the constructor cannot catch it, because it is thrown on the other thread:

void process(const Job& job) {
    if (job.size == 0)
        throw std::invalid_argument("job " + std::to_string(job.id)
                                    + " is empty");
}

int main() {
    std::cout << "starting job 2" << std::endl;
    try {
        std::jthread worker(process, Job{2, 0});
    } catch (const std::exception& e) {
        std::cout << "caught: " << e.what() << '\n';  // never printed
    }
}

All four printed starting job 2. libstdc++ then printed:

terminate called after throwing an instance of 'std::invalid_argument'
  what():  job 2 is empty

libc++ printed libc++abi: terminating due to uncaught exception of type std::invalid_argument: job 2 is empty; both ended with SIGABRT. Microsoft’s release runtime again printed nothing and exited with 0xC0000409.

Catch inside the function, and hand the exception to the caller as a std::exception_ptr, rethrown after the join:

std::exception_ptr error;           // written by the worker only
{
    std::jthread worker([&error] {
        try {
            process(Job{2, 0});
        } catch (...) {
            error = std::current_exception();
        }
    });
}   // joined: now error can be read
try {
    if (error)
        std::rethrow_exception(error);
} catch (const std::exception& e) {
    std::cout << "caught in main: " << e.what() << '\n';
}

All four printed caught in main: job 2 is empty.

Stop a thread: std::stop_token and request_stop()

The standard library has no call that kills a thread (that would be a platform call on native_handle()); stopping is cooperative. A jthread passes its own std::stop_token to a function whose first parameter takes one; request_stop(), or the destructor, sets it:

void serve(std::stop_token token, int id) {
    using namespace std::chrono_literals;
    while (!token.stop_requested())
        std::this_thread::sleep_for(5ms);   // look for work
    std::cout << "worker " << id << ": stop requested\n";
}
// ...
std::jthread first(serve, 1);   // runs serve(token, 1)
first.request_stop();
first.join();
std::cout << "main: worker 1 joined\n";
// ...
{
    std::jthread second(serve, 2);
}   // ~jthread(): request_stop(), then join()
std::cout << "main: worker 2 joined\n";

A member function that takes a std::stop_token does not receive it from std::jthread t(&Worker::run, &worker);: the token would have to come before the object, and all four rejected the call. A lambda that takes the token and passes it on worked on all four: std::jthread t([&worker](std::stop_token token) { worker.run(token); });.

A worker asleep in std::condition_variable_any::wait(lock, token, pred) is woken by the stop request: the call returns at once with the value of pred() ([thread.condvarany.intwait]):

std::mutex mutex;
std::condition_variable_any job_added;
std::vector<Job> queue;          // guarded by mutex
std::size_t bytes = 0;           // the worker's; read after join

std::jthread worker([&](std::stop_token token) {
    std::unique_lock lock(mutex);
    while (job_added.wait(lock, token,
                          [&] { return !queue.empty(); })) {
        bytes += queue.back().size;
        queue.pop_back();
    }
    // wait() returned false: a stop was requested
    std::cout << "worker: stopped, " << queue.size()
              << " jobs waiting\n";
});
// ...
worker.request_stop();           // wakes the wait
worker.join();
std::cout << "main: " << bytes << " bytes processed\n";

With one 4096-byte job queued before the stop, all four printed worker: stopped, 0 jobs waiting. Plain std::condition_variable has no such overload: all four rejected the call.

To run code at the moment of the stop, register a std::stop_callback on the token. Registered before the stop, it runs inside request_stop(), on the requesting thread; registered after, it runs at once, in its own constructor. Here serve takes the token alone:

const std::thread::id main_id = std::this_thread::get_id();
std::jthread worker(serve);

std::stop_callback on_stop(worker.get_stop_token(), [&] {
    bool here = std::this_thread::get_id() == main_id;
    std::cout << "on_stop runs in main's thread: "
              << (here ? "yes" : "no") << '\n';
});
std::cout << "requesting a stop\n";
worker.request_stop();      // runs on_stop before it returns
std::cout << "request_stop() returned\n";

std::cout << "registering a callback after the stop\n";
std::stop_callback late(worker.get_stop_token(), [] {
    std::cout << "late: runs at once, in its constructor\n";
});
std::cout << "late is constructed\n";

worker.join();
std::cout << "main: joined\n";

It printed:

requesting a stop
on_stop runs in main's thread: yes
request_stop() returned
registering a callback after the stop
late: runs at once, in its constructor
late is constructed
main: joined

join, detach and joinable

joinable() returns get_id() != std::thread::id(): true while the object owns a thread it has not joined or detached ([thread.thread.member]). All four agreed in every state:

A second join() throws std::system_error with errc::invalid_argument on all four. Only what() differs:

• Microsoft’s STL: invalid argument: invalid argument
• libstdc++: Invalid argument
• libc++: thread::join failed: Invalid argument

join() has no timeout. To wait at most so long, request a stop, or wait with wait_for on a condition variable or a future.

After detach() the object no longer represents the thread, and no join() can wait for it: only a signal the thread sends itself, through a condition variable or a future, tells you it ended. Hence the Core Guidelines’ CP.26, “Don’t detach() a thread”: a detached thread is hard to monitor and to communicate with.

When main returns, std::exit destroys the static objects while a detached thread may still run; if the thread then uses one of them, or most of the standard library (std::cout included), the behavior is undefined ([basic.start.term]). The standard does not say whether the thread is stopped.

Sleep, thread ids and hardware_concurrency

A thread acts on itself through std::this_thread, and on the thread an object owns through its members:

An id is unique among threads that are running or can still be joined; the library may reuse the id of a thread that has ended and can no longer be joined ([thread.thread.id]). Sleeping is not a way to wait for another thread: join() waits for it to end, and a condition variable waits for it to signal.

What you need to build it

std::thread and std::jthread are in <thread>, the stop tokens in <stop_token>. As C++17, all four rejected std::jthread; GCC adds note: 'std::jthread' is only available from C++20 onwards. As C++20, __cpp_lib_jthread was 201911 on all three libraries. The first releases with std::jthread:

Clang 23.1 with libc++ built every sample without -fexperimental-library. On Linux, no build passed -pthread, and all ran: Compiler Explorer’s glibc is 2.39, and since 2.34 libpthread is part of libc (the glibc 2.34 announcement: “New applications do not need to link with -lpthread”). On glibc 2.33 or older, g++ without the flag fails the link with undefined reference to 'pthread_create'.

std::thread or std::jthread: which one to write

Before the review:

• Every std::thread is joined on every path, exceptions included, or is a std::jthread.
• References go in through std::ref or std::cref; every other argument is copied first.
• What a thread uses by reference is declared before the thread.
• A result is read after join(), from a slot only that thread writes.
• The thread’s function catches its own exceptions, and a std::exception_ptr carries one out.

More answers about threads and shared data are in Concurrency.