Coroutine support library
Coroutine handles, promise deduction, suspension objects, generator support, and the boundary between language coroutines and library helpers.
The coroutine support library is the standard-library side of C++ coroutines. The language defines co_await, co_yield, co_return, suspension points, and promise lookup; this hub covers the library types that make those language features usable in concrete designs, especially handles, traits, suspension helpers, and generator-style entry points.
# Start Here
Handles and frame access
Start here when you need to hold, resume, destroy, or inspect a coroutine frame through a standard handle type.
Promise deduction
Use this route when the core question is how a coroutine return type maps to its `promise_type` and customization points.
Suspension primitives
Start here when you need the basic always-suspend / never-suspend helpers used by promise methods and awaiter implementations.
Generator entry points
Use the generator route when the coroutine is being exposed as a pull-style range rather than as a custom task type.
# Quick Map
| If you need to... | Start with | Why |
|---|---|---|
| Refer to a coroutine frame after suspension | coroutine_handle | This is the standard non-owning handle used to resume, destroy, or inspect a coroutine state object. |
| Recover a promise object from a coroutine frame | coroutine_handle::promise, from_promise | These are the canonical bridge points between the frame handle and the promise implementation. |
| Control whether a coroutine suspends initially or finally | suspend_always, suspend_never | Promise hooks such as `initial_suspend` and `final_suspend` commonly return these simple awaitables. |
| Understand how a return type becomes a coroutine promise | coroutine_traits | This is the library mechanism that locates `promise_type` for a coroutine's declared return type and arguments. |
| Use a standard generator-style coroutine | generator, generator::iterator | `std::generator` is the standard library's synchronous yielded-sequence entry point. |
| Get a coroutine handle that never suspends meaningful work | noop_coroutine, noop_coroutine_promise | The noop coroutine facilities provide a trivial always-safe coroutine state useful in generic code paths. |
| Understand `co_await` / `co_yield` / `co_return` semantics | language coroutines | Those operators and the coroutine transformation rules are language features, not defined by this hub. |
# Coroutine Model
| Layer | Primary destinations | Use it for |
|---|---|---|
| Language coroutine semantics | coroutines | `co_await`, `co_yield`, `co_return`, suspension semantics, and the compiler transformation model. |
| Frame handle access | coroutine_handle | Representing and operating on a suspended or executing coroutine frame. |
| Promise selection | coroutine_traits | Mapping a coroutine signature to the promise type that defines its behavior. |
| Basic suspension helpers | suspend_always, suspend_never | Returning simple awaitables from promise hooks and hand-written awaiters. |
| Standard yielded sequence wrapper | generator | Exposing a coroutine as a synchronous range-compatible sequence. |
# Handle And Promise Routes
Handle lifecycle
Use this route for the core non-owning handle API: validity, resume, destroy, address conversion, and comparisons.
operator bool · done · address
Promise access
Start here when custom coroutine types expose behavior through the promise object stored in the frame.
No-op handles
Use the noop route when generic code needs a valid coroutine handle with trivial behavior and no user frame payload.
# Suspension And Generator Facilities
| Facility | Use it for | Primary destinations |
|---|---|---|
| Simple suspend choices | Returning an awaitable that always suspends or never suspends from promise hooks. | suspend_always, suspend_never |
| Generator facade | Presenting coroutine output as a synchronous range over yielded values. | generator, generator::iterator |
| Generator promise hooks | Understanding the standard promise-side operations behind `std::generator`. | generator::promise_type, begin, end |
# Practical Routes
I am implementing a coroutine return type
Start with handle and traits APIs when you need to understand how a custom task, lazy value, or resumable operation is wired.
I need a yielded sequence
Use `std::generator` first when the goal is pull-style iteration over yielded values rather than a bespoke async abstraction.
I am debugging suspension behavior
Start from the basic suspension helpers and then step outward into promise hooks or awaiter design as needed.
# Boundary Lines
| This hub covers | Use a different hub for |
|---|---|
| Library support types for coroutine frames, promise discovery, trivial suspension objects, and standard generator facilities. | Language coroutines when the question is about `co_await`, `co_yield`, `co_return`, promise requirements, or the compiler rewrite rules. |
| Generator-style coroutine exposure through the standard library. | ranges and iterator hub when the question is primarily about range/view composition or iterator behavior after the coroutine surface is already chosen. |
| Core coroutine support mechanisms. | thread support or diagnostics when you are dealing with scheduling, blocking, or error-reporting policy around a coroutine rather than the coroutine support library itself. |