Coroutine Frame Allocation
Reason about coroutine frame allocation and lifetime.
Coroutine Frame Allocation is a free C++ Academy lesson on CoddyKit. This is lesson 4 of 4. Any 3 lessons of this learning path are free to read in full — after that, CoddyKit PRO unlocks every lesson, plus hands-on practice with a built-in code editor and a 24/7 AI tutor. It is part of the C++ Academy learning path, and your progress syncs across the web and the CoddyKit app. The C++ Academy course includes 4 lessons in total.
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.
Learn C++ with an AI tutor — free
Write and run real code in your browser, get instant help from a 24/7 AI tutor, and pick up where you left off on the web or in the app.
- Courses
- 51
- Lessons
- 203
Frequently Asked Questions
Is the “Coroutine Frame Allocation” lesson free?
Yes — any 3 lessons of the C++ Academy learning path, including “Coroutine Frame Allocation”, are free to read in full here on the web. After that, CoddyKit PRO unlocks every lesson, plus interactive practice with a built-in code editor and a 24/7 AI tutor. The C++ Academy course includes 4 lessons in total.
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, so you can start here or from the beginning and move at your own pace. This is lesson 4 of 4.
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.
All lessons in this course
- Coroutine Concepts co_await co_yield co_return
- Implementing a Simple Generator
- Async Tasks and Awaiter Types
- Coroutine Frame Allocation