std::coroutine_handle, std::noop_coroutine_handle
From cppreference.com
C++
Feature test macros (C++20)
Concepts library (C++20)
Metaprogramming library (C++11)
Ranges library (C++20)
Filesystem library (C++17)
Concurrency support library (C++11)
Execution control library (C++26)
Utilities library
Relational operators (deprecated in C++20)
Integer comparison functions
Swap and type operations
Common vocabulary types
Type support (basic types, RTTI)
Library feature-test macros (C++20)
(C++11)
(C++20)
(C++26)
(C++20)
Coroutine support (C++20)
Contract support (C++26)
(C++20)(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)(C++20)(C++20)
(C++20)(C++20)(C++20)
General utilities
(C++20)(C++20)(C++20)
(C++20)(C++20)(C++20)
(C++20)
Coroutine support
Coroutine traits
(C++20)
Coroutine handle
coroutine_handle
(C++20)
No-op coroutines
(C++20)
(C++20)
Trivial awaitables
(C++20)
(C++20)
Range generators
(C++23)
std::coroutine_handle
Member functions
Conversion
Observers
Control
Promise access
Export/import
Non-member functions
Helper classes
Defined in header
<coroutine>
template< class Promise = void >
struct coroutine_handle;
(1)
(since C++20)
struct coroutine_handle;
template<>
struct coroutine_handle<void>;
(2)
(since C++20)
struct coroutine_handle<void>;
template<>
struct coroutine_handle<std::noop_coroutine_promise >;
(3)
(since C++20)
struct coroutine_handle<std::noop_coroutine_promise >;
using noop_coroutine_handle =
std::coroutine_handle<std::noop_coroutine_promise >;
(4)
(since C++20)
std::coroutine_handle<std::noop_coroutine_promise >;
The class template coroutine_handle
can be used to refer to a suspended or executing coroutine. Every specialization of coroutine_handle
is a LiteralType.
1) Primary template, can be created from the promise object of type
Promise
.2) Specialization std::coroutine_handle<void> erases the promise type. It is convertible from other specializations.
3) Specialization std::coroutine_handle<std::noop_coroutine_promise > refers to no-op coroutines. It cannot be created from a promise object.
On typical implementations, every specialization of std::coroutine_handle
is TriviallyCopyable.
If the program adds specializations for std::coroutine_handle
, the behavior is undefined.
Contents
[edit] Data members
Member name
Definition
ptr
(private)
A pointer void* to the coroutine state.(exposition-only member object*)
[edit] Member functions
Conversion
Observers
Control
Promise Access
[static]
coroutine_handle
from the promise object of a coroutine (public static member function) [edit]
Export/Import
exports the underlying address, i.e. the pointer backing the coroutine
(public member function) [edit]
(public member function) [edit]
[edit] Non-member functions
[edit] Helper classes
[edit] Notes
A coroutine_handle
may be dangling, in which case the coroutine_handle
must be used carefully in order to avoid undefined behavior.
[edit] Example
Run this code
#include <coroutine> #include <iostream> #include <optional> template<std::movable T> class Generator { public: struct promise_type { Generator<T> get_return_object() { return Generator{Handle::from_promise(*this)}; } static std::suspend_always initial_suspend() noexcept { return {}; } static std::suspend_always final_suspend() noexcept { return {}; } std::suspend_always yield_value(T value) noexcept { current_value = std::move(value); return {}; } // Disallow co_await in generator coroutines. void await_transform() = delete; [[noreturn]] static void unhandled_exception() { throw; } std::optional <T> current_value; }; using Handle = std::coroutine_handle<promise_type>; explicit Generator(const Handle coroutine) : m_coroutine{coroutine} {} Generator() = default; ~Generator() { if (m_coroutine) m_coroutine.destroy(); } Generator(const Generator&) = delete; Generator& operator=(const Generator&) = delete; Generator(Generator&& other) noexcept : m_coroutine{other.m_coroutine} { other.m_coroutine = {}; } Generator& operator=(Generator&& other) noexcept { if (this != &other) { if (m_coroutine) m_coroutine.destroy(); m_coroutine = other.m_coroutine; other.m_coroutine = {}; } return *this; } // Range-based for loop support. class Iter { public: void operator++() { m_coroutine.resume(); } const T& operator*() const { return *m_coroutine.promise().current_value; } bool operator==(std::default_sentinel_t ) const { return !m_coroutine || m_coroutine.done(); } explicit Iter(const Handle coroutine) : m_coroutine{coroutine} {} private: Handle m_coroutine; }; Iter begin() { if (m_coroutine) m_coroutine.resume(); return Iter{m_coroutine}; } std::default_sentinel_t end() { return {}; } private: Handle m_coroutine; }; template<std::integral T> Generator<T> range(T first, const T last) { while (first < last) co_yield first++; } int main() { for (const char i : range(65, 91)) std::cout << i << ' '; std::cout << '\n'; }
Output:
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
[edit] Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR | Applied to | Behavior as published | Correct behavior |
---|---|---|---|
LWG 3460 | C++20 | the public base class of coroutine_handle could leave it in an undesired state
|
inheritance removed |