From cppreference.com
Defined in header
template<classPromise=void>structcoroutine_handle; (1) (since C++20)template<>structcoroutine_handle<void>; (2) (since C++20)template<>structcoroutine_handle<std::noop_coroutine_promise>; (3) (since C++20)usingnoop_coroutine_handle=std::coroutine_handle<std::noop_coroutine_promise>; (4) (since C++20)The class template coroutine_handle can be used to refer to a suspended or executing coroutine. Every specialization of coroutine_handle is a
.
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
.
If the program adds specializations for std::coroutine_handle, the behavior is undefined.
Data members
Member name Definition ptr(private)A pointer void* to the coroutine state.
(exposition-only member object*)Member functions
constructs a coroutine_handle object
(public member function)
assigns the coroutine_handle object
(public member function)
Conversion
obtains a type-erased coroutine_handle
(public member function)
Observers
checks if the coroutine has completed
(public member function)
checks if the handle represents a coroutine
(public member function)
Control
resumes execution of the coroutine
(public member function)
destroys a coroutine
(public member function)
Promise Access
access the promise of a coroutine
(public member function)
[static]
creates a coroutine_handle from the promise object of a coroutine
(public static member function)
Export/Import
exports the underlying address, i.e. the pointer backing the coroutine
(public member function)
[static]
imports a coroutine from a pointer
(public static member function)
Non-member functions
Helper classes
Notes
A coroutine_handle may be dangling, in which case the coroutine_handle must be used carefully in order to avoid undefined behavior.
Example
Run this code
#include<coroutine>#include<iostream>#include<optional>template<std::movableT>classGenerator{public:structpromise_type{Generator<T>get_return_object(){returnGenerator{Handle::from_promise(*this)};}staticstd::suspend_alwaysinitial_suspend()noexcept{return{};}staticstd::suspend_alwaysfinal_suspend()noexcept{return{};}std::suspend_alwaysyield_value(Tvalue)noexcept{current_value=std::move(value);return{};}// Disallow co_await in generator coroutines.voidawait_transform()=delete;[[noreturn]]staticvoidunhandled_exception(){throw;}std::optional<T>current_value;};usingHandle=std::coroutine_handle<promise_type>;explicitGenerator(constHandlecoroutine):m_coroutine{coroutine}{}Generator()=default;~Generator(){if(m_coroutine)m_coroutine.destroy();}Generator(constGenerator&)=delete;Generator&operator=(constGenerator&)=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.classIter{public:voidoperator++(){m_coroutine.resume();}constT&operator*()const{return*m_coroutine.promise().current_value;}booloperator==(std::default_sentinel_t)const{return!m_coroutine||m_coroutine.done();}explicitIter(constHandlecoroutine):m_coroutine{coroutine}{}private:Handlem_coroutine;};Iterbegin(){if(m_coroutine)m_coroutine.resume();returnIter{m_coroutine};}std::default_sentinel_tend(){return{};}private:Handlem_coroutine;};template<std::integralT>Generator<T>range(Tfirst,constTlast){while(first<last)co_yieldfirst++;}intmain(){for(constchari: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 Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR Applied to Behavior as published Correct behavior
C++20 the public base class of coroutine_handle could leave it in an undesired state inheritance removed See also