std::coroutine_handle, std::noop_coroutine_handle - cppreference.com (original) (raw)

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

• 1 Data members
• 2 Member functions
  • 2.1 Conversion
  • 2.2 Observers
  • 2.3 Control
  • 2.4 Promise Access
  • 2.5 Export/Import
• 3 Non-member functions
• 4 Helper classes
• 5 Notes
• 6 Example
• 7 Defect reports
• 8 See also

[edit] Data members

[edit] Member functions

[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

#include #include #include   template<std::movable T> class Generator { public: struct promise_type { Generator 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 current_value; };   using Handle = std::coroutine_handle;   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 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.

[edit] See also