cppdraft_translate/cppdraft/thread/jthread/class.md

[thread.jthread.class]

32 Concurrency 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]

1

#

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:// typesusing 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], membersvoid swap(jthread&) noexcept; bool joinable() const noexcept; void join(); void detach(); id get_id() const noexcept; native_handle_type native_handle(); // see [thread.req.native]// [thread.jthread.stop], stop token handling stop_source get_stop_source() noexcept; stop_token get_stop_token() const noexcept; bool request_stop() noexcept; // [thread.jthread.special], specialized algorithmsfriend void swap(jthread& lhs, jthread& rhs) noexcept; // [thread.jthread.static], static membersstatic unsigned int hardware_concurrency() noexcept; private: stop_source ssource; // exposition only};}

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

🔗

jthread() noexcept;

1

#

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

2

#

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

🔗

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

3

#

Constraints: remove_cvref_t is not the same type as jthread.

4

#

Mandates: The following are all true:

• (4.1)

is_constructible_v<decay_t, F>,

• (4.2)

(is_constructible_v<decay_t, Args> && ...), and

• (4.3)

is_invocable_v<decay_t, decay_t...> ||
is_invocable_v<decay_t, stop_token, decay_t...>.

5

#

Effects: Initializes ssource.

The new thread of execution executesinvoke(auto(std::forward(f)), get_stop_token(), // for invoke, see [func.invoke]auto(std::forward(args))...) if that expression is well-formed, otherwiseinvoke(auto(std::forward(f)), auto(std::forward(args))...) with the values produced by auto being materialized ([conv.rval]) 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.

6

#

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

7

#

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]

8

#

Throws: system_error if unable to start the new thread.

9

#

Error conditions:

• (9.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;

10

#

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();

11

#

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;

12

#

Effects: If &x == this is true, there are no effects.

Otherwise, if joinable() is true, calls request_stop() and then join(), then assigns the state of x to *this and sets x to a default constructed state.

13

#

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

ssource has the value of x.ssource prior to the assignment.

14

#

Returns: *this.

32.4.4.3 Members [thread.jthread.mem]

🔗

void swap(jthread& x) noexcept;

1

#

Effects: Exchanges the values of *this and x.

🔗

bool joinable() const noexcept;

2

#

Returns: get_id() != id().

🔗

void join();

3

#

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

4

#

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]

5

#

Postconditions: The thread represented by *this has completed.

get_id() == id().

6

#

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

7

#

Error conditions:

• (7.1)

  resource_deadlock_would_occur — if deadlock is detected orget_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();

8

#

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.

9

#

Postconditions: get_id() == id().

10

#

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

11

#

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;

12

#

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]

🔗

stop_source get_stop_source() noexcept;

1

#

Effects: Equivalent to: return ssource;

🔗

stop_token get_stop_token() const noexcept;

2

#

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

🔗

bool request_stop() noexcept;

3

#

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

32.4.4.5 Specialized algorithms [thread.jthread.special]

🔗

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

1

#

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

32.4.4.6 Static members [thread.jthread.static]

🔗

static unsigned int hardware_concurrency() noexcept;

1

#

Returns: thread​::​hardware_concurrency().