Skip to content
Tutorials Center
My learning

Topics

Lesson 139 of 171 ยท Concurrency

Coroutines

Learn C++20 coroutines - lazy sequences with co_yield and std::generator (C++23), how co_await and co_return work, writing a minimal generator, and lifetime pitfalls.

An ordinary function runs from start to finish in one go: you call it, it returns, and its local variables are gone. A coroutine is a function that can pause in the middle, hand control back to its caller, and later resume exactly where it stopped, with all its local variables intact. That one ability turns out to express two very different things elegantly: lazy sequences ("give me the next value when I ask for it") and asynchronous code that reads like straight-line code ("wait for this network reply, then continue") without blocking a thread.

C++20 added coroutines to the language as three keywords, co_yield, co_await and co_return, plus a low-level framework that libraries build on. C++23 added the first ready-made coroutine type to the standard library: std::generator. This lesson starts with std::generator, which you can use today with no boilerplate, then explains what the compiler does behind the scenes, builds a small generator type by hand, shows how co_await works with a tiny single-threaded scheduler, and ends with the lifetime pitfalls that make coroutines bite. It builds on Ranges and Views and Lambda Expressions.

Your first coroutine: std::generator

Any function whose body contains co_yield, co_await or co_return is a coroutine. The simplest kind produces a sequence: each co_yield value hands one value to the caller and pauses until the caller wants the next. With std::generator<T> (header <generator>, C++23), the result is a range you can loop over.

C++ A Fibonacci generator

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.

fibonacci() contains an infinite loop, yet the program finishes, because the coroutine only runs when the loop asks for the next element. std::views::take(12) stops asking after twelve values, and the paused coroutine is then simply destroyed. Its local variables a and b survive between values because they live in the coroutine's frame, not on the ordinary call stack.

Without coroutines you'd write the same thing as an iterator class that stores a and b as members and implements operator++ and operator*. The coroutine keeps the logic in its natural shape: a loop.

Coroutines are lazy: watching the control flow

A good way to understand coroutines is to print what happens and when. Calling a generator function doesn't run its body: it creates the coroutine frame and returns the generator object immediately. The body starts on the first increment of the loop, runs to the first co_yield, pauses, and so on.

C++ Who runs when

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.

The output alternates between main and the coroutine in a fixed order, all on one thread:

TEXT
calling letters()
got the generator, nothing ran yet
  [coroutine] started
main received a
  [coroutine] resumed after a
main received b
  [coroutine] resumed after b, finishing
loop done

This is the key point: coroutines are not threads. Nothing runs in parallel. A coroutine is a function that the caller suspends and resumes cooperatively. They belong in the concurrency chapter because they're the foundation of modern asynchronous code, where one thread juggles thousands of paused operations, but on their own they add no parallelism and need no locks.

Generators in practice

Generators shine whenever producing values involves state that's awkward to keep in an iterator: walking a tree, parsing input, or combining several sources. std::ranges::elements_of lets a generator yield every element of another generator as if it had yielded them itself, which makes recursion natural.

C++ Recursive tree walk

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.

The tree prints in sorted order, 1 3 6 8 10 14, with no explicit stack. co_return; ends a coroutine early, like return; in a normal function (a plain return is not allowed in a coroutine).

A tokenizer is another natural fit: the loop keeps its position in local variables and hands out one token at a time.

C++ A lazy tokenizer

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.

It prints five tokens: x, 42, y, 7 and done. The tokenizer yields std::string_views into line, which is safe here because line outlives the loop.

With GCC 15 at -O1 and above, a file that uses several std::generator functions can trigger a bogus -Wmismatched-new-delete warning that points into the <generator> header. It is a false positive in the compiler's analysis, not a bug in your code.

Things to know about std::generator<T>:

  • It's a move-only, single-pass input_range: you can iterate it once. Calling begin() a second time is undefined behavior.
  • Its elements are T&& references by default, so a range-for loop can move from them; std::generator<const T&> hands out const references instead, which avoids copies of big values.
  • An exception thrown in the generator body propagates out of the loop's increment, to the code iterating it.
  • It's C++23: GCC 14 and later ship it, recent MSVC versions do too, and libc++ (the library Clang uses on macOS) doesn't have it yet. With older toolchains people use small libraries, or write their own, as below.

What the compiler does with a coroutine

When a function is a coroutine, the compiler rewrites it. You don't need the details to use std::generator, but they explain the rules and the error messages:

  1. The coroutine frame. The compiler allocates (usually on the heap) a frame holding the parameters (copied or moved in), the local variables that live across a suspension, and a note of where to resume. The optimizer can sometimes put the frame on the caller's stack instead.
  2. The promise object. The return type (here std::generator<int>) names a nested promise_type. The compiler creates one promise in the frame. It's the coroutine's control panel: it decides what the caller gets back, what happens at the start and the end, and what co_yield and co_return do.
  3. The handle. std::coroutine_handle<promise_type> (header <coroutine>) is a non-owning pointer to the frame. Calling handle.resume() continues the coroutine; handle.done() says whether it finished; handle.destroy() frees the frame.
  4. The keywords become calls on the promise. co_yield v becomes co_await promise.yield_value(v). co_return v calls promise.return_value(v), and co_return; or falling off the end calls promise.return_void(). Every coroutine also starts with co_await promise.initial_suspend() and ends with co_await promise.final_suspend().

So "a coroutine" is really a cooperation between your function body and a library type that defines the promise. That's why C++20 shipped the keywords but almost no types: libraries were expected to supply them.

Writing a minimal generator by hand

Building a tiny generator yourself makes all of this concrete. This Counter type supports only next(), which resumes the coroutine and returns the yielded value, or std::nullopt when it's finished.

C++ A hand-written generator 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.

This prints 1 4 9 16 25 and then after the end: false. Read the promise top to bottom and you can see every design decision: initial_suspend returns std::suspend_always, so the body doesn't start until the first next(); yield_value stores the value and suspends; final_suspend suspends too, so the frame is still alive for done() to be checked, and the destructor frees it with destroy(). std::suspend_always and std::suspend_never are the two trivial awaitables the standard provides.

Our type is about 50 lines and still lacks iterators, so it can't be used in a range-for loop. That's the boilerplate std::generator saves you; write your own only when you need something it doesn't do.

co_await: suspending until something is ready

co_yield is a special case of a more general operation. co_await expr suspends the coroutine until expr says it can continue. The thing being awaited is an awaitable, an object with three member functions:

  • await_ready(): return true to skip suspending (the result is already available).
  • await_suspend(handle): called after the coroutine is paused, with its handle. This is where the awaitable arranges for someone to call handle.resume() later: when a timer fires, when I/O completes, or when a scheduler gets to it.
  • await_resume(): called when the coroutine continues; its return value becomes the value of the whole co_await expression.

Real libraries (Boost.Asio, cppcoro-style task libraries, game engines, Qt) use this to write asynchronous I/O as if it were blocking code. The example below is small but complete: a single-threaded scheduler with a queue of paused coroutines, an awaitable yield_to_others() that puts the current coroutine at the back of the queue, and two "tasks" that take turns.

C++ Cooperative tasks with co_await

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.

The two tasks interleave in a predictable order (download 1, render 1, download 2, render 2, ...), all on the main thread. Each co_await yield_to_others() puts the current coroutine at the back of the queue and returns control to whoever resumed it. Swap that awaitable for one that registers the handle with an operating-system I/O call, and you have the core of an asynchronous network server. Note that name is a std::string by value: the coroutine outlives the call expression, so it must own its data (see the pitfalls below).

co_return value; is the counterpart for coroutines that produce one result, such as a Task<int> that another coroutine can co_await to get the int. The standard library doesn't provide such a task type yet; that's what std::execution in C++26 and third-party libraries offer.

Pitfalls and rules

Dangling references are the number one coroutine bug. A coroutine's parameters are copied into its frame, but a reference parameter copies only the reference. Because the body runs later, the referred-to object may already be gone:

C++
std::generator<char> chars(const std::string& s) {   // stores a reference
    for (char c : s) co_yield c;
}

for (char c : chars("temporary")) { ... }   // OK: the temporary lives until the loop ends

auto gen = chars(std::string{"temporary"}); // the string dies at the end of this line
for (char c : gen) { ... }                  // undefined behavior: reads a destroyed string

The same goes for std::string_view and std::span parameters, pointers, and lambda captures by reference when the lambda itself is a coroutine. The safe default for coroutines that may outlive the call is to take parameters by value.

More rules worth knowing:

  • main, constructors, destructors, constexpr and consteval functions can't be coroutines, and neither can functions with plain return statements or C-style varargs.
  • A coroutine's return type determines everything; auto return types aren't allowed.
  • The frame is usually heap-allocated. Compilers can elide that allocation when the coroutine's lifetime is clearly nested inside the caller (an optimization known as HALO), but don't count on it in hot loops.
  • Coroutines are stackless: only the coroutine function itself can suspend, not a normal function it calls. A function that wants to suspend must itself be a coroutine and be awaited (or, for generators, yielded with elements_of).
  • A coroutine handle is a raw, non-owning pointer. Exactly one owner must call destroy() (or the coroutine must free itself by not suspending at its final point, like Task above). Wrap handles in an RAII type.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A generator function prints "start" as its first statement. What is printed by auto g = make_gen(); alone?

    std::generator suspends at its initial suspend point, so calling the function only creates the frame and returns the generator. The body begins when iteration asks for the first value.
  2. 2. fibonacci() contains while (true) { co_yield a; ... }. Why does for (auto n : fibonacci() | std::views::take(5)) finish?

    The coroutine runs only between resumptions. After five values the view stops resuming it, and the suspended coroutine is destroyed with the generator.
  3. 3. Two coroutines take turns through a single-threaded scheduler using co_await. Do they need a mutex around a shared counter?

    Coroutines are not threads. On one thread, each coroutine runs until it suspends, so there's no data race. That changes if a scheduler resumes coroutines on several threads.
  4. 4. What does co_yield value turn into inside the compiler-generated code?

    co_yield is defined in terms of the promise. yield_value typically stores the value and returns an awaitable that suspends the coroutine.
  5. 5. std::generator<char> chars(std::string_view s) is called as auto g = chars(std::string{"hi"}); and g is iterated on the next line. What happens?

    The frame stores the string_view, not the characters. The temporary string dies at the end of the full expression, before the lazily started body reads it. Take std::string by value instead.

Summary

  • A coroutine is a function containing co_yield, co_await or co_return; it can suspend and later resume with its locals intact, stored in a coroutine frame.
  • std::generator<T> (C++23, <generator>) is the ready-made lazy sequence: co_yield each value, loop over it with range-for or views, and use std::ranges::elements_of to yield a whole sub-range.
  • Coroutines are lazy and cooperative, not threads: they add no parallelism and run only when resumed.
  • The return type's promise_type controls the coroutine; std::coroutine_handle resumes and destroys it; initial_suspend, final_suspend, yield_value and return_void/return_value define its behavior.
  • co_await works with awaitables (await_ready, await_suspend, await_resume) and is the basis of asynchronous libraries.
  • Prefer by-value parameters in coroutines that outlive the call; references, views and spans easily dangle.

Next: Modern C++ Features by Standard, a guided tour of what C++11 through C++23 added, plus a clearly labeled preview of C++26.