C++ Reference ยท Types and Language Concepts
C++ coroutines
Concept page on C++20 coroutines: how the compiler transforms them, promise_type, coroutine_handle, awaitables, std::generator and lifetime pitfalls.
A coroutine is a function whose execution can be suspended and resumed. Its local variables live in a heap-allocated coroutine frame (unless the compiler removes the allocation), so they survive between suspensions. A function becomes a coroutine when its body contains co_await, co_yield or co_return.
C++20 standardizes the machinery, not a ready-made library. The compiler rewrites your coroutine around three customization points: the return type's nested promise_type (controls what happens at start, at co_yield, at co_return and on exceptions), a std::coroutine_handle (a non-owning pointer to the frame used to resume or destroy it) and awaiters (the objects that co_await operates on). C++23 adds std::generator, so the common "lazy sequence" case needs no hand-written machinery.
std::generator<int> evens(int n) { for (int i = 0; i < n; i += 2) co_yield i; }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
How the compiler treats a coroutine
When a coroutine is called, roughly this happens:
- The frame is allocated (using
promise_type::operator newif declared) and parameters are copied into it. - The promise object is constructed inside the frame.
promise.get_return_object()creates the value that will be returned to the caller.co_await promise.initial_suspend()runs. If it returnsstd::suspend_alwaysthe coroutine is lazy and stops here;std::suspend_nevermakes it eager.- The body runs.
co_yield vbecomesco_await promise.yield_value(v).co_return vcallspromise.return_value(v)(orreturn_void()with no operand), then leaves the body. - Uncaught exceptions go to
promise.unhandled_exception(). co_await promise.final_suspend()runs (it must benoexcept). If it suspends, the frame stays alive untilhandle.destroy(); if not, the frame is destroyed automatically.
Awaiters
co_await expr asks the awaited object three questions through the awaiter interface:
| Member | Purpose |
|---|---|
bool await_ready() |
Return true to skip suspension. |
await_suspend(handle) |
Called after suspension. May return void, bool, or another handle for symmetric transfer. This is where you schedule the resumption. |
T await_resume() |
Called when resuming. Its value is the value of the co_await expression. |
std::suspend_always and std::suspend_never are the two trivial awaiters in <coroutine>.
Usage notes
- Coroutines are stackless: only the coroutine itself can suspend, not functions it calls. That is cheap but you must write
co_awaitat each level. - Lifetime pitfalls: parameters are copied into the frame, but reference parameters copy only the reference. A coroutine started with a reference to a temporary can resume after that temporary is gone. Pass by value or make sure the referent outlives the coroutine.
- Lambda coroutines and captures: captures belong to the closure object, not to the frame. If the lambda object dies while the coroutine is suspended, the captures dangle. Prefer passing values as parameters.
- Always destroy the handle exactly once, usually in the destructor of the return type, and never resume a coroutine that is
done(). - Return types: C++23
std::generator<T>is the only coroutine type in the standard library; asynchronous task types, schedulers and executors come from libraries (std::executionis C++26). - Allocation can be elided by the compiler when the frame's lifetime is nested within the caller, but do not depend on it; you can provide your own allocation in the promise.
- Not usable in constructors, destructors,
main,constexprfunctions or functions with a deduced (auto) return type or C-style variadic parameters.