skip to content

C++20 Coroutines

A C++20 coroutine is a function that suspends with co_await, co_yield or co_return, driven by a promise type you or a library writes. Interviewers ask what the compiler generates.

on this pageshow

explore

questions

6

In C++, what does co_yield do in a lazy generator of log lines, and what does C++23's std::generator add over a hand-written one?

level: middleimportance: should knowfreq 38%

answer

  1. co_await promise.yield_value(e)
  2. suspend until the next pull
  3. lazy: initial_suspend always
  4. a view, begun once
  5. no co_await inside

basics

~20 s

co_yield e means co_await promise.yield_value(e): the promise stores the value and the coroutine suspends until the consumer asks for the next one. C++23's std::generator packages that promise, an input iterator and frame ownership into a ready-made lazy range.

solid answer

~40 s

`co_yield e` is defined as `co_await p.yield_value(e)` on the coroutine's promise `p`. A generator's `yield_value` stores the value (or a pointer to it) and returns an awaitable that suspends, so the producer stops right after each line and the consumer reads it through the generator object. Nothing runs until the first pull because the promise's `initial_suspend` returns `std::suspend_always`. Written by hand, the generator type must also own the `std::coroutine_handle`, destroy the frame, be move-only and provide iteration. C++23's `std::generator<Ref, Val = void, Allocator = void>` does all of that: it is a move-only `ranges::view` with an input iterator, works with range-for and views, supports recursive `co_yield std::ranges::elements_of(...)`, and deletes `await_transform`, so `co_await` in its body is ill-formed. `begin()` may be called only once. libstdc++ ships `<generator>`; libc++ (LLVM 23) does not yet.

code

cpp · 32 lines
cpp
#include <coroutine>
#include <cstdio>
#include <exception>
#include <string>
#include <utility>
struct LineGen {
    struct promise_type {
        std::string current;
        LineGen get_return_object() { return LineGen{Handle::from_promise(*this)}; }
        std::suspend_always initial_suspend() noexcept { return {}; }  // lazy
        std::suspend_always final_suspend() noexcept { return {}; }
        std::suspend_always yield_value(std::string s) { current = std::move(s); return {}; }
        void return_void() {}
        void unhandled_exception() { std::terminate(); }
    };
    using Handle = std::coroutine_handle<promise_type>;
    explicit LineGen(Handle h) : h_(h) {}
    LineGen(LineGen&& o) noexcept : h_(std::exchange(o.h_, {})) {}
    ~LineGen() { if (h_) h_.destroy(); }
    bool next() { h_.resume(); return !h_.done(); }
    const std::string& value() const { return h_.promise().current; }
    Handle h_;
};

LineGen log_lines(int n) {
    for (int i = 1; i <= n; ++i) co_yield "line " + std::to_string(i);
}

int main() {
    LineGen g = log_lines(3);  // nothing printed yet: the body has not started
    while (g.next()) std::printf("%s\n", g.value().c_str());
}

go deeper

for a junior

Recall that co_yield hands one value out and pauses the function until the next value is requested.

for a middle

Expand co_yield into co_await promise.yield_value, and list what a hand-written generator must own versus what std::generator provides.

for a senior

Know std::generator's single-pass begin, its deleted await_transform, elements_of recursion and the Ref parameter, and check library support per toolchain.

for a principal

Standardise on std::generator where every target's library ships it, and keep one reviewed fallback generator type where it does not.

## What `co_yield` means The standard defines `co_yield e` as exactly `co_await p.yield_value(e)`, where `p` is the coroutine's promise object. So a yield is just an await whose awaitable the **promise** chooses: 1. `p.yield_value(e)` runs; a generator stores the value (or its address) in the promise. 2. It returns an awaitable, usually `std::suspend_always`, so the coroutine suspends. 3. Control returns to whoever resumed the coroutine — the consumer asking for the next line. 4. The next `resume()` continues right after the `co_yield`, inside the loop, with all locals intact. A log-line generator therefore produces one line per request and never builds the whole list in memory. ## A hand-written generator Before C++23 every project wrote its own generator type. It needs: - a `promise_type` with `get_return_object`, `initial_suspend` returning `std::suspend_always` (lazy), `yield_value`, `return_void`, `unhandled_exception` and a `final_suspend` that suspends, so the value and the frame survive until the owner is done; - ownership of the `std::coroutine_handle<promise_type>`: destroy the frame in the destructor, be move-only, null the handle in the move constructor; - an interface to pull values: `next()` and `value()` as in the example, or an iterator so that range-for works. That is thirty-odd lines of exactly the kind of code that hides double-destroys and leaks, which is why the standard now ships one. ## `std::generator` (C++23) `std::generator` lives in `<generator>`: ```cpp // C++23 - not compiled here: libc++ in LLVM 23 does not provide <generator> #include <generator> #include <print> #include <string> std::generator<std::string> log_lines(int n) { for (int i = 1; i <= n; ++i) co_yield "line " + std::to_string(i); } int main() { for (const std::string& line : log_lines(3)) std::println("{}", line); } ``` What it gives you over the hand-written type: | Property | `std::generator` | |---|---| | Template parameters | `Ref`, `Val = void`, `Allocator = void`; `std::pmr::generator` uses `polymorphic_allocator<>` | | Range category | a `ranges::view` with an input iterator and `default_sentinel_t` end | | Copying | deleted; move-only | | Start | lazy: `initial_suspend()` returns `suspend_always` | | Iteration | `begin()` requires the coroutine to be at its initial suspend point, so it is called once | | Recursion | `co_yield std::ranges::elements_of(other_generator)` yields a nested generator's elements | | `co_await` in the body | ill-formed: the promise declares `void await_transform() = delete;` | | Frame allocation | through the `Allocator` parameter, via the promise's `operator new` | The `Ref` parameter decides what the iterator yields. `std::generator<std::string>` yields `std::string&&` references to the value the coroutine holds; `std::generator<const std::string&>` yields const references and avoids moving out. ## Stopping early A consumer rarely needs every line. Breaking out of the loop leaves the coroutine suspended at its last `co_yield`, and the generator's destructor then destroys the frame. Destroying a suspended coroutine runs the destructors of every object in scope at that suspension point, in the usual reverse order: - a `std::ifstream` local in the generator closes its file; - a `std::lock_guard` local would release its mutex — one more reason not to hold locks across a `co_yield`; - code after the `co_yield` never runs, so cleanup belongs in destructors, not in statements after the loop. ## Pitfalls - **Synchronous only.** `std::generator` is for pulling values; because `co_await` is ill-formed in its body, it cannot wait for a socket read. An asynchronous stream needs a different coroutine type. - **Single pass.** Iterating twice is a precondition violation, not a restart; store the lines if you need them again. - **Lifetime of arguments.** A lazy generator does not run until iterated, so a reference parameter must outlive the iteration (the dangling-reference rules for coroutines apply). - **Toolchain support.** At the pinned versions, libstdc++ (GCC 16.2 headers) provides `<generator>` and libc++ (LLVM 23) lists the paper as not implemented; check `__cpp_lib_generator` before relying on it.

  • Why does the hand-written generator's final_suspend return std::suspend_always?
    If the coroutine did not suspend at the end, its frame — including the promise holding `current` — would be destroyed as soon as the body finished, and the generator object would then call `done()` and `destroy()` on a dangling handle. Suspending at the final point keeps the frame alive until the owner observes `done()` and destroys it exactly once in its destructor.
  • Can a std::generator's body wait for a network read with co_await?
    No. `std::generator`'s promise declares `await_transform` as deleted, so every `co_await` expression in the body is ill-formed; only `co_yield` (which does not go through `await_transform`) may suspend it. It is a synchronous pull-based range. Reading from a socket as a stream needs an asynchronous generator type from a library or your own promise.

  • co_yield returns from the function like return does.
  • A generator computes all its values up front when called.
  • std::generator can be iterated as many times as you like.
  • You can co_await inside a std::generator body.
  • std::generator is available in every C++23 standard library.

Assumes C++23; co_yield is C++20, std::generator is C++23 and is missing from libc++ in LLVM 23.

open as a page

In C++20, what turns an ordinary function into a coroutine, and how does the compiler find the promise_type that drives it?

level: middleimportance: should knowfreq 42%

basics

~10 s

A function is a coroutine if its body contains co_await, co_yield or co_return; its declaration looks unchanged. The compiler uses std::coroutine_traits<R, Args...>::promise_type, which by default is the return type's nested promise_type.

open as a page

In C++20, what happens step by step at co_await on an awaiter for an async socket read, and what may await_suspend return?

level: seniorimportance: should knowfreq 40%

basics

~20 s

co_await calls await_ready; if it returns false the coroutine suspends and await_suspend(handle) runs, typically starting the read and storing the handle. When something resumes the handle, await_resume's result becomes the value of the co_await. await_suspend may return void, bool or a coroutine_handle.

open as a page

A lazy C++20 coroutine takes const std::string& and is resumed after the caller's temporary has died; why does it read freed memory, and how do you fix it?

level: seniorimportance: should knowfreq 45%

basics

~20 s

The frame copies parameters, but a reference parameter is copied as a reference to the caller's object. A temporary passed to it dies at the end of the call's full-expression, so a later resume reads a destroyed string. Take the parameter by value instead.

open as a page

As a C++ lead, how do you decide whether and how your team adopts C++20 coroutines when the standard library supplies no task type or executor?

level: principalimportance: should knowfreq 28%

basics

~20 s

Adopt only with one owned or vetted task type, a scheduler story and lifetime rules the team enforces. C++20 gives the language and handles, C++23 only std::generator, and C++26's std::execution::task is missing from libc++ (LLVM 23) and libstdc++ (GCC 16.2).

open as a page

In C++20, where does a coroutine's frame live, who frees it, and when can the compiler elide its heap allocation?

level: seniorimportance: nice to knowfreq 30%

basics

~20 s

The frame, or coroutine state, comes from the promise type's operator new if it declares one, else the global one. It is freed when the coroutine runs off its end or destroy() is called, and may be elided when it cannot outlive the caller.

open as a page