32 Thread support library [thread]

32.4 Threads [thread.threads]

32.4.4 Class jthread [thread.jthread.class]

32.4.4.1 General [thread.jthread.class.general]

The class jthread provides a mechanism to create a new thread of execution.

The functionality is the same as for class thread ([thread.thread.class]) with the additional abilities to provide a stop_token ([thread.stoptoken]) to the new thread of execution, make stop requests, and automatically join.

namespace std { class jthread { public: // types using id = thread::id; using native_handle_type = thread::native_handle_type; // [thread.jthread.cons], constructors, move, and assignment jthread() noexcept; template<class F, class... Args> explicit jthread(F&& f, Args&&... args); ~jthread(); jthread(const jthread&) = delete; jthread(jthread&&) noexcept; jthread& operator=(const jthread&) = delete; jthread& operator=(jthread&&) noexcept; // [thread.jthread.mem], members void swap(jthread&) noexcept; [[nodiscard]] bool joinable() const noexcept; void join(); void detach(); [[nodiscard]] id get_id() const noexcept; [[nodiscard]] native_handle_type native_handle(); // see [thread.req.native] // [thread.jthread.stop], stop token handling [[nodiscard]] stop_source get_stop_source() noexcept; [[nodiscard]] stop_token get_stop_token() const noexcept; bool request_stop() noexcept; // [thread.jthread.special], specialized algorithms friend void swap(jthread& lhs, jthread& rhs) noexcept; // [thread.jthread.static], static members [[nodiscard]] static unsigned int hardware_concurrency() noexcept; private: stop_source ssource; // exposition only }; }

32.4.4.2 Constructors, move, and assignment [thread.jthread.cons]

🔗

jthread() noexcept;

Effects: Constructs a jthread object that does not represent a thread of execution.

Postconditions: get_id() == id() is true and ssource.stop_possible() is false.

🔗

template<class F, class... Args> explicit jthread(F&& f, Args&&... args);

Constraints: remove_cvref_t<F> is not the same type as jthread.

Mandates: The following are all true:

(4.1)
is_constructible_v<decay_t<F>, F>,
(4.2)
(is_constructible_v<decay_t<Args>, Args> && ...),
(4.3)
is_move_constructible_v<decay_t<F>>,
(4.4)
(is_move_constructible_v<decay_t<Args>> && ...), and
(4.5)
is_invocable_v<decay_t<F>, decay_t<Args>...> ||

is_invocable_v<decay_t<F>, stop_token, decay_t<Args>...>.

Preconditions: decay_t<F> and each type in decay_t<Args> meet the Cpp17MoveConstructible requirements.

Effects: Initializes ssource.

The new thread of execution executes invoke(decay-copy(std::forward<F>(f)), get_stop_token(), decay-copy(std::forward<Args>(args))...) if that expression is well-formed, otherwise invoke(decay-copy(std::forward<F>(f)), decay-copy(std::forward<Args>(args))...) with the calls to decay-copy being evaluated in the constructing thread.

Any return value from this invocation is ignored.

[Note 1:

This implies that any exceptions not thrown from the invocation of the copy of f will be thrown in the constructing thread, not the new thread.

— end note]

If the invoke expression exits via an exception, terminate is called.

Synchronization: The completion of the invocation of the constructor synchronizes with the beginning of the invocation of the copy of f.

Postconditions: get_id() != id() is true and ssource.stop_possible() is true and *this represents the newly started thread.

[Note 2:

The calling thread can make a stop request only once, because it cannot replace this stop token.

— end note]

Throws: system_error if unable to start the new thread.

Error conditions:

(10.1)
resource_unavailable_try_again — the system lacked the necessary resources to create another thread, or the system-imposed limit on the number of threads in a process would be exceeded.

🔗

jthread(jthread&& x) noexcept;

Postconditions: x.get_id() == id() and get_id() returns the value of x.get_id() prior to the start of construction.

ssource has the value of x.ssource prior to the start of construction and x.ssource.stop_possible() is false.

🔗

~jthread();

Effects: If joinable() is true, calls request_stop() and then join().

[Note 3:

Operations on *this are not synchronized.

— end note]

🔗

jthread& operator=(jthread&& x) noexcept;

Effects: If joinable() is true, calls request_stop() and then join().

Assigns the state of x to *this and sets x to a default constructed state.

Postconditions: x.get_id() == id() and get_id() returns the value of x.get_id() prior to the assignment.

ssource has the value of x.ssource prior to the assignment and x.ssource.stop_possible() is false.

Returns: *this.

32.4.4.3 Members [thread.jthread.mem]

🔗

void swap(jthread& x) noexcept;

Effects: Exchanges the values of *this and x.

🔗

[[nodiscard]] bool joinable() const noexcept;

Returns: get_id() != id().

🔗

void join();

Effects: Blocks until the thread represented by *this has completed.

Synchronization: The completion of the thread represented by *this synchronizes with ([intro.multithread]) the corresponding successful join() return.

[Note 1:

Operations on *this are not synchronized.

— end note]

Postconditions: The thread represented by *this has completed.

get_id() == id().

Throws: system_error when an exception is required ([thread.req.exception]).

Error conditions:

(7.1)
resource_deadlock_would_occur — if deadlock is detected or get_id() == this_thread::get_id().
(7.2)
no_such_process — if the thread is not valid.
(7.3)
invalid_argument — if the thread is not joinable.

🔗

void detach();

Effects: The thread represented by *this continues execution without the calling thread blocking.

When detach() returns, *this no longer represents the possibly continuing thread of execution.

When the thread previously represented by *this ends execution, the implementation releases any owned resources.

Postconditions: get_id() == id().

Throws: system_error when an exception is required ([thread.req.exception]).

Error conditions:

(11.1)
no_such_process — if the thread is not valid.
(11.2)
invalid_argument — if the thread is not joinable.

🔗

id get_id() const noexcept;

Returns: A default constructed id object if *this does not represent a thread, otherwise this_thread::get_id() for the thread of execution represented by *this.

32.4.4.4 Stop token handling [thread.jthread.stop]

🔗

[[nodiscard]] stop_source get_stop_source() noexcept;

Effects: Equivalent to: return ssource;

🔗

[[nodiscard]] stop_token get_stop_token() const noexcept;

Effects: Equivalent to: return ssource.get_token();

🔗

bool request_stop() noexcept;

Effects: Equivalent to: return ssource.request_stop();

32.4.4.5 Specialized algorithms [thread.jthread.special]

🔗

friend void swap(jthread& x, jthread& y) noexcept;

Effects: Equivalent to: x.swap(y).

32.4.4.6 Static members [thread.jthread.static]

🔗

[[nodiscard]] static unsigned int hardware_concurrency() noexcept;

Returns: thread::hardware_concurrency().