Coroutine Frame Allocation
Reason about coroutine frame allocation and lifetime.
Coroutine Frame Allocation is a free C++ Academy lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the C++ Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Where State Lives
Local variables in a coroutine survive across suspensions. They cannot live on the stack — the function returns between suspensions. Instead, they live in a heap-allocated coroutine frame.
What the Frame Contains
The frame holds:
- The coroutine s parameters
- The promise object
- Local variables that live across suspensions
- The resume and destroy function pointers
Heap Allocation Cost
Each coroutine call allocates a frame. Allocations are not free — significant for high-frequency coroutines. Optimizing compilers may elide the allocation when the lifetime is bounded — known as HALO (Heap Allocation eLision Optimization).
When HALO Kicks In
The compiler may avoid heap allocation when:
- The coroutine s lifetime is provably contained
- Inlining can prove the frame fits on the stack
- The frame size is fixed at compile time
Custom Allocators
You can provide custom allocators to your coroutine frames by overloading operator new inside the promise type.
struct promise_type {
void* operator new(size_t size) {
return std::malloc(size);
}
void operator delete(void* ptr) {
std::free(ptr);
}
};Frame Pools
For high-throughput async systems, allocate frames from a pool to avoid the general allocator overhead. Each thread or task type can have its own pool.
Frame Size
The frame size depends on the largest set of variables that may be alive across any suspension point. Adding more local variables increases it.
Reducing Frame Size
Tips:
- Restrict variable scope tightly
- Avoid large local arrays — use the heap explicitly
- Move temporaries into separate non-coroutine helpers
Inspecting Frames
Compilers can print frame sizes. With clang, use -fcoro-aligned-allocation and inspect via the diagnostic options. Disassembly reveals the frame layout.
Lifetime and Cleanup
The coroutine frame is destroyed when final_suspend finishes (or earlier if explicitly destroyed). RAII members are correctly destructed.
Memory Safety
A coroutine handle is a raw pointer. Holding one after the coroutine has been destroyed is undefined behavior. Library types wrap handles in RAII to prevent this.
When to Worry
Most applications never need to think about frame allocation. Worry only when you have millions of coroutines or extreme performance constraints. Profile first.
Quick Check
Why does a coroutine frame typically live on the heap?
Recap
Coroutines allocate a heap frame to preserve state across suspensions. Compilers can elide allocation (HALO) when feasible. Custom allocators and frame pools help in high-throughput systems — most code does not need to worry.
Frequently asked questions
Is the “Coroutine Frame Allocation” lesson free?
Yes — the full text of “Coroutine Frame Allocation” is free to read here on the web, and the C++ Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the C++ Academy course, upgrade to CoddyKit PRO.
What will I learn in “Coroutine Frame Allocation”?
Reason about coroutine frame allocation and lifetime. You practise C++ Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start C++ Academy?
No prior experience is required. C++ Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Coroutine Frame Allocation” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this C++ Academy lesson?
Yes. Every C++ Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.