NAME¶

std::jthread - std::jthread

Synopsis¶

Defined in header <thread>
class jthread; (since C++20)

The class jthread represents a single thread of execution. It has the same general
behavior as std::thread, except that jthread automatically rejoins on destruction,
and can be cancelled/stopped in certain situations.

Threads begin execution immediately upon construction of the associated thread
object (pending any OS scheduling delays), starting at the top-level function
provided as a constructor argument. The return value of the top-level function is
ignored and if it terminates by throwing an exception, std::terminate is called. The
top-level function may communicate its return value or an exception to the caller
via std::promise or by modifying shared variables (which may require
synchronization, see std::mutex and std::atomic)

Unlike std::thread, the jthread logically holds an internal private member of type
std::stop_source, which maintains a shared stop-state. The jthread constructor
accepts a function that takes a std::stop_token as its first argument, which will be
passed in by the jthread from its internal stop_source. This allows the function to
check if stop has been requested during its execution, and return if it has.

std::jthread objects may also be in the state that does not represent any thread
(after default construction, move from, detach, or join), and a thread of execution
may be not associated with any jthread objects (after detach).

No two std::jthread objects may represent the same thread of execution; std::jthread
is not CopyConstructible or CopyAssignable, although it is MoveConstructible and
MoveAssignable.

Member types¶

Member type Definition
id std::thread::id
native_handle_type(not always present) std::thread::native_handle_type

Member functions¶

constructor constructs new jthread object
(public member function)
if joinable() is true, calls request_stop() and then join(); in
destructor either case destructs the jthread object.
(public member function)
operator= moves the jthread object
(public member function)

Observers¶

checks whether the thread is joinable, i.e. potentially running
joinable in parallel context
(public member function)
get_id returns the id of the thread
(public member function)
native_handle returns the underlying implementation-defined thread handle
(public member function)
hardware_concurrency returns the number of concurrent threads supported by the
[static] implementation
(public static member function)

Operations¶

join waits for the thread to finish its execution
(public member function)
permits the thread to execute independently from the thread
detach handle
(public member function)
swap swaps two jthread objects
(public member function)
Stop token handling
returns a stop_source object associated with the shared stop
get_stop_source state of the thread
(public member function)
returns a stop_token associated with the shared stop state of
get_stop_token the thread
(public member function)
request_stop requests execution stop via the shared stop state of the thread
(public member function)

Non-member functions¶

swap(std::jthread) specializes the std::swap algorithm
(C++20) (function)

Notes¶

Feature-test macro: __cpp_lib_jthread

See also¶

thread manages a separate thread
(C++11) (class)