How compilers implement coroutines is an implementation detail which is subject to change at any time. Nevertheless, you may be called upon to debug them, so it’s nice to know what you’re looking at.<\/p>\n
The C++ language requires that any coroutine be resumable from a Note<\/b>: The Microsoft Visual C++ compiler coroutine ABI took a breaking change in version 16.8<\/a>, so I’ll cover Microsoft Visual C++ coroutines twice, once in C++17 mode and once again in C++20 mode.<\/p>\n In the Microsoft Visual C++ compiler, the C++17-style coroutine handle is a pointer to a structure we shall call a “frame” for expository purposes.<\/p>\n The Constructing a coroutine frame consists of the following steps:<\/p>\n The index is initialized to 2 because the state of a suspended coroutine is always recorded as a nonzero even number.<\/p>\n When a coroutine suspends, its To resume a suspended coroutine, call the For 32-bit code, the jump table is an array of addresses to jump to. For 64-bit code, the jump table is an array of relative virtual addresses which need to be added to the module base address to for the code address. Using relative virtual addresses keeps the jump table smaller and also reduces the number of relocations needed.<\/p>\n To destroy a suspended coroutine, set the bottom bit of the index (turning it into an odd number), and then call the The Microsoft Visual C++ compiler uses the naming convention Note that the compiler adds one<\/i> to the index before using it to look up the offset in the jump table, so you need to ignore the first entry in the jump table.<\/p>\n The clang compiler uses a slightly different approach:<\/p>\n Instead of encoding the “destroying” state in the bottom bit of the index, clang uses a separate The gcc compiler sits somewhere in between the Microsoft and clang compilers.<\/p>\n Like the clang compiler, the gcc compiler uses a pair of function pointers, one for resuming the coroutine (which is internally called the coroutine_handle<><\/code>, so there needs to be some vtable-like thing so that calling the resume()<\/code> method on an arbitrary coroutine_handle<><\/code> resumes the correct coroutine.<\/p>\nstruct coroutine_frame\r\n{\r\n void (*resume)(coroutine_frame*);\r\n uint16_t index;\r\n uint16_t flags;\r\n promise_type promise;\r\n parameters...\r\n locals...\r\n temporaries...\r\n other bookkeeping...\r\n};\r\n<\/pre>\nindex<\/code> represents the progress of the coroutine through its function body. The flags<\/code> value is nonzero if the coroutine frame was allocated on the heap.<\/p>\n\n
resume<\/code> member to point to a custom function specific to the coroutine.<\/li>\nindex<\/code> to 2.<\/li>\nflags<\/code> to 1 if the frame was allocated on the heap; otherwise initialize it to zero.<\/li>\n<\/ul>\n\n
index<\/code> is updated to remember where the coroutine needs to resume. The coroutine states appear to be numbered in the order in which they appear in the function, so the initial state of the coroutine is 2, the first suspension point is 4, the next one is 6, and so on.\u00b9 Some of the suspension points can get optimized out, say, because the compiler can prove that await_ready<\/code> always returns true<\/code>.<\/p>\nresume<\/code> function with a pointer to the coroutine frame. Each coroutine gets a custom resume<\/code> function which uses the index as an index into a jump table to dispatch to the appropriate point in the coroutine where execution should resume.<\/p>\nresume<\/code> function. The odd entries in the jump table point to cleanup functions which destruct the variables that were live at the point of suspension. And if the flags<\/code> say that the coroutine was allocated on the heap, then it is delete<\/code> from the heap.<\/p>\nfunction$_ResumeCoro$N<\/code> for the coroutine resume<\/code> function, for some number N<\/var>. (I haven’t yet figured out what the N<\/var> means.) Here’s a 64-bit example:<\/p>\nfunction$_ResumeCoro$1:\r\n mov [rsp+8], rcx ; save coroutine frame\r\n push rbx \r\n sub rsp, 30h ; build stack frame\r\n mov rbx, [rsp+40h] ; rbx = coroutine frame\r\n movzx eax, word ptr [rbx+8] ; eax = index\r\n mov [rsp+20h], ax ; remember the index\r\n inc ax ; add 1, just for fun\r\n cmp ax, 6 \r\n ja fatal_error ; invalid index\r\n movsx rax, ax \r\n lea rdx, [__ImageBase] ; get module base address\r\n mov ecx, [rdx+rax*4+3158h] ; get offset from jump table\r\n add rcx,rdx ; apply offset to base address\r\n jmp rcx ; jump there\r\n<\/pre>\n
struct coroutine_frame\r\n{\r\n void (*resume)(coroutine_frame*);\r\n void (*destroy)(coroutine_frame*);\r\n uintN_t index;\r\n \/* parameters, local variables, other bookkeeping *\/\r\n};\r\n<\/pre>\ndestroy<\/code> function. This means that the indices are small integers, with no special meaning for even\/odd values. (Zero is a valid index.) The resume<\/code> and destroy<\/code> functions have separate jump tables, one for resumption and one for destruction, and if the number of states is small, then clang doesn’t even bother making a jump table; it just uses a bunch of tests. The size of the variable used to hold the state is chosen to be large enough to hold all of the states. Most reasonable-sized coroutines can get by with an 8-bit index, but the compiler internally supports indices up to 32 bits in size<\/a>.<\/p>\nstruct coroutine_frame\r\n{\r\n void (*actor)(coroutine_frame*);\r\n void (*destroy)(coroutine_frame*);\r\n uint8_t unused;\r\n uint8_t flags;\r\n uint16_t index;\r\n \/* parameters, local variables, other bookkeeping *\/\r\n};\r\n<\/pre>\nactor<\/code>) and one for destroying it. However, the gcc compiler follows the Microsoft C++ convention of using even numbers for suspended states and odd numbers for destroying states. The destroy<\/code> function just sets the bottom bit of the index<\/code> and then jumps to the actor<\/code> function.<\/p>\n