# C++20 coroutines and C++23 std::generator

> How C++20 stackless coroutines compile into resumable state-machine frames, how promise_type, awaitables, and symmetric transfer govern suspension, and how C++23 std::generator and lifetime rules keep async code sound.

- **Source:** C++ Atlas (https://cppatlas.com/topics/coroutines)
- **Track:** Concurrency
- **Estimated reading time:** 10 minutes
- **ISO C++ clauses:** [dcl.fct.def.coroutine] (https://eel.is/c++draft/dcl.fct.def.coroutine), [expr.await] (https://eel.is/c++draft/expr.await), [coroutine.handle] (https://eel.is/c++draft/coroutine.handle), [coroutine.traits] (https://eel.is/c++draft/coroutine.traits), [coro.generator] (https://eel.is/c++draft/coro.generator)
- **cppreference links:** [Coroutines (C++20)](https://en.cppreference.com/w/cpp/language/coroutines), [Coroutine support library](https://en.cppreference.com/w/cpp/coroutine), [std::coroutine_handle](https://en.cppreference.com/w/cpp/coroutine/coroutine_handle), [std::coroutine_traits](https://en.cppreference.com/w/cpp/coroutine/coroutine_traits), [std::suspend_always](https://en.cppreference.com/w/cpp/coroutine/suspend_always), [std::suspend_never](https://en.cppreference.com/w/cpp/coroutine/suspend_never), [std::noop_coroutine](https://en.cppreference.com/w/cpp/coroutine/noop_coroutine), [std::generator](https://en.cppreference.com/w/cpp/coroutine/generator)
- **Prerequisites:** object-lifetime-and-storage, lambdas, threads-jthread-and-locks

A C++20 coroutine is not a lightweight OS thread or a fiber with a separate stack. It is a compiler-transformed state machine whose suspension points and local variables live in a resumable **coroutine state** (frame), giving callers deterministic, zero-kernel-trap pausing and resumption.

## What makes a function a stackless coroutine

A function becomes a coroutine solely by its body containing `co_await`, `co_yield`, or `co_return`—the function signature (`Task fetch(int id)`) does not announce coroutine status. Because C++ coroutines are **stackless**, suspending a coroutine pauses only that function's own frame, storing parameters, locals that cross suspension points, the `promise` object, and a suspension-point index inside a compiler-generated coroutine state. Control returns cleanly to the immediate caller along the ordinary C++ call stack.

By default, the coroutine state is allocated dynamically via `operator new` (which `promise_type` may overload for arena or pool allocation). Under `[dcl.fct.def.coroutine]`, the compiler may perform **Heap Allocation eLision Optimization (HALO)**—placing the frame directly on the caller's stack—whenever it can prove the coroutine's lifetime nests strictly inside the caller and its size is statically known.

> **Mental model.** Calling a coroutine does not spawn background execution: it builds a state-machine frame, runs until its first suspension point, hands back the return object, and advances only when someone calls `handle.resume()`.

## The promise_type lifecycle from entry to final_suspend

When compiling a coroutine returning `R` with parameter types `Args...`, the compiler instantiates `std::coroutine_traits<R, Args...>::promise_type` (which defaults to `R::promise_type`). Entry and exit follow a fixed choreography:

1. Allocate the coroutine frame and move-or-copy parameter values into it.
2. Construct the `promise` inside the frame and invoke `promise.get_return_object()` (converting/storing the result for the caller).
3. Execute `co_await promise.initial_suspend()` (returning `std::suspend_always` for lazy tasks, or `std::suspend_never` for eager start).
4. Run the coroutine body; uncaught exceptions transfer to `promise.unhandled_exception()`, while `co_return` invokes `return_void()` or `return_value(expr)`.
5. Execute `co_await promise.final_suspend()`, which **must** be `noexcept`.

If `final_suspend()` returns `std::suspend_never`, the coroutine frame self-destructs immediately when control reaches the end—so any wrapper `Task` that later checks `handle.done()` or calls `handle.destroy()` in `~Task()` commits a use-after-free. Therefore, RAII `Task` types almost always suspend at `final_suspend()` (via `std::suspend_always` or a symmetric-transfer awaiter) so `~Task()` owns `handle.destroy()`.

```cpp
#include <coroutine>
#include <exception>
#include <utility>

struct Task {
    struct promise_type {
        std::coroutine_handle<> continuation = std::noop_coroutine();

        Task get_return_object() noexcept {
            return Task{std::coroutine_handle<promise_type>::from_promise(*this)};
        }
        std::suspend_always initial_suspend() noexcept { return {}; }
        struct FinalAwaiter {
            bool await_ready() noexcept { return false; }
            std::coroutine_handle<> await_suspend(
                std::coroutine_handle<promise_type> h) noexcept {
                return h.promise().continuation; // Symmetric tail transfer
            }
            void await_resume() noexcept {}
        };
        FinalAwaiter final_suspend() noexcept { return {}; }
        void return_void() noexcept {}
        void unhandled_exception() { std::terminate(); }
    };

    std::coroutine_handle<promise_type> handle;
    explicit Task(std::coroutine_handle<promise_type> h) noexcept : handle(h) {}
    Task(Task&& other) noexcept : handle(std::exchange(other.handle, {})) {}
    Task& operator=(Task&&) = delete;
    ~Task() { if (handle) handle.destroy(); }
};
```

## The awaitable protocol and symmetric transfer

Every `co_await expr` evaluates a three-step customization pipeline. First, if `promise_type` defines `await_transform`, the compiler transforms `expr` via `promise.await_transform(expr)`. Second, if the resulting awaitable provides a member or non-member `operator co_await`, that operator yields the awaiter. Third, the compiler calls `awaiter.await_ready()`: if `true`, execution skips suspension and calls `await_resume()` immediately; if `false`, the coroutine saves its registers and suspension index, enters the suspended state, and calls `awaiter.await_suspend(h)`.

The return type of `await_suspend(std::coroutine_handle<Promise> h)` governs what executes next:

- **`void`** keeps `h` suspended and returns control to whichever caller resumed `h`.
- **`bool`** keeps `h` suspended when `true`, or immediately resumes `h` when `false` (useful to close lock-free race windows).
- **`std::coroutine_handle<>`** triggers **symmetric transfer**: the compiler tail-calls `.resume()` on the returned handle (or `std::noop_coroutine()` to bounce back to the resumer) without pushing a new stack frame. Calling `continuation.resume()` inside a `void`-returning `await_suspend` consumes O(N) call stack frames across loops of `co_await` calls and risks stack overflow, whereas returning `continuation` runs in constant stack space.

> **Standardese.** Under `[expr.await]`, the coroutine state is already suspended *before* `await_suspend(h)` executes. If `await_suspend` hands `h` off to another thread pool or executor, that worker may resume and destroy `h` concurrently—so never touch `this`, `h.promise()`, or frame locals after publishing `h`.

## Lifetime hazards across suspension points

Because a suspended coroutine frequently outlives the full-expression that created it, two argument-passing idioms introduce silent dangling references:

First, **reference and view parameters**: if you declare `Task parse(const std::string& text)` or `Task parse(std::string_view text)` and call `auto t = parse(std::string("payload"));`, the coroutine frame stores a reference or pointer—not a copied `std::string`. At the semicolon, the temporary string is destroyed while `t` remains suspended, leaving a dangling handle on the first `resume()`. Asynchronous coroutines should accept owning values (`std::string`) in their parameter list.

Second, **lambda coroutine captures**: in `[x = 42]() -> Task { co_await std::suspend_always{}; use(x); }()`, captured `x` lives inside the lambda closure object, *not* in the coroutine's parameters. Only the closure's `this` pointer is copied into the coroutine frame. When the temporary lambda dies at the semicolon after returning `Task`, resuming `Task` reads a destroyed closure! Either keep the closure alive across the coroutine's entire lifetime or pass values as parameters to the lambda instead of capturing them.

> **Pitfall.** Coroutine frames copy or move declared function parameters, never the pointees behind `const T&`, `std::string_view`, `std::span`, or lambda captures. Any state read after a suspension point must be owned inside the frame or guaranteed to outlive the coroutine handle.

```cpp
#include <coroutine>
#include <string>

struct DemoTask {
    struct promise_type {
        DemoTask get_return_object() noexcept { return {}; }
        std::suspend_always initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_void() noexcept {}
        void unhandled_exception() {}
    };
};

// Safe: owns its own std::string inside the coroutine frame
DemoTask consume_owned(std::string payload) {
    co_await std::suspend_always{};
    (void)payload.size();
}

// Safe alternative for lambdas: pass captured data as an argument, not a capture
auto make_coro = [](int x) -> DemoTask {
    co_await std::suspend_always{};
    (void)x;
};
```

## C++23 std::generator and recursive co_yield

Writing a custom `promise_type` just to produce lazy sequences is verbose and error-prone. `co_yield expr` is pure syntax sugar for `co_await promise.yield_value(expr)`, and C++23 `<generator>` packages that pattern into `std::generator<Ref, V, Allocator>`, a standard synchronous `std::ranges::view` compatible with range pipelines.

Even better, C++23 `std::generator` solves the classic recursive-generator slowdown via `std::ranges::elements_of`. Yielding elements of a nested generator with a manual `for (auto x : child()) co_yield x;` loop incurs O(depth) trampoline hops on every yielded item. Calling `co_yield std::ranges::elements_of(child())` pushes the child coroutine onto an internal active-coroutine stack inside the root generator and transfers directly to the innermost leaf in O(1) per element.

```cpp
#include <generator>
#include <ranges>

std::generator<int> range_seq(int lo, int hi) {
    for (int i = lo; i < hi; ++i) {
        co_yield i;
    }
}

std::generator<int> chained_seq() {
    co_yield std::ranges::elements_of(range_seq(0, 3));
    co_yield std::ranges::elements_of(range_seq(10, 13));
}
```

Each promise customization hook maps cleanly to a distinct phase of the coroutine lifecycle:

| Customization Point | When Invoked | Key Invariant |
| --- | --- | --- |
| `initial_suspend()` | Right after `get_return_object()` | `suspend_always` builds lazy tasks; `suspend_never` runs eagerly |
| `final_suspend()` | After `return_*` or `unhandled_exception()` | Must be `noexcept`; suspending transfers `destroy()` ownership to caller |
| `await_transform(e)` | Before `operator co_await` on every `co_await e` | Lets promises intercept or wrap arbitrary awaited expressions |
| `yield_value(v)` | On every `co_yield v` | Lowers directly to `co_await promise.yield_value(v)` |
| `await_suspend(h)` | After `h` is suspended and `await_ready()` is false | Returning `coroutine_handle<>` triggers constant-stack symmetric transfer |

## What to remember

- A function is a coroutine solely because its body uses `co_await`, `co_yield`, or `co_return`; stackless frames store spilled locals without needing OS thread stacks.
- Make `final_suspend()` `noexcept` and suspend if an owning wrapper like `Task` later calls `handle.done()` or `handle.destroy()`.
- Prefer `std::coroutine_handle<>`-returning `await_suspend` for symmetric transfer so chained async continuations never overflow the call stack.
- Never touch `this`, `h.promise()`, or frame locals after handing `h` to another thread inside `await_suspend`, because the coroutine is already suspended and may finish concurrently.
- Pass asynchronous coroutine inputs by owning value—not `const T&`, `string_view`, or temporary lambda captures—and use C++23 `std::generator` with `std::ranges::elements_of` for synchronous lazy streams.

## Concept Map Outline

- **C++20 coroutines & generator:** Compiler-generated stackless state machines pause and resume without separate OS thread stacks.
  - **Stackless frame mechanics:** Compiler transforms functions containing co_await, co_yield, or co_return into frames.
    - **Frame stores spilled locals:** Holds promise, copied parameters, suspension index, and cross-suspend variables.
    - **Custom operator new & HALO:** Promises may override allocation; compilers elide heap frames when lifetimes nest.
    - **Runs on resumer thread:** Calling or resuming a coroutine executes synchronously on the invoking thread.
  - **Promise lifecycle:** coroutine_traits<R, Args...>::promise_type orchestrates startup, returns, and teardown.
    - **initial_suspend laziness:** Returns suspend_always for lazy start or suspend_never for eager execution.
    - **final_suspend must be noexcept:** Suspending lets RAII wrappers call destroy(); suspend_never self-deletes the frame.
    - **unhandled_exception hook:** Captures uncaught body exceptions inside the promise before final_suspend runs.
  - **Awaitable protocol:** co_await drives await_transform, await_ready, await_suspend, and await_resume.
    - **await_ready bypass:** Returns true when results are already ready, avoiding suspension overhead.
    - **Symmetric transfer handle:** Returning coroutine_handle<> from await_suspend tail-resumes without stack growth.
    - **Suspended before await_suspend:** Another thread can resume and destroy h immediately once await_suspend publishes h.
  - **Suspension lifetime hazards:** References and closure captures outlive temporaries across suspension boundaries.
    - **Reference & view parameters:** const T& and string_view bind temporaries that die at the caller semicolon.
    - **Lambda capture closure trap:** Temporary coroutine lambdas destroy captures at the semicolon, leaving dangling this.
    - **Pass owning values:** By-value parameters move directly into the coroutine frame for safe later access.
  - **C++23 std::generator:** Standard synchronous ranges::view backed by co_yield and promise.yield_value.
    - **co_yield lowers to co_await:** Every co_yield x evaluates co_await promise.yield_value(x).
    - **elements_of O(1) recursion:** Yielding nested generators via elements_of avoids linear trampoline overhead.

## Standardese Quiz Questions

### Question 1 [warmup] ([dcl.fct.def.coroutine])

A Task RAII wrapper holds std::coroutine_handle<promise_type> h and calls if (h) h.destroy(); in ~Task(). What happens if promise_type::final_suspend() returns std::suspend_never?

A. h.destroy() safely releases any remaining promise fields
B. When the coroutine finishes, its frame self-destructs before ~Task() runs, causing double destruction / use-after-free in ~Task()
C. Compilation fails unless final_suspend() returns std::suspend_always
D. The coroutine restarts from initial_suspend()

**Answer (B):** When the coroutine finishes, its frame self-destructs before ~Task() runs, causing double destruction / use-after-free in ~Task()

**Why:** Under [dcl.fct.def.coroutine], if a coroutine does not suspend at final_suspend(), execution flows off the end and automatically destroys the coroutine state. Any Task handle still pointing to that frame now dangles, so checking h.done() or calling h.destroy() in ~Task() is undefined behavior.

### Question 2 [warmup] ([expr.yield])

Inside a coroutine body, how does the compiler translate co_yield expr;?

A. Into co_await promise.yield_value(expr);
B. Into promise.return_value(expr);
C. Into co_await expr; bypassing the promise
D. Into a thread yield call std::this_thread::yield()

**Answer (A):** Into co_await promise.yield_value(expr);

**Why:** Per [expr.yield], co_yield expr is defined to be equivalent to co_await p.yield_value(expr), where p is the coroutine's promise object.

### Question 3 [tricky] ([dcl.fct.def.coroutine], [expr.prim.lambda.closure])

Assuming Task starts lazily (initial_suspend() returns std::suspend_always), what happens when t.handle.resume() executes below?

```cpp
Task t = [msg = std::string("hello")]() -> Task {
    co_await std::suspend_always{};
    std::size_t n = msg.size();
    (void)n;
}();
t.handle.resume();
```

A. msg was copied into the coroutine frame automatically, so msg.size() returns 5
B. Compilation fails because lambdas cannot be coroutines
C. Undefined behavior: the temporary lambda closure dies at the semicolon while t is suspended, so msg inside the coroutine reads a dangling closure this
D. HALO automatically extends the lambda closure lifetime to match t

**Answer (C):** Undefined behavior: the temporary lambda closure dies at the semicolon while t is suspended, so msg inside the coroutine reads a dangling closure this

**Why:** A coroutine lambda's captures reside in the closure object (*this), not in the coroutine's parameter list. Calling (...)() stores only the closure's this pointer inside the coroutine frame; when the temporary closure is destroyed at the semicolon, resuming t later dereferences a dangling this pointer.

### Question 4 [tricky] ([dcl.fct.def.coroutine], [class.temporary])

Why does make_task(std::string("transient")) exhibit undefined behavior when resumed after its initial suspension point?

```cpp
Task make_task(std::string_view sv) {
    co_await std::suspend_always{};
    use(sv);
}
Task t = make_task(std::string("transient"));
t.handle.resume();
```

A. std::string_view cannot be copied into a coroutine frame
B. co_await std::suspend_always{} clears all parameters
C. std::string temporaries cannot convert to std::string_view in coroutines
D. The coroutine frame stores a copy of sv (a pointer+length view), while the temporary std::string is destroyed at the semicolon before t.handle.resume() runs

**Answer (D):** The coroutine frame stores a copy of sv (a pointer+length view), while the temporary std::string is destroyed at the semicolon before t.handle.resume() runs

**Why:** Coroutine parameters are copied/moved into the frame according to their declared parameter types. Because sv is a non-owning std::string_view (just like const std::string&), it does not extend or copy the backing std::string temporary, which dies at the end of the full-expression creating t.

### Question 5 [standardese] ([expr.await])

In void await_suspend(std::coroutine_handle<> h), the awaiter pushes h into a lock-free queue watched by another thread, and then reads this->result on the next line of await_suspend. Why is this a race / use-after-free?

A. await_suspend cannot accept a type-erased std::coroutine_handle<>
B. The coroutine is already suspended before await_suspend begins ([expr.await]), so the worker thread can resume and destroy the coroutine (and the awaited temporary awaiter) before await_suspend finishes
C. await_suspend automatically holds an internal mutex on h
D. Only bool await_suspend permits multi-threaded resumption

**Answer (B):** The coroutine is already suspended before await_suspend begins ([expr.await]), so the worker thread can resume and destroy the coroutine (and the awaited temporary awaiter) before await_suspend finishes

**Why:** Under [expr.await], the coroutine saves state and suspends before await_suspend(h) is entered. Once h is published to another thread, that thread may immediately resume h, run past co_await, and destroy both h and any stack/member awaiter object before await_suspend returns.

### Question 6 [standardese] ([expr.await], [coroutine.handle.noop])

How does returning std::coroutine_handle<> from await_suspend prevent stack overflow across long chains of completed coroutines, and what handle stops the chain?

A. It pushes continuations onto a heap queue; nullptr stops the chain
B. It spawns a fresh thread for each continuation; std::coroutine_handle<>::from_address(nullptr) stops it
C. It performs symmetric transfer via a tail call to the returned handle's resume() without growing the stack; returning std::noop_coroutine() returns control to the caller
D. It runs await_resume() recursively and unwinds with exceptions

**Answer (C):** It performs symmetric transfer via a tail call to the returned handle's resume() without growing the stack; returning std::noop_coroutine() returns control to the caller

**Why:** Under [expr.await], if await_suspend returns a std::coroutine_handle<Z>, the compiler emits a tail transfer calling resume() on that handle without allocating another C++ stack frame. Returning std::noop_coroutine() invokes a no-op resumption that immediately returns control to whichever caller invoked resume().
