skip to content

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.