17 Language support library [support]

17.12 Coroutines [support.coroutine]

17.12.4 Class template coroutine_­handle [coroutine.handle]

17.12.4.1 General [coroutine.handle.general]

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.con], construct/reset constexpr 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/import constexpr void* address() const noexcept; static constexpr coroutine_handle from_address(void* addr); // [coroutine.handle.conv], conversion constexpr operator coroutine_handle<>() const noexcept; // [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; // [coroutine.handle.promise], promise access Promise& promise() const; private: void* ptr; // exposition only }; }
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 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 of coroutine_­handle, the behavior is undefined.

17.12.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.12.4.3 Conversion [coroutine.handle.conv]

constexpr operator coroutine_handle<>() const noexcept;
Effects: Equivalent to: return coroutine_­handle<>​::​from_­address(address());

17.12.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<Promise>.
Postconditions: from_­address(address()) == *this.

17.12.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.12.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.12.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.12.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.12.4.9 Hash support [coroutine.handle.hash]

template<class P> struct hash<coroutine_handle<P>>;
The specialization is enabled ([unord.hash]).