Coroutines

std::coroutine_handle is a thin non-owning wrapper around a pointer to the coroutine frame. With it you can resume() a coroutine, query done(), destroy() the frame, and reach the promise(). It does not manage the frame's lifetime.

co_await expr suspends until expr is ready, then yields its result. co_yield v suspends and hands v to the caller. co_return finishes the coroutine, optionally passing a result via the promise_type. Any of the three makes the function a coroutine.

The promise_type is a compiler-found type that customizes a coroutine. It builds the return object, decides start/end suspension, handles co_yield/co_return values, and catches exceptions. Without it the lifecycle hooks cannot be generated.

Suspension means the coroutine stops at a defined point, saves its local state and resume position into the frame, and returns control to the caller — without unwinding or freeing the frame. It can later be resumed from that point.

A thread is an OS-scheduled, preemptive execution context with its own stack that runs in parallel on another core. A coroutine is a suspendable function with a heap frame, cooperatively scheduled; alone it gives no parallelism.

It lives in the coroutine frame — a compiler-generated object normally allocated on the heap. The frame holds the promise_type, the resume point, parameters, and any locals that survive a suspension. The caller's stack frame is gone after the first suspension.

A generator is a coroutine that produces a sequence of values lazily, one per resume, instead of computing them all upfront. It is built with co_yield, which suspends and hands the current value to the caller. C++23 adds std::generator<T>.

A coroutine does not return a value the ordinary way — its result must flow through the promise_type via return_value/return_void. Plain return bypasses that machinery, so the language forbids it; use co_return, which lowers into the promise call.

Both are trivial standard awaitables. For std::suspend_always, await_ready() returns false, so co_await always suspends. For std::suspend_never, await_ready() returns true, so co_await never suspends. Neither carries a result.

The compiler emits three Awaitable calls: await_ready() decides whether suspension is needed; await_suspend(handle) runs while the frame is parked; await_resume() yields the expression's value on resume.

No. co_await only suspends the coroutine and returns control to the caller — it never spawns a thread. Resumption runs on whatever thread calls handle.resume(). Switching threads needs a scheduling Awaitable.

It is your choice, set by initial_suspend. suspend_never makes the coroutine eager — it runs to the first suspension on call. suspend_always makes it lazy — it starts on the first resume(). Generators are usually lazy.

final_suspend() runs after the body and decides whether the frame stays alive. suspend_always keeps it so the caller can still read the result or exception; suspend_never destroys it at once, dangling the handle.

Define a type with a nested promise_type whose yield_value stores the value and returns suspend_always. Wrap a coroutine_handle, expose next()/value(), and destroy() the frame in the destructor.

It must provide get_return_object, initial_suspend, final_suspend (noexcept), unhandled_exception, and exactly one of return_value or return_void. A generator also needs yield_value. Missing any required member is ill-formed.

co_yield v calls promise.yield_value(v) and suspends the coroutine — it can be resumed again, producing a sequence. co_return calls return_value/return_void and finishes the coroutine — no further resumption is possible.

Callbacks are simple but nest. Futures look synchronous but compose awkwardly. C++20 coroutines give linear co_await code; C++26 senders/receivers add structured schedulers.

A function becomes a coroutine if its body uses co_await, co_yield, or co_return. The compiler transforms it into a state machine with a heap-allocated frame. The return type must define a promise_type.

C++20 coroutines suspend and resume without blocking a thread. co_await/co_yield/co_return makes a function a coroutine; the compiler turns it into a heap-allocated state machine. The return type needs a user-defined promise.

The frame is allocated (normally on the heap) once when the coroutine is first called, and freed when destroy() runs. The compiler may elide the heap allocation (HALO) when the coroutine's lifetime is fully visible to it.

Call std::coroutine_handle<promise_type>::from_promise(*this) — it rebuilds the handle from the promise's address, since the promise sits at a known frame offset. get_return_object() uses it to build the caller's wrapper.

coroutine_handle does not own the frame. If you lose the handle to an unfinished coroutine, or never call destroy(), the frame leaks. Prevent it by wrapping the handle in a RAII type whose destructor calls destroy(), and follow proper move semantics so ownership is unique.

A by-value parameter is copied into the coroutine frame, so it stays alive across suspensions for the coroutine's whole lifetime. A reference parameter only refers to the caller's object — if the caller returns first, the reference dangles, which is undefined behavior.

If await_suspend calls handle.resume() on the next coroutine, and that one resumes another, each resume() nests inside the previous stack frame. A long chain never unwinds and overflows the stack; heap frames do not bound it.

An exception escaping the body is caught by the compiler and routed to promise.unhandled_exception(). It does not reach the resumer's stack. A typical promise stores std::current_exception() and rethrows it later from get().

void suspends and returns to the caller. bool does the same when true, but false resumes the current coroutine at once. A returned coroutine_handle<> is symmetric transfer: that handle is resumed without growing the stack.

Make await_ready() return false, have await_suspend(handle) register the I/O and stash the handle in the completion callback, and let await_resume() return the result. The callback calls handle.resume().

A coroutine parameter taken by reference is not copied into the frame — only the reference is. If the referent dies before the coroutine resumes, using it is UB. It bites after the first suspension, once the caller's stack has unwound.

The compiler rewrites the body into a state machine in the heap frame. A resume-index integer records which suspend point to continue from; resume() dispatches on it — a switch — to jump back with locals preserved.

Symmetric transfer is returning a coroutine_handle<> from await_suspend so the compiler resumes that coroutine via a tail call instead of a nested resume(). It solves stack overflow in long coroutine chains.