[support.coroutine] - C++17 → C++20

Files changed (1) hide show

tmp/tmpqbuw15me/{from.md → to.md} +364 -0

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

	@@ -0,0 +1,364 @@

+## Coroutines <a id="support.coroutine">[[support.coroutine]]</a>
+The header `<coroutine>` defines several types providing compile and
+run-time support for coroutines in a C++ program.
+### Header `<coroutine>` synopsis <a id="coroutine.syn">[[coroutine.syn]]</a>
+``` cpp
+#include <compare>              // see [compare.syn]
+namespace std {
+  // [coroutine.traits], coroutine traits
+  template<class R, class... ArgTypes>
+    struct coroutine_traits;
+  // [coroutine.handle], coroutine handle
+  template<class Promise = void>
+    struct coroutine_handle;
+  // [coroutine.handle.compare], comparison operators
+  constexpr bool operator==(coroutine_handle<> x, coroutine_handle<> y) noexcept;
+  constexpr strong_ordering operator<=>(coroutine_handle<> x, coroutine_handle<> y) noexcept;
+  // [coroutine.handle.hash], hash support
+  template<class T> struct hash;
+  template<class P> struct hash<coroutine_handle<P>>;
+  // [coroutine.noop], no-op coroutines
+  struct noop_coroutine_promise;
+  template<> struct coroutine_handle<noop_coroutine_promise>;
+  using noop_coroutine_handle = coroutine_handle<noop_coroutine_promise>;
+  noop_coroutine_handle noop_coroutine() noexcept;
+  // [coroutine.trivial.awaitables], trivial awaitables
+  struct suspend_never;
+  struct suspend_always;
+}
+```
+### Coroutine traits <a id="coroutine.traits">[[coroutine.traits]]</a>
+This subclause defines requirements on classes representing *coroutine
+traits*, and defines the class template `coroutine_traits` that meets
+those requirements.
+#### Class template `coroutine_traits` <a id="coroutine.traits.primary">[[coroutine.traits.primary]]</a>
+The header `<coroutine>` defines the primary template `coroutine_traits`
+such that if `ArgTypes` is a parameter pack of types and if the
+*qualified-id* `R::promise_type` is valid and denotes a type
+[[temp.deduct]], then `coroutine_traits<R,ArgTypes...>` has the
+following publicly accessible member:
+``` cpp
+using promise_type = typename R::promise_type;
+```
+Otherwise, `coroutine_traits<R,ArgTypes...>` has no members.
+Program-defined specializations of this template shall define a publicly
+accessible nested type named `promise_type`.
+### Class template `coroutine_handle` <a id="coroutine.handle">[[coroutine.handle]]</a>
+``` cpp
+namespace std {
+  template<>
+  struct coroutine_handle<void>
+  {
+    // [coroutine.handle.con], construct/reset
+    constexpr coroutine_handle() noexcept;
+    constexpr coroutine_handle(nullptr_t) noexcept;
+    coroutine_handle& operator=(nullptr_t) noexcept;
+    // [coroutine.handle.export.import], export/import
+    constexpr void* address() const noexcept;
+    static constexpr coroutine_handle from_address(void* addr);
+    // [coroutine.handle.observers], observers
+    constexpr explicit operator bool() const noexcept;
+    bool done() const;
+    // [coroutine.handle.resumption], resumption
+    void operator()() const;
+    void resume() const;
+    void destroy() const;
+  private:
+    void* ptr;  // exposition only
+  };
+  template<class Promise>
+  struct coroutine_handle : coroutine_handle<>
+  {
+    // [coroutine.handle.con], construct/reset
+    using coroutine_handle<>::coroutine_handle;
+    static coroutine_handle from_promise(Promise&);
+    coroutine_handle& operator=(nullptr_t) noexcept;
+    // [coroutine.handle.export.import], export/import
+    static constexpr coroutine_handle from_address(void* addr);
+    // [coroutine.handle.promise], promise access
+    Promise& promise() const;
+  };
+}
+```
+An object of type `coroutine_handle<T>` is called a *coroutine handle*
+and can be used to refer to a suspended or executing coroutine. A
+default-constructed `coroutine_handle` object does not refer to any
+coroutine.
+If a program declares an explicit or partial specialization of
+`coroutine_handle`, the behavior is undefined.
+#### Construct/reset <a id="coroutine.handle.con">[[coroutine.handle.con]]</a>
+``` cpp
+constexpr coroutine_handle() noexcept;
+constexpr coroutine_handle(nullptr_t) noexcept;
+```
+*Ensures:* `address() == nullptr`.
+``` cpp
+static coroutine_handle from_promise(Promise& p);
+```
+*Preconditions:* `p` is a reference to a promise object of a coroutine.
+*Returns:* A coroutine handle `h` referring to the coroutine.
+*Ensures:* `addressof(h.promise()) == addressof(p)`.
+``` cpp
+coroutine_handle& operator=(nullptr_t) noexcept;
+```
+*Ensures:* `address() == nullptr`.
+*Returns:* `*this`.
+#### Export/import <a id="coroutine.handle.export.import">[[coroutine.handle.export.import]]</a>
+``` cpp
+constexpr void* address() const noexcept;
+```
+*Returns:* `ptr`.
+``` cpp
+static constexpr coroutine_handle<> coroutine_handle<>::from_address(void* addr);
+static constexpr coroutine_handle<Promise> coroutine_handle<Promise>::from_address(void* addr);
+```
+*Preconditions:* `addr` was obtained via a prior call to `address`.
+*Ensures:* `from_address(address()) == *this`.
+#### Observers <a id="coroutine.handle.observers">[[coroutine.handle.observers]]</a>
+``` cpp
+constexpr explicit operator bool() const noexcept;
+```
+*Returns:* `address() != nullptr`.
+``` cpp
+bool done() const;
+```
+*Preconditions:* `*this` refers to a suspended coroutine.
+*Returns:* `true` if the coroutine is suspended at its final suspend
+point, otherwise `false`.
+#### Resumption <a id="coroutine.handle.resumption">[[coroutine.handle.resumption]]</a>
+Resuming a coroutine via `resume`, `operator()`, or `destroy` on an
+execution agent other than the one on which it was suspended has
+implementation-defined behavior unless each execution agent either is an
+instance of `std::thread` or `std::jthread`, or is the thread that
+executes `main`.
+[*Note 1*: A coroutine that is resumed on a different execution agent
+should avoid relying on consistent thread identity throughout, such as
+holding a mutex object across a suspend point. — *end note*]
+[*Note 2*: A concurrent resumption of the coroutine may result in a
+data race. — *end note*]
+``` cpp
+void operator()() const;
+void resume() const;
+```
+*Preconditions:* `*this` refers to a suspended coroutine. The coroutine
+is not suspended at its final suspend point.
+*Effects:* Resumes the execution of the coroutine.
+``` cpp
+void destroy() const;
+```
+*Preconditions:* `*this` refers to a suspended coroutine.
+*Effects:* Destroys the coroutine [[dcl.fct.def.coroutine]].
+#### Promise access <a id="coroutine.handle.promise">[[coroutine.handle.promise]]</a>
+``` cpp
+Promise& promise() const;
+```
+*Preconditions:* `*this` refers to a coroutine.
+*Returns:* A reference to the promise of the coroutine.
+#### Comparison operators <a id="coroutine.handle.compare">[[coroutine.handle.compare]]</a>
+``` cpp
+constexpr bool operator==(coroutine_handle<> x, coroutine_handle<> y) noexcept;
+```
+*Returns:* `x.address() == y.address()`.
+``` cpp
+constexpr strong_ordering operator<=>(coroutine_handle<> x, coroutine_handle<> y) noexcept;
+```
+*Returns:* `compare_three_way()(x.address(), y.address())`.
+#### Hash support <a id="coroutine.handle.hash">[[coroutine.handle.hash]]</a>
+``` cpp
+template<class P> struct hash<coroutine_handle<P>>;
+```
+The specialization is enabled [[unord.hash]].
+### No-op coroutines <a id="coroutine.noop">[[coroutine.noop]]</a>
+#### Class `noop_coroutine_promise` <a id="coroutine.promise.noop">[[coroutine.promise.noop]]</a>
+``` cpp
+struct noop_coroutine_promise {};
+```
+The class `noop_coroutine_promise` defines the promise type for the
+coroutine referred to by `noop_coroutine_handle` [[coroutine.syn]].
+#### Class `coroutine_handle<noop_coroutine_promise>` <a id="coroutine.handle.noop">[[coroutine.handle.noop]]</a>
+``` cpp
+namespace std {
+  template<>
+  struct coroutine_handle<noop_coroutine_promise> : coroutine_handle<>
+  {
+    // [coroutine.handle.noop.observers], observers
+    constexpr explicit operator bool() const noexcept;
+    constexpr bool done() const noexcept;
+    // [coroutine.handle.noop.resumption], resumption
+    constexpr void operator()() const noexcept;
+    constexpr void resume() const noexcept;
+    constexpr void destroy() const noexcept;
+    // [coroutine.handle.noop.promise], promise access
+    noop_coroutine_promise& promise() const noexcept;
+    // [coroutine.handle.noop.address], address
+    constexpr void* address() const noexcept;
+  private:
+    coroutine_handle(unspecified);
+  };
+}
+```
+##### Observers <a id="coroutine.handle.noop.observers">[[coroutine.handle.noop.observers]]</a>
+``` cpp
+constexpr explicit operator bool() const noexcept;
+```
+*Returns:* `true`.
+``` cpp
+constexpr bool done() const noexcept;
+```
+*Returns:* `false`.
+##### Resumption <a id="coroutine.handle.noop.resumption">[[coroutine.handle.noop.resumption]]</a>
+``` cpp
+constexpr void operator()() const noexcept;
+constexpr void resume() const noexcept;
+constexpr void destroy() const noexcept;
+```
+*Effects:* None.
+*Remarks:* If `noop_coroutine_handle` is converted to
+`coroutine_handle<>`, calls to `operator()`, `resume` and `destroy` on
+that handle will also have no observable effects.
+##### Promise access <a id="coroutine.handle.noop.promise">[[coroutine.handle.noop.promise]]</a>
+``` cpp
+noop_coroutine_promise& promise() const noexcept;
+```
+*Returns:* A reference to the promise object associated with this
+coroutine handle.
+##### Address <a id="coroutine.handle.noop.address">[[coroutine.handle.noop.address]]</a>
+``` cpp
+constexpr void* address() const noexcept;
+```
+*Returns:* `ptr`.
+*Remarks:* A `noop_coroutine_handle`’s `ptr` is always a non-null
+pointer value.
+#### Function `noop_coroutine` <a id="coroutine.noop.coroutine">[[coroutine.noop.coroutine]]</a>
+``` cpp
+noop_coroutine_handle noop_coroutine() noexcept;
+```
+*Returns:* A handle to a coroutine that has no observable effects when
+resumed or destroyed.
+*Remarks:* A handle returned from `noop_coroutine` may or may not
+compare equal to a handle returned from another invocation of
+`noop_coroutine`.
+### Trivial awaitables <a id="coroutine.trivial.awaitables">[[coroutine.trivial.awaitables]]</a>
+``` cpp
+namespace std {
+  struct suspend_never {
+    constexpr bool await_ready() const noexcept { return true; }
+    constexpr void await_suspend(coroutine_handle<>) const noexcept {}
+    constexpr void await_resume() const noexcept {}
+  };
+  struct suspend_always {
+    constexpr bool await_ready() const noexcept { return false; }
+    constexpr void await_suspend(coroutine_handle<>) const noexcept {}
+    constexpr void await_resume() const noexcept {}
+  };
+}
+```
+[*Note 1*: The types `suspend_never` and `suspend_always` can be used
+to indicate that an *await-expression* should either never suspend or
+always suspend, and in either case not produce a value. — *end note*]

Diff to HTML by rtfpessoa