================
@@ -8,470 +8,966 @@ Debugging C++ Coroutines
Introduction
============
-For performance and other architectural reasons, the C++ Coroutines feature in
-the Clang compiler is implemented in two parts of the compiler. Semantic
-analysis is performed in Clang, and Coroutine construction and optimization
-takes place in the LLVM middle-end.
+Coroutines in C++ were introduced in C++20, and their user experience for
+debugging them can still be challenging. This document guides you 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 will introduce foundational debugging techniques also
+applicable to the debugging of asynchronous programming.
+
+Both compilers (clang, gcc, ...) and debuggers (lldb, gdb, ...) are
+still improving their support for coroutines. As such, we recommend to use the
+latest available version of your toolchain.
+
+This document focuses on clang and lldb. The screenshots show
+[lldb-dap](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.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 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
+====================
+
+The first major use case for coroutines in C++ are generators, i.e. functions
+which can produce values via ``co_yield``. Values are produced lazily,
+on-demand. For that 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
-However, this design forces us to generate insufficient debugging information.
-Typically, the compiler generates debug information in the Clang frontend, as
-debug information is highly language specific. However, this is not possible
-for Coroutine frames because the frames are constructed in the LLVM middle-end.
-
-To mitigate this problem, the LLVM middle end attempts to generate some debug
-information, which is unfortunately incomplete, since much of the language
-specific information is missing in the middle end.
+.. code-block:: c++
-This document describes how to use this debug information to better debug
-coroutines.
+ // generator.hpp
+ #include <coroutine>
-Terminology
-===========
+ // `generator` is a stripped down, minimal generator type.
+ template<typename T>
+ struct generator {
+ struct promise_type {
+ T current_value{};
-Due to the recent nature of C++20 Coroutines, the terminology used to describe
-the concepts of Coroutines is not settled. This section defines a common,
-understandable terminology to be used consistently throughout this document.
+ 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();
+ }
+ };
-coroutine type
---------------
+ generator(std::coroutine_handle<promise_type> h) : hdl(h) { hdl.resume(); }
+ ~generator() { hdl.destroy(); }
-A `coroutine function` is any function that contains any of the Coroutine
-Keywords `co_await`, `co_yield`, or `co_return`. A `coroutine type` is a
-possible return type of one of these `coroutine functions`. `Task` and
-`Generator` are commonly referred to coroutine types.
+ generator<int>& operator++() { hdl.resume(); return *this; } // resume the
coroutine
+ int operator*() const { return hdl.promise().current_value; }
----------------
JFinis wrote:
```suggestion
generator<T>& operator++() { hdl.resume(); return *this; } // resume the
coroutine
T operator*() const { return hdl.promise().current_value; }
```
https://github.com/llvm/llvm-project/pull/142651
_______________________________________________
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
