24 KiB
[support.coroutine]
17 Language support library [support]
17.13 Coroutines [support.coroutine]
17.13.1 General [support.coroutine.general]
The header defines several types providing compile and run-time support for coroutines in a C++ program.
17.13.2 Header synopsis [coroutine.syn]
// all freestanding#include // see [compare.syn]namespace std {// [coroutine.traits], coroutine traitstemplate<class R, class... ArgTypes>struct coroutine_traits; // [coroutine.handle], coroutine handletemplatestruct coroutine_handle; // [coroutine.handle.compare], comparison operatorsconstexpr bool operator==(coroutine_handle<> x, coroutine_handle<> y) noexcept; constexpr strong_ordering operator<=>(coroutine_handle<> x, coroutine_handle<> y) noexcept; // [coroutine.handle.hash], hash supporttemplate struct hash; template struct hash<coroutine_handle
>; // [coroutine.noop], no-op coroutinesstruct 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 awaitablesstruct suspend_never; struct suspend_always;}
17.13.3 Coroutine traits [coroutine.traits]
17.13.3.1 General [coroutine.traits.general]
Subclause [coroutine.traits] defines requirements on classes representingcoroutine traits, and defines the class templatecoroutine_traits that meets those requirements.
17.13.3.2 Class template coroutine_traits [coroutine.traits.primary]
The header defines the primary templatecoroutine_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: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.
17.13.4 Class template coroutine_handle [coroutine.handle]
17.13.4.1 General [coroutine.handle.general]
namespace std {template<>struct coroutine_handle{// [coroutine.handle.con], construct/resetconstexpr coroutine_handle() noexcept; constexpr coroutine_handle(nullptr_t) noexcept; coroutine_handle& operator=(nullptr_t) noexcept; // [coroutine.handle.export.import], export/importconstexpr void* address() const noexcept; static constexpr coroutine_handle from_address(void* addr); // [coroutine.handle.observers], observersconstexpr explicit operator bool() const noexcept; bool done() const; // [coroutine.handle.resumption], resumptionvoid operator()() const; void resume() const; void destroy() const; private:void* ptr; // exposition only}; templatestruct coroutine_handle {// [coroutine.handle.con], construct/resetconstexpr coroutine_handle() noexcept; constexpr coroutine_handle(nullptr_t) noexcept; static coroutine_handle from_promise(Promise&); coroutine_handle& operator=(nullptr_t) noexcept; // [coroutine.handle.export.import], export/importconstexpr void* address() const noexcept; static constexpr coroutine_handle from_address(void* addr); // [coroutine.handle.conv], conversionconstexpr operator coroutine_handle<>() const noexcept; // [coroutine.handle.observers], observersconstexpr explicit operator bool() const noexcept; bool done() const; // [coroutine.handle.resumption], resumptionvoid operator()() const; void resume() const; void destroy() const; // [coroutine.handle.promise], promise access Promise& promise() const; private:void* ptr; // exposition only};}
An object of typecoroutine_handle is called a coroutine handle and can be used to refer to a suspended or executing coroutine.
A coroutine_handle object whose member address() returns a null pointer value does not refer to any coroutine.
Two coroutine_handle objects refer to the same coroutine if and only if their member address() returns the same non-null value.
If a program declares an explicit or partial specialization ofcoroutine_handle, the behavior is undefined.
17.13.4.2 Construct/reset [coroutine.handle.con]
constexpr coroutine_handle() noexcept; constexpr coroutine_handle(nullptr_t) noexcept;
Postconditions: address() == nullptr.
static coroutine_handle from_promise(Promise& p);
Preconditions: p is a reference to a promise object of a coroutine.
Postconditions: addressof(h.promise()) == addressof(p).
Returns: A coroutine handle h referring to the coroutine.
coroutine_handle& operator=(nullptr_t) noexcept;
Postconditions: address() == nullptr.
Returns: *this.
17.13.4.3 Conversion [coroutine.handle.conv]
constexpr operator coroutine_handle<>() const noexcept;
Effects: Equivalent to: return coroutine_handle<>::from_address(address());
17.13.4.4 Export/import [coroutine.handle.export.import]
constexpr void* address() const noexcept;
Returns: ptr.
static constexpr coroutine_handle<> coroutine_handle<>::from_address(void* addr);
Preconditions: addr was obtained via a prior call to address on an object whose type is a specialization of coroutine_handle.
Postconditions: from_address(address()) == *this.
static constexpr coroutine_handle<Promise> coroutine_handle<Promise>::from_address(void* addr);
Preconditions: addr was obtained via a prior call to address on an object of type cv coroutine_handle.
Postconditions: from_address(address()) == *this.
17.13.4.5 Observers [coroutine.handle.observers]
constexpr explicit operator bool() const noexcept;
Returns: address() != nullptr.
bool done() const;
Preconditions: *this refers to a suspended coroutine.
Returns: true if the coroutine is suspended at its final suspend point, otherwise false.
17.13.4.6 Resumption [coroutine.handle.resumption]
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 can result in a data race.
â end note]
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.
void destroy() const;
Preconditions: *this refers to a suspended coroutine.
Effects: Destroys the coroutine ([dcl.fct.def.coroutine]).
17.13.4.7 Promise access [coroutine.handle.promise]
Promise& promise() const;
Preconditions: *this refers to a coroutine.
Returns: A reference to the promise of the coroutine.
17.13.4.8 Comparison operators [coroutine.handle.compare]
constexpr bool operator==(coroutine_handle<> x, coroutine_handle<> y) noexcept;
Returns: x.address() == y.address().
constexpr strong_ordering operator<=>(coroutine_handle<> x, coroutine_handle<> y) noexcept;
Returns: compare_three_way()(x.address(), y.address()).
17.13.4.9 Hash support [coroutine.handle.hash]
template<class P> struct hash<coroutine_handle<P>>;
The specialization is enabled ([unord.hash]).
17.13.5 No-op coroutines [coroutine.noop]
17.13.5.1 Class noop_coroutine_promise [coroutine.promise.noop]
struct noop_coroutine_promise {};
The class noop_coroutine_promise defines the promise type for the coroutine referred to by noop_coroutine_handle ([coroutine.syn]).
17.13.5.2 Class coroutine_handle<noop_coroutine_promise> [coroutine.handle.noop]
17.13.5.2.1 General [coroutine.handle.noop.general]
namespace std {template<>struct coroutine_handle<noop_coroutine_promise>{// [coroutine.handle.noop.conv], conversionconstexpr operator coroutine_handle<>() const noexcept; // [coroutine.handle.noop.observers], observersconstexpr explicit operator bool() const noexcept; constexpr bool done() const noexcept; // [coroutine.handle.noop.resumption], resumptionconstexpr 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], addressconstexpr void* address() const noexcept; private: coroutine_handle(unspecified); void* ptr; // exposition only};}
17.13.5.2.2 Conversion [coroutine.handle.noop.conv]
constexpr operator coroutine_handle<>() const noexcept;
Effects: Equivalent to: return coroutine_handle<>::from_address(address());
17.13.5.2.3 Observers [coroutine.handle.noop.observers]
constexpr explicit operator bool() const noexcept;
Returns: true.
constexpr bool done() const noexcept;
Returns: false.
17.13.5.2.4 Resumption [coroutine.handle.noop.resumption]
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.
17.13.5.2.5 Promise access [coroutine.handle.noop.promise]
noop_coroutine_promise& promise() const noexcept;
Returns: A reference to the promise object associated with this coroutine handle.
17.13.5.2.6 Address [coroutine.handle.noop.address]
constexpr void* address() const noexcept;
Returns: ptr.
Remarks: A noop_coroutine_handle's ptr is always a non-null pointer value.
17.13.5.3 Function noop_coroutine [coroutine.noop.coroutine]
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.
17.13.6 Trivial awaitables [coroutine.trivial.awaitables]
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 either never suspends or always suspends, and in either case does not produce a value.
â end note]