C++ Reference ยท Concurrency
C++ std::jthread class
Reference for std::jthread (C++20): a thread that joins automatically in its destructor and receives a std::stop_token for cooperative cancellation.
std::jthread (header <thread>, C++20) is std::thread with two safety features. Its destructor requests the thread to stop and then joins it, so forgetting join() no longer terminates the program. And it owns a std::stop_source: if the thread function takes a std::stop_token as its first parameter, jthread passes one in, and the owner can ask the thread to finish with request_stop().
Everything else, such as join(), detach(), joinable() and get_id(), works like std::thread. The class is move-only.
std::jthread worker([](std::stop_token st) { while (!st.stop_requested()) { /* work */ } }); // leaving the scope requests a stop and joins
Try it
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.
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.
Syntax
template<class F, class... Args> explicit jthread(F&& f, Args&&... args); // if f is invocable with (stop_token, args...), a token is passed as the first argument bool request_stop() noexcept; std::stop_source get_stop_source() noexcept; std::stop_token get_stop_token() const noexcept; void join(); void detach(); bool joinable() const noexcept;
| Name | Description |
|---|---|
f, args... |
The callable and arguments. If f(stop_token, args...) is valid, the token is supplied automatically. |
request_stop() |
Sets the stop state. Returns true if this call made the request, false if one had been made already. |
get_stop_token() |
A token you can hand to other code or register callbacks on. |
get_stop_source() |
The source, which can request a stop from elsewhere. |
join() |
Waits for the thread. Also what the destructor does after request_stop(). |
Errors: like std::thread: a failed start throws std::system_error, and an exception that escapes the thread function calls std::terminate.
Usage notes
- Stopping is cooperative.
request_stop()only sets a flag. The thread must checkstop_requested()regularly (or use astd::stop_callback, or a condition variable wait that takes a token). - The destructor requests a stop first, so a worker that loops until stopped ends cleanly. A worker that ignores the token still blocks the destructor until it returns on its own.
- Prefer
jthreadoverthreadin new code. The only reason to keepstd::threadis a toolchain without C++20 library support or a need to avoid the extra stop-state allocation. - Detached
jthreadloses automatic joining, and the stop token no longer reaches an owner. Rarely a good idea. - Passing the token by reference to others: copy the
stop_token(it is cheap, shared state) into helpers rather than passing thejthread. - Waiting with a token:
std::condition_variable_any::wait(lock, stop_token, predicate)wakes up when a stop is requested, so a blocked worker stops promptly. - Races on shared data are still your responsibility; see mutexes and atomics.