Text of clang.llvm.org › docs › DebuggingCoroutines.html as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Debugging C++ Coroutines - Clang

Hide navigation sidebar Hide table of contents sidebar Back to top Edit this page Toggle table of contents sidebar Debugging C++ Coroutines # Introduction # Coroutines in C++ were introduced in C++20, and the user experience for debugging them can still be challenging. This document guides you on how to most efficiently debug coroutines and how to navigate existing shortcomings in debuggers and compilers. Coroutines are generally used either as generators or for asynchronous programming.

In this document, we will discuss both use cases. Even if you are using coroutines for asynchronous programming, you should still read the generators section, as it introduces foundational debugging techniques also applicable to the debugging of asynchronous programs. Both compilers (clang, gcc, …) and debuggers (lldb, gdb, …) are still improving their support for coroutines. As such, we recommend using the latest available version of your toolchain.

This document focuses on clang and lldb. The screenshots show lldb-dap in combination with VS Code. The same techniques can also be used in other IDEs. Debugging clang-compiled binaries with gdb is possible, but requires more scripting. This guide comes with a basic GDB script for coroutine debugging. This guide will first showcase the more polished, bleeding-edge experience, but will also show you how to debug coroutines with older toolchains.

In general, the older your toolchain, the deeper you will have to dive into the implementation details of coroutines (such as their ABI). The further down you go in this document, the more low-level, technical the content will become. If you are on an up-to-date toolchain, you will hopefully be able to stop reading earlier. Debugging generators # One of the two major use cases for coroutines in C++ is generators, i.e., functions which can produce values via co_yield .

Values are produced lazily, on-demand. For this purpose, every time a new value is requested, the coroutine gets resumed. As soon as it reaches a co_yield and thereby returns the requested value, the coroutine is suspended again. This logic is encapsulated in a generator type similar to this one: // generator.hpp #include <coroutine> // `generator` is a stripped down, minimal generator type. template < typename T > struct generator { struct promise_type { T current_value {}; auto get_return_object () { return std :: coroutine_handle < promise_type >:: from_promise ( * this ); } auto initial_suspend () { return std :: suspend_always (); } auto final_suspend () noexcept { return std :: suspend_always (); } auto return_void () { return std :: suspend_always (); } void unhandled_exception () { __builtin_unreachable (); } auto yield_value ( T v ) { current_value = v ; return std :: suspend_always (); } }; generator ( std :: coroutine_handle < promise_type > h ) : hdl ( h ) { hdl . resume (); } ~ generator () { hdl . destroy (); } generator < T >& operator ++ () { hdl . resume (); return * this ; } // resume the coroutine T operator * () const { return hdl . promise (). current_value ; } private : std :: coroutine_handle < promise_type > hdl ; }; We can then use this generator class to print the Fibonacci sequence: #include "generator.hpp" #include <iostream> generator < int > fibonacci () { co_yield 0 ; int prev = 0 ; co_yield 1 ; int current = 1 ; while ( true ) { int next = current + prev ; co_yield next ; prev = current ; current = next ; } } template < typename T > void print10Elements ( generator < T >& gen ) { for ( unsigned i = 0 ; i < 10 ; ++ i ) { std :: cerr << * gen << " \n " ; ++ gen ; } } int main () { std :: cerr << "Fibonacci sequence - here we go \n " ; generator < int > fib = fibonacci (); for ( unsigned i = 0 ; i < 5 ; ++ i ) { ++ fib ; } print10Elements ( fib ); } To compile this code, use clang++ --std=c++23 generator-example.cpp -g .

Breakpoints inside the generators # We can set breakpoints inside coroutines just as we set them in regular functions. For VS Code, that means clicking next the line number in the editor. In the lldb CLI or in gdb , you can use b to set a breakpoint. Inspecting variables in a coroutine # If you hit a breakpoint inside the fibonacci function, you should be able to inspect all local variables ( prev , current , next ) just like in a regular function.

Note the two additional variables __promise and __coro_frame . Those show the internal state of the coroutine. They are not relevant for our generator example but will be relevant for asynchronous programming described in the next section. Stepping out of a coroutine # When single-stepping, you will notice that the debugger will leave the fibonacci function as soon as you hit a co_yield statement. You might find yourself inside some standard library code.

After stepping out of the library code, you will be back in the main function. Stepping into a coroutine # If you stop at ++fib and try to step into the generator, you will first find yourself inside operator++ . Stepping into the handle.resume() will not work by default. This is because lldb does not step into functions from the standard library by default. To make this work, you first need to run settings set target.process.thread.step-avoid-regexp "" .

You can do so from the “Debug Console” towards the bottom of the screen. With that setting change, you can step through coroutine_handle::resume and into your generator. You might find yourself at the top of the coroutine at first, instead of at your previous suspension point. In that case, single-step and you will arrive at the previously suspended co_yield statement. Inspecting a suspended coroutine # The print10Elements function receives an opaque generator type.

Let’s assume we are suspended at the ++gen; line and want to inspect the generator and its internal state. To do so, we can simply look into the gen.hdl variable. LLDB comes with a pretty printer for std::coroutine_handle which will show us the internal state of the coroutine. For GDB, the pretty printer is provided by a script, see GDB Debugger Script for setup instructions. We can see two function pointers resume and destroy .

These pointers point to the resume / destroy functions. By inspecting those function pointers, we can see that our generator is actually backed by our fibonacci coroutine. When using VS Code + lldb-dap, you can Cmd+Click on the function address ( 0x555... in the screenshot) to jump directly to the function definition backing your coroutine handle. Next, we see the promise . In our case, this reveals the current value of our generator.

The coro_frame member represents the internal state of the coroutine. It contains our internal coroutine state prev , current , next . Furthermore, it contains many internal, compiler-specific members, which are named based on their type. These represent temporary values which the compiler decided to spill across suspension points, but which were not declared in our original source code and hence have no proper user-provided name.

Tracking the exact suspension point # Among the compiler-generated members, the __coro_index is particularly important. This member identifies the suspension point at which the coroutine is currently suspended. However, it is non-trivial to map this number back to a source code location. For GDB, the provided GDB Debugger Script already takes care of this and provides the exact line number of the suspension point as part of the coroutine handle’s summary string.

Unfortunately, LLDB’s pretty-printer does not support this, yet. Furthermore, those labels are only emitted starting with clang 21.0. When debugging with LLDB or when using older clang versions, we will have to use a different approach. For simple cases, you might still be able to guess the suspension point correctly. Alternatively, you might also want to modify your coroutine library to store the line number of the current suspension point in the promise: // For all promise_types we need a new `_coro_return_

The rest of this page is on the live site.