[thread.jthread.class] - C++17 → C++20

Files changed (1) hide show

tmp/tmpgsl86izb/{from.md → to.md} +256 -0

tmp/tmpgsl86izb/{from.md → to.md} RENAMED Viewed

	@@ -0,0 +1,256 @@

+### Class `jthread` <a id="thread.jthread.class">[[thread.jthread.class]]</a>
+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.
+``` cpp
+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
+  };
+}
+```
+#### Constructors, move, and assignment <a id="thread.jthread.cons">[[thread.jthread.cons]]</a>
+``` cpp
+jthread() noexcept;
+```
+*Effects:* Constructs a `jthread` object that does not represent a
+thread of execution.
+*Ensures:* `get_id() == id()` is `true` and `ssource.stop_possible()` is
+`false`.
+``` cpp
+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`:
+- `is_constructible_v<decay_t<F>, F>`,
+- `(is_constructible_v<decay_t<Args>, Args> && ...)`,
+- `is_move_constructible_v<decay_t<F>>`,
+- `(is_move_constructible_v<decay_t<Args>> && ...)`, and
+- `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
+``` cpp
+invoke(decay-copy(std::forward<F>(f)), get_stop_token(),
+       decay-copy(std::forward<Args>(args))...)
+```
+if that expression is well-formed, otherwise
+``` cpp
+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`.
+*Ensures:* `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:*
+- `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.
+``` cpp
+jthread(jthread&& x) noexcept;
+```
+*Ensures:* `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`.
+``` cpp
+~jthread();
+```
+*Effects:* If `joinable()` is `true`, calls `request_stop()` and then
+`join()`.
+[*Note 3*: Operations on `*this` are not synchronized. — *end note*]
+``` cpp
+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.
+*Ensures:* `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`.
+#### Members <a id="thread.jthread.mem">[[thread.jthread.mem]]</a>
+``` cpp
+void swap(jthread& x) noexcept;
+```
+*Effects:* Exchanges the values of `*this` and `x`.
+``` cpp
+[[nodiscard]] bool joinable() const noexcept;
+```
+*Returns:* `get_id() != id()`.
+``` cpp
+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*]
+*Ensures:* The thread represented by `*this` has completed.
+`get_id() == id()`.
+*Throws:* `system_error` when an exception is
+required [[thread.req.exception]].
+*Error conditions:*
+- `resource_deadlock_would_occur` — if deadlock is detected or
+  `get_id() == this_thread::get_id()`.
+- `no_such_process` — if the thread is not valid.
+- `invalid_argument` — if the thread is not joinable.
+``` cpp
+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.
+*Ensures:* `get_id() == id()`.
+*Throws:* `system_error` when an exception is
+required [[thread.req.exception]].
+*Error conditions:*
+- `no_such_process` — if the thread is not valid.
+- `invalid_argument` — if the thread is not joinable.
+``` cpp
+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`.
+#### Stop token handling <a id="thread.jthread.stop">[[thread.jthread.stop]]</a>
+``` cpp
+[[nodiscard]] stop_source get_stop_source() noexcept;
+```
+*Effects:* Equivalent to: `return ssource;`
+``` cpp
+[[nodiscard]] stop_token get_stop_token() const noexcept;
+```
+*Effects:* Equivalent to: `return ssource.get_token();`
+``` cpp
+bool request_stop() noexcept;
+```
+*Effects:* Equivalent to: `return ssource.request_stop();`
+#### Specialized algorithms <a id="thread.jthread.special">[[thread.jthread.special]]</a>
+``` cpp
+friend void swap(jthread& x, jthread& y) noexcept;
+```
+*Effects:* Equivalent to: `x.swap(y)`.
+#### Static members <a id="thread.jthread.static">[[thread.jthread.static]]</a>
+``` cpp
+[[nodiscard]] static unsigned int hardware_concurrency() noexcept;
+```
+*Returns:* `thread::hardware_concurrency()`.

Diff to HTML by rtfpessoa