skip to content

In C++20, where does a coroutine's frame live, who frees it, and when can the compiler elide its heap allocation?

level: seniorimportance: nice to knowfreq 30%

answer

  1. coroutine state, not the stack
  2. promise operator new first
  3. destroy() or flowing off the end
  4. final_suspend decides the owner
  5. HALO when lifetime is nested

basics

~20 s

The frame, or coroutine state, comes from the promise type's operator new if it declares one, else the global one. It is freed when the coroutine runs off its end or destroy() is called, and may be elided when it cannot outlive the caller.

solid answer

~50 s

A coroutine's locals, parameter copies, promise and resume point live in the **coroutine state** (the frame), not on the caller's stack, because the coroutine outlives each call to `resume()`. The standard says an implementation **may need** to allocate it, and does so with a non-array allocation function looked up first in the promise type — which may receive the size followed by the coroutine's arguments — then globally. If the promise declares `get_return_object_on_allocation_failure`, the allocation must be non-throwing and, when it returns `nullptr`, the caller receives that function's result instead. The frame is freed when control flows off the end of the coroutine (when `final_suspend` does not suspend) or when `destroy()` is called on a handle to a suspended coroutine; calling `destroy()` on a running one is undefined behavior. Clang performs **heap allocation elision (HALO)** when it can see that the frame cannot outlive the caller — the example below allocates at `-O0` and not at `-O2`.

code

cpp · 31 lines
cpp
#include <coroutine>
#include <cstdio>
#include <exception>
#include <new>
int allocations = 0;

struct Lazy {
    struct promise_type {
        int value = 0;
        static void* operator new(std::size_t n) { ++allocations; return ::operator new(n); }
        static void operator delete(void* p) { ::operator delete(p); }
        Lazy get_return_object() { return Lazy{Handle::from_promise(*this)}; }
        std::suspend_always initial_suspend() noexcept { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_value(int v) { value = v; }
        void unhandled_exception() { std::terminate(); }
    };
    using Handle = std::coroutine_handle<promise_type>;
    explicit Lazy(Handle h) : h(h) {}
    Lazy(const Lazy&) = delete;
    ~Lazy() { h.destroy(); }
    int get() { h.resume(); return h.promise().value; }
    Handle h;
};

Lazy square(int x) { co_return x * x; }

int main() {
    int r = square(7).get();  // the frame cannot outlive this full-expression
    std::printf("r=%d allocations=%d\n", r, allocations);
}

go deeper

for a junior

Recall that a coroutine keeps its state in a frame that usually lives on the heap, not on the stack.

for a middle

Explain how operator new is looked up in the promise first, and the two ways a frame is destroyed.

for a senior

Match final_suspend to ownership, measure allocations, and know when HALO can and cannot remove them.

for a principal

Set an allocation policy for coroutines on hot paths — pooled promises, measured elision — instead of assuming coroutines are free.

## Why a frame is needed An ordinary function keeps its locals on the native stack and loses them when it returns. A coroutine **returns to its caller at every suspension** and continues later, possibly on another thread, so its state must live somewhere that survives: the **coroutine state**, usually called the frame. It holds: - the promise object; - copies of the parameters (references stay references); - locals and temporaries that live across a suspension point; - an index saying where to resume. ## How it is allocated The standard says an implementation may need to allocate this storage, and specifies how: 1. The name `operator new` is looked up **in the promise type** first. If found, the compiler tries to call it with the frame size followed by the coroutine's arguments, and falls back to just the size. 2. If the promise type declares none, the global `operator new` is used with the size. 3. If the promise type declares `get_return_object_on_allocation_failure`, a failed allocation returns `nullptr` (using the nothrow form when the global function is selected), and the caller receives `promise_type::get_return_object_on_allocation_failure()` instead of a coroutine. Step 1 is how custom allocation works: a promise can route frames to a pool, and C++23's `std::generator` uses its `Allocator` parameter this way. ## Who frees it The frame is destroyed in exactly two ways: - control **flows off the end** of the coroutine — after `final_suspend` if that does not suspend; - someone calls **`destroy()`** on a `std::coroutine_handle` to the suspended coroutine. | `final_suspend()` returns | After the body ends | Who must free the frame | |---|---|---| | `std::suspend_never` | the frame is freed immediately | nobody; any handle is now dangling | | `std::suspend_always` | the coroutine waits at its final suspend point | the owner, by calling `destroy()` once | `final_suspend` must not be potentially-throwing, and destroying a coroutine that is **not suspended** is undefined behavior. A fire-and-forget task usually picks `suspend_never`; a task or generator whose result is read afterwards picks `suspend_always` and destroys in the owner's destructor. ## Allocation elision Heap allocation on every call is the main cost of stackless coroutines, so the standard's "may need to allocate" leaves room to avoid it. Clang implements **heap allocation elision (HALO)**: when inlining shows the frame's lifetime is nested within the caller — created, resumed and destroyed before the caller returns — the frame becomes part of the caller's own frame. The example shows it directly: the promise's `operator new` runs once at `-O0` and zero times at `-O2`. Conditions in practice: - the compiler must see the coroutine's body and the code that destroys it, so it must be inlinable; - the handle must not escape to somewhere the compiler cannot follow, such as another thread or a container; - optimisation must be on. Elision is an optimisation, never a guarantee: code must be correct with a heap frame. Clang's coroutine debugging guide describes how it splits each coroutine into a ramp function, a resume function, a destroy function and, for elided frames, a cleanup function that destroys without deallocating — that split is one implementation's design, not the standard's. ## Senior practice 1. Count allocations with a promise `operator new` before claiming coroutines are free on a hot path. 2. Give long-lived or escaping coroutines a pool allocator through the promise rather than hoping for elision. 3. Keep `final_suspend` and the owner's destructor in agreement, so every frame is destroyed exactly once.

  • How can a coroutine report an allocation failure without exceptions?
    Declare a static `get_return_object_on_allocation_failure()` in the promise type. The compiler then treats a `nullptr` from the allocation function as failure — using `::operator new(size_t, nothrow_t)` when the global function is selected, and requiring a non-throwing allocation function — and returns that function's result to the caller instead of starting the coroutine. It suits builds with exceptions disabled.
  • Why must final_suspend not throw?
    The standard requires `co_await promise.final_suspend()` to be non-potentially-throwing because by then the body has finished and `unhandled_exception()` has already had its chance; there is no handler left to deliver an exception to, and the frame's owner may be about to destroy it. Declaring it `noexcept` and returning `std::suspend_always` or `std::suspend_never` is the usual shape.

  • A coroutine's locals live on the caller's stack like a normal call.
  • The frame is freed automatically when the coroutine object goes out of scope.
  • Compilers always elide coroutine frame allocations.
  • Calling destroy() on a running coroutine is a safe way to cancel it.
  • A promise type cannot control how the frame is allocated.

Assumes C++23; the frame allocation and destruction rules are C++20's, and C++23 adds allocator support through std::generator.