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.
std::generator<int> count(int n) { for (int i = 1; i <= n; ++i) { co_yield i; // produce a value, suspend } }
Try it
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.
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
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,constexprfunctions, or functions with a deducedautoreturn 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 xis shorthand forco_await promise.yield_value(x). That is whystd::generatorcan keep a pointer to the yielded value without copying.final_suspendmust benoexcept. 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_suspendreturningsuspend_alwaysmakes the coroutine lazy (starts on firstresume);suspend_nevermakes 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 smallTaskas above. - Available since C++20;
<generator>since C++23. Both work in GCC 15 with-std=c++23.