Skip to content
Tutorials Center
My learning

Topics

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.

C++
std::jthread worker([](std::stop_token st) {
    while (!st.stop_requested()) { /* work */ }
});
// leaving the scope requests a stop and joins

Try it

C++ Automatic join

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.

C++ Stopping a loop 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.

Syntax

C++
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 check stop_requested() regularly (or use a std::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 jthread over thread in new code. The only reason to keep std::thread is a toolchain without C++20 library support or a need to avoid the extra stop-state allocation.
  • Detached jthread loses 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 the jthread.
  • 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.