Skip to content
Tutorials Center
My learning

Topics

C++ Reference ยท Keywords and Statements

The co_await, co_yield and co_return keywords

Reference for the C++20 coroutine keywords co_await, co_yield and co_return: what makes a function a coroutine, promise types, awaiters and std::generator.

A coroutine is a function that can suspend itself in the middle and be resumed later, keeping its local variables alive in between. C++20 adds three keywords for this. co_await expr suspends the coroutine until the awaited thing is ready, co_yield value hands a value to the caller and suspends, and co_return value finishes the coroutine with a result. A function that contains any of the three is a coroutine; there is no separate coroutine keyword.

The language only provides the mechanism. The meaning of each keyword is decided by the coroutine's return type, through its nested promise_type, and by the awaiter object that co_await operates on. C++23 supplies one ready-made type, std::generator, so for simple lazy sequences you no longer write that machinery yourself.

C++
std::generator<int> count(int n) {
    for (int i = 1; i <= n; ++i) {
        co_yield i;               // produce a value, suspend
    }
}

Try it

C++ A lazy sequence with co_yield and std::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.

C++ Writing the machinery by hand: co_await and co_return

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.

Syntax

C++
co_await  cast-expression      // suspend until the awaitable is ready; yields its result
co_yield  expression           // same as: co_await promise.yield_value(expression)
co_return expression;          // promise.return_value(expression), then final suspend
co_return;                     // promise.return_void()
Part Description
Awaitable The operand of co_await. It is turned into an awaiter (via promise.await_transform if present, then operator co_await if present).
Awaiter An object with await_ready(), await_suspend(handle) and await_resume(). await_ready returning true skips suspension; await_resume provides the value of the whole co_await expression.
std::suspend_always / std::suspend_never Trivial awaiters in <coroutine>: always suspend, or never suspend.
promise_type Nested in (or specialized for) the return type. Provides get_return_object, initial_suspend, final_suspend, unhandled_exception and return_value or return_void.

Errors / undefined behavior: resuming a coroutine that is not suspended or that has already finished is undefined behavior. Flowing off the end of a coroutine whose promise has no return_void is undefined behavior. Destroying a coroutine that is not suspended at a suspension point is undefined behavior.

Usage notes

  • Where they are allowed. Not in main, constructors, destructors, constexpr functions, or functions with a deduced auto return type. Lambdas can be coroutines, but captures live in the lambda object, not the frame, so a coroutine lambda must outlive the coroutine.
  • The coroutine frame (parameters, locals, suspension state) is normally heap-allocated. Parameters are copied into it, so a reference parameter can dangle if the caller's object dies before the coroutine finishes.
  • co_yield x is shorthand for co_await promise.yield_value(x). That is why std::generator can keep a pointer to the yielded value without copying.
  • final_suspend must be noexcept. Suspending there keeps the frame alive so you can read the result; if it does not suspend, the frame destroys itself and the handle becomes dangling.
  • Lazy versus eager. initial_suspend returning suspend_always makes the coroutine lazy (starts on first resume); suspend_never makes it start immediately.
  • Need a library. Writing promise types is advanced. Use std::generator (C++23) for sequences; for asynchronous tasks use a library or write a small Task as above.
  • Available since C++20; <generator> since C++23. Both work in GCC 15 with -std=c++23.