[thread.stoptoken] - C++17 → C++20

Files changed (1) hide show

tmp/tmpsyupry8r/{from.md → to.md} +441 -0

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

	@@ -0,0 +1,441 @@

+## Stop tokens <a id="thread.stoptoken">[[thread.stoptoken]]</a>
+### Introduction <a id="thread.stoptoken.intro">[[thread.stoptoken.intro]]</a>
+This clause describes components that can be used to asynchonously
+request that an operation stops execution in a timely manner, typically
+because the result is no longer required. Such a request is called a
+*stop request*.
+`stop_source`, `stop_token`, and `stop_callback` implement semantics of
+shared ownership of a *stop state*. Any `stop_source`, `stop_token`, or
+`stop_callback` that shares ownership of the same stop state is an
+*associated* `stop_source`, `stop_token`, or `stop_callback`,
+respectively. The last remaining owner of the stop state automatically
+releases the resources associated with the stop state.
+A `stop_token` can be passed to an operation which can either
+- actively poll the token to check if there has been a stop request, or
+- register a callback using the `stop_callback` class template which
+  will be called in the event that a stop request is made.
+A stop request made via a `stop_source` will be visible to all
+associated `stop_token` and `stop_source` objects. Once a stop request
+has been made it cannot be withdrawn (a subsequent stop request has no
+effect).
+Callbacks registered via a `stop_callback` object are called when a stop
+request is first made by any associated `stop_source` object.
+Calls to the functions `request_stop`, `stop_requested`, and
+`stop_possible` do not introduce data races. A call to `request_stop`
+that returns `true` synchronizes with a call to `stop_requested` on an
+associated `stop_token` or `stop_source` object that returns `true`.
+Registration of a callback synchronizes with the invocation of that
+callback.
+### Header `<stop_token>` synopsis <a id="thread.stoptoken.syn">[[thread.stoptoken.syn]]</a>
+``` cpp
+namespace std {
+  // [stoptoken], class stop_token
+  class stop_token;
+  // [stopsource], class stop_source
+  class stop_source;
+  // no-shared-stop-state indicator
+  struct nostopstate_t {
+    explicit nostopstate_t() = default;
+  };
+  inline constexpr nostopstate_t nostopstate{};
+  // [stopcallback], class stop_callback
+  template<class Callback>
+  class stop_callback;
+}
+```
+### Class `stop_token` <a id="stoptoken">[[stoptoken]]</a>
+The class `stop_token` provides an interface for querying whether a stop
+request has been made (`stop_requested`) or can ever be made
+(`stop_possible`) using an associated `stop_source` object (
+[[stopsource]]). A `stop_token` can also be passed to a `stop_callback`
+[[stopcallback]] constructor to register a callback to be called when a
+stop request has been made from an associated `stop_source`.
+``` cpp
+namespace std {
+  class stop_token {
+  public:
+    // [stoptoken.cons], constructors, copy, and assignment
+    stop_token() noexcept;
+    stop_token(const stop_token&) noexcept;
+    stop_token(stop_token&&) noexcept;
+    stop_token& operator=(const stop_token&) noexcept;
+    stop_token& operator=(stop_token&&) noexcept;
+    ~stop_token();
+    void swap(stop_token&) noexcept;
+    // [stoptoken.mem], stop handling
+    [[nodiscard]] bool stop_requested() const noexcept;
+    [[nodiscard]] bool stop_possible() const noexcept;
+    [[nodiscard]] friend bool operator==(const stop_token& lhs, const stop_token& rhs) noexcept;
+    friend void swap(stop_token& lhs, stop_token& rhs) noexcept;
+  };
+}
+```
+#### Constructors, copy, and assignment <a id="stoptoken.cons">[[stoptoken.cons]]</a>
+``` cpp
+stop_token() noexcept;
+```
+*Ensures:* `stop_possible()` is `false` and `stop_requested()` is
+`false`.
+[*Note 1*: Because the created `stop_token` object can never receive a
+stop request, no resources are allocated for a stop
+state. — *end note*]
+``` cpp
+stop_token(const stop_token& rhs) noexcept;
+```
+*Ensures:* `*this == rhs` is `true`.
+[*Note 2*: `*this` and `rhs` share the ownership of the same stop
+state, if any. — *end note*]
+``` cpp
+stop_token(stop_token&& rhs) noexcept;
+```
+*Ensures:* `*this` contains the value of `rhs` prior to the start of
+construction and `rhs.stop_possible()` is `false`.
+``` cpp
+~stop_token();
+```
+*Effects:* Releases ownership of the stop state, if any.
+``` cpp
+stop_token& operator=(const stop_token& rhs) noexcept;
+```
+*Effects:* Equivalent to: `stop_token(rhs).swap(*this)`.
+*Returns:* `*this`.
+``` cpp
+stop_token& operator=(stop_token&& rhs) noexcept;
+```
+*Effects:* Equivalent to: `stop_token(std::move(rhs)).swap(*this)`.
+*Returns:* `*this`.
+``` cpp
+void swap(stop_token& rhs) noexcept;
+```
+*Effects:* Exchanges the values of `*this` and `rhs`.
+#### Members <a id="stoptoken.mem">[[stoptoken.mem]]</a>
+``` cpp
+[[nodiscard]] bool stop_requested() const noexcept;
+```
+*Returns:* `true` if `*this` has ownership of a stop state that has
+received a stop request; otherwise, `false`.
+``` cpp
+[[nodiscard]] bool stop_possible() const noexcept;
+```
+*Returns:* `false` if:
+- `*this` does not have ownership of a stop state, or
+- a stop request was not made and there are no associated `stop_source`
+  objects;
+otherwise, `true`.
+#### Non-member functions <a id="stoptoken.nonmembers">[[stoptoken.nonmembers]]</a>
+``` cpp
+[[nodiscard]] bool operator==(const stop_token& lhs, const stop_token& rhs) noexcept;
+```
+*Returns:* `true` if `lhs` and `rhs` have ownership of the same stop
+state or if both `lhs` and `rhs` do not have ownership of a stop state;
+otherwise `false`.
+``` cpp
+friend void swap(stop_token& x, stop_token& y) noexcept;
+```
+*Effects:* Equivalent to: `x.swap(y)`.
+### Class `stop_source` <a id="stopsource">[[stopsource]]</a>
+The class `stop_source` implements the semantics of making a stop
+request. A stop request made on a `stop_source` object is visible to all
+associated `stop_source` and `stop_token` ([[stoptoken]]) objects. Once
+a stop request has been made it cannot be withdrawn (a subsequent stop
+request has no effect).
+``` cpp
+namespace std {
+  // no-shared-stop-state indicator
+  struct nostopstate_t {
+    explicit nostopstate_t() = default;
+  };
+  inline constexpr nostopstate_t nostopstate{};
+  class stop_source {
+  public:
+    // [stopsource.cons], constructors, copy, and assignment
+    stop_source();
+    explicit stop_source(nostopstate_t) noexcept;
+    stop_source(const stop_source&) noexcept;
+    stop_source(stop_source&&) noexcept;
+    stop_source& operator=(const stop_source&) noexcept;
+    stop_source& operator=(stop_source&&) noexcept;
+    ~stop_source();
+    void swap(stop_source&) noexcept;
+    // [stopsource.mem], stop handling
+    [[nodiscard]] stop_token get_token() const noexcept;
+    [[nodiscard]] bool stop_possible() const noexcept;
+    [[nodiscard]] bool stop_requested() const noexcept;
+    bool request_stop() noexcept;
+    [[nodiscard]] friend bool
+      operator==(const stop_source& lhs, const stop_source& rhs) noexcept;
+    friend void swap(stop_source& lhs, stop_source& rhs) noexcept;
+  };
+}
+```
+#### Constructors, copy, and assignment <a id="stopsource.cons">[[stopsource.cons]]</a>
+``` cpp
+stop_source();
+```
+*Effects:* Initialises `*this` to have ownership of a new stop state.
+*Ensures:* `stop_possible()` is `true` and `stop_requested()` is
+`false`.
+*Throws:* `bad_alloc` if memory could not be allocated for the stop
+state.
+``` cpp
+explicit stop_source(nostopstate_t) noexcept;
+```
+*Ensures:* `stop_possible()` is `false` and `stop_requested()` is
+`false`.
+[*Note 1*: No resources are allocated for the state. — *end note*]
+``` cpp
+stop_source(const stop_source& rhs) noexcept;
+```
+*Ensures:* `*this == rhs` is `true`.
+[*Note 2*: `*this` and `rhs` share the ownership of the same stop
+state, if any. — *end note*]
+``` cpp
+stop_source(stop_source&& rhs) noexcept;
+```
+*Ensures:* `*this` contains the value of `rhs` prior to the start of
+construction and `rhs.stop_possible()` is `false`.
+``` cpp
+~stop_source();
+```
+*Effects:* Releases ownership of the stop state, if any.
+``` cpp
+stop_source& operator=(const stop_source& rhs) noexcept;
+```
+*Effects:* Equivalent to: `stop_source(rhs).swap(*this)`.
+*Returns:* `*this`.
+``` cpp
+stop_source& operator=(stop_source&& rhs) noexcept;
+```
+*Effects:* Equivalent to: `stop_source(std::move(rhs)).swap(*this)`.
+*Returns:* `*this`.
+``` cpp
+void swap(stop_source& rhs) noexcept;
+```
+*Effects:* Exchanges the values of `*this` and `rhs`.
+#### Members <a id="stopsource.mem">[[stopsource.mem]]</a>
+``` cpp
+[[nodiscard]] stop_token get_token() const noexcept;
+```
+*Returns:* `stop_token()` if `stop_possible()` is `false`; otherwise a
+new associated `stop_token` object.
+``` cpp
+[[nodiscard]] bool stop_possible() const noexcept;
+```
+*Returns:* `true` if `*this` has ownership of a stop state; otherwise,
+`false`.
+``` cpp
+[[nodiscard]] bool stop_requested() const noexcept;
+```
+*Returns:* `true` if `*this` has ownership of a stop state that has
+received a stop request; otherwise, `false`.
+``` cpp
+bool request_stop() noexcept;
+```
+*Effects:* If `*this` does not have ownership of a stop state, returns
+`false`. Otherwise, atomically determines whether the owned stop state
+has received a stop request, and if not, makes a stop request. The
+determination and making of the stop request are an atomic
+read-modify-write operation [[intro.races]]. If the request was made,
+the callbacks registered by associated `stop_callback` objects are
+synchronously called. If an invocation of a callback exits via an
+exception then `terminate` is called [[except.terminate]].
+[*Note 1*: A stop request includes notifying all condition variables of
+type `condition_variable_any` temporarily registered during an
+interruptible wait [[thread.condvarany.intwait]]. — *end note*]
+*Ensures:* `stop_possible()` is `false` or `stop_requested()` is `true`.
+*Returns:* `true` if this call made a stop request; otherwise `false`.
+#### Non-member functions <a id="stopsource.nonmembers">[[stopsource.nonmembers]]</a>
+``` cpp
+[[nodiscard]] friend bool
+  operator==(const stop_source& lhs, const stop_source& rhs) noexcept;
+```
+*Returns:* `true` if `lhs` and `rhs` have ownership of the same stop
+state or if both `lhs` and `rhs` do not have ownership of a stop state;
+otherwise `false`.
+``` cpp
+friend void swap(stop_source& x, stop_source& y) noexcept;
+```
+*Effects:* Equivalent to: `x.swap(y)`.
+### Class template `stop_callback` <a id="stopcallback">[[stopcallback]]</a>
+``` cpp
+namespace std {
+  template<class Callback>
+  class stop_callback {
+  public:
+    using callback_type = Callback;
+    // [stopcallback.cons], constructors and destructor
+    template<class C>
+    explicit stop_callback(const stop_token& st, C&& cb)
+        noexcept(is_nothrow_constructible_v<Callback, C>);
+    template<class C>
+    explicit stop_callback(stop_token&& st, C&& cb)
+        noexcept(is_nothrow_constructible_v<Callback, C>);
+    ~stop_callback();
+    stop_callback(const stop_callback&) = delete;
+    stop_callback(stop_callback&&) = delete;
+    stop_callback& operator=(const stop_callback&) = delete;
+    stop_callback& operator=(stop_callback&&) = delete;
+  private:
+    Callback callback;      // exposition only
+  };
+  template<class Callback>
+  stop_callback(stop_token, Callback) -> stop_callback<Callback>;
+}
+```
+*Mandates:* `stop_callback` is instantiated with an argument for the
+template parameter `Callback` that satisfies both `invocable` and
+`destructible`.
+*Preconditions:* `stop_callback` is instantiated with an argument for
+the template parameter `Callback` that models both `invocable` and
+`destructible`.
+#### Constructors and destructor <a id="stopcallback.cons">[[stopcallback.cons]]</a>
+``` cpp
+template<class C>
+explicit stop_callback(const stop_token& st, C&& cb)
+  noexcept(is_nothrow_constructible_v<Callback, C>);
+template<class C>
+explicit stop_callback(stop_token&& st, C&& cb)
+  noexcept(is_nothrow_constructible_v<Callback, C>);
+```
+*Constraints:* `Callback` and `C` satisfy
+`constructible_from<Callback, C>`.
+*Preconditions:* `Callback` and `C` model
+`constructible_from<Callback, C>`.
+*Effects:* Initializes `callback` with `std::forward<C>(cb)`. If
+`st.stop_requested()` is `true`, then
+`std::forward<Callback>(callback)()` is evaluated in the current thread
+before the constructor returns. Otherwise, if `st` has ownership of a
+stop state, acquires shared ownership of that stop state and registers
+the callback with that stop state such that
+`std::forward<Callback>(callback)()` is evaluated by the first call to
+`request_stop()` on an associated `stop_source`.
+*Remarks:* If evaluating `std::forward<Callback>(callback)()` exits via
+an exception, then `terminate` is called [[except.terminate]].
+*Throws:* Any exception thrown by the initialization of `callback`.
+``` cpp
+~stop_callback();
+```
+*Effects:* Unregisters the callback from the owned stop state, if any.
+The destructor does not block waiting for the execution of another
+callback registered by an associated `stop_callback`. If `callback` is
+concurrently executing on another thread, then the return from the
+invocation of `callback` strongly happens before [[intro.races]]
+`callback` is destroyed. If `callback` is executing on the current
+thread, then the destructor does not block [[defns.block]] waiting for
+the return from the invocation of `callback`. Releases ownership of the
+stop state, if any.

Diff to HTML by rtfpessoa