Skip to content
Tutorials Center
My learning

Topics

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.

C++
std::generator<int> evens(int n) {
    for (int i = 0; i < n; i += 2) co_yield i;
}

Try it

C++ std::generator, the ready-made coroutine type

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.

C++ A hand-written coroutine type

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:

  1. The frame is allocated (using promise_type::operator new if declared) and parameters are copied into it.
  2. The promise object is constructed inside the frame.
  3. promise.get_return_object() creates the value that will be returned to the caller.
  4. co_await promise.initial_suspend() runs. If it returns std::suspend_always the coroutine is lazy and stops here; std::suspend_never makes it eager.
  5. The body runs. co_yield v becomes co_await promise.yield_value(v). co_return v calls promise.return_value(v) (or return_void() with no operand), then leaves the body.
  6. Uncaught exceptions go to promise.unhandled_exception().
  7. co_await promise.final_suspend() runs (it must be noexcept). If it suspends, the frame stays alive until handle.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_await at 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::execution is 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, constexpr functions or functions with a deduced (auto) return type or C-style variadic parameters.