[coroutine.handle] (original) (raw)

17 Language support library [support]

17.12 Coroutines [support.coroutine]

17.12.3 Class template coroutine_­handle [coroutine.handle]

namespace std { template<> struct coroutine_handle { // [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), export/import
constexpr void* address() const noexcept;
static constexpr coroutine_handle from_address(void* addr);

// [[coroutine.handle.observers]](#observers), observers
constexpr explicit operator bool() const noexcept;
bool done() const;

// [[coroutine.handle.resumption]](#resumption), resumption
void operator()() const;
void resume() const;
void destroy() const;

private: void* ptr; // exposition only };

template 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), export/import
static constexpr coroutine_handle from_address(void* addr);

// [[coroutine.handle.promise]](#promise), promise access
Promise& promise() const;

}; }

An object of typecoroutine_­handle<T> is called a coroutine handleand 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 ofcoroutine_­handle, the behavior is undefined.

17.12.3.1 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.

Returns:A coroutine handle h referring to the coroutine.

Postconditions: addressof(h.promise()) == addressof(p).

coroutine_handle& operator=(nullptr_t) noexcept;

Postconditions: address() == nullptr.

17.12.3.2 Export/import [coroutine.handle.export.import]

constexpr void* address() const noexcept;

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.

Postconditions: from_­address(address()) == *this.

17.12.3.3 Observers [coroutine.handle.observers]

constexpr explicit operator bool() const noexcept;

Returns: address() != nullptr.

Preconditions: *this refers to a suspended coroutine.

Returns: true if the coroutine is suspended at its final suspend point, otherwise false.

17.12.3.4 Resumption [coroutine.handle.resumption]

Resuming a coroutine via resume, operator(), or destroyon 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

:

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

:

A concurrent resumption of the coroutine may 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.

Preconditions: *this refers to a suspended coroutine.

17.12.3.5 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.3.6 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()).