C++20 coroutine frame layout mismatch when linking object files from different compilers

To guarantee a consistent coroutine frame layout across translation units built with the same major compiler version, you must unify the flags that influence the lowering of the coroutine state machine into a physical memory layout. Because the C++20 standard leaves the frame layout implementation-defined, any flag that alters spill slots, padding, or exception handling can create a binary mismatch.

Required Flag Unification

The following settings must be identical across all translation units to avoid ABI breakage:

• Exception Handling: Consistently use -fexceptions or -fno-exceptions (GCC/Clang) or /EHsc (MSVC). Mismatched exception models change how the frame handles cleanup and unwinding.
• Optimization Levels: Fix the optimization level (e.g., -O2 or -Os) across all units. Different levels can alter the placement of variables within the frame or trigger different elision strategies.
• Sanitizer Instrumentation: Ensure -fsanitize=undefined or -fsanitize=thread are applied globally or not at all. Sanitizers often insert additional padding or metadata into the frame layout.
• Toolchain-Specific Flags: For MSVC, ensure /Zc:await settings are identical; mismatched flags result in incompatible resumption struct layouts.

ABI Specifications and Limitations

While the Itanium C++ ABI (used by GCC/Clang on Linux) and the Microsoft x64 ABI provide nominal requirements for promise_type placement and suspension tokens, they do not guarantee binary compatibility across major compiler releases. The lowering strategy—how the compiler transforms the coroutine into a state machine—is subject to change between versions, meaning object files from different major versions are generally incompatible.

Link-Time Detection and Verification

Standard linkers cannot natively detect coroutine frame mismatches, as they typically manifest as runtime memory corruption rather than unresolved symbols. To detect these incompatibilities in a build system, use the following verification method:

1. Compile a representative coroutine translation unit using -fdump-coroutines-all (GCC/Clang) or /coroutine:dump (MSVC).
2. Extract the size and field offsets of the __coro_frame (or equivalent internal struct).
3. Compare these offsets against a known-good baseline in your CI pipeline. If the offsets or total size differ, reject the build before the linking stage.

One diagnostic detail that would change this recommendation is the specific compiler version and target architecture; some specific minor releases may introduce breaking changes to the lowering strategy that require a full rebuild of all dependencies regardless of flags.