{"id":8605,"date":"2023-11-13T11:11:14","date_gmt":"2023-11-13T11:11:14","guid":{"rendered":"https:\/\/www.modernescpp.com\/?p=8605"},"modified":"2023-11-22T18:20:56","modified_gmt":"2023-11-22T18:20:56","slug":"a-concise-introduction-to-coroutines-by-dian-lun-li","status":"publish","type":"post","link":"https:\/\/www.modernescpp.com\/index.php\/a-concise-introduction-to-coroutines-by-dian-lun-li\/","title":{"rendered":"A Concise Introduction to Coroutines by Dian-Lun Lin"},"content":{"rendered":"\n

Today, I will start a miniseries about a scheduler for tasks. The starting point of this miniseries is a straightforward scheduler by Dian-Lun Lin that becomes increasingly sophisticated.<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

I have already written around 15 posts about coroutines<\/a>. They explain the theory about coroutines and apply this theory in various ways. However, I still fight for an intuitive introduction to a non-trivial coroutine use case. I was, therefore, pretty happy to watch Dian-Lun Lin CppCon 2022 talk: “An Introduction to C++ Coroutines through a Thread Scheduling Demonstration<\/a>“. <\/p>\n\n\n\n

Today, I’m happy to present a guest post by Dian-Lun Lin. He will intuitively introduce coroutines to implement a straightforward scheduler that dispatches tasks. I will use this scheduler as a starting point for further experiments.<\/p>\n\n\n\n

An Introduction to C++ Coroutines<\/h2>\n\n\n\n

A coroutine is a function that can suspend itself and be resumed by the caller. Unlike regular functions, which execute sequentially from start to finish, coroutines allow for controlled suspension and resumption of execution. This enables us to write code that looks synchronous but can efficiently handle asynchronous operations without blocking the calling thread.
Implementing a C++ coroutine can be a bit challenging due to its versatility. In C++ coroutines, you can fine-tune how a coroutine behaves in numerous ways. For example, you can decide whether a coroutine should be suspended when it starts or finishes, and you can precisely adjust when and where these suspensions occur within the coroutine. To illustrate, let’s begin with a straightforward example:<\/p>\n\n\n\n

\/\/ simpleCoroutine.cpp<\/span>\n\n#include <coroutine><\/span>\n#include <iostream><\/span>\n\nstruct<\/span> MyCoroutine {                             \/\/ (1)<\/span>\n    struct<\/span> promise_type {\n        MyCoroutine get_return_object() {\n            return<\/span> std::<\/span>coroutine_handle<<\/span>promise_type>::<\/span>from_promise(*<\/span>this<\/span>);\n        }\n        std::<\/span>suspend_always initial_suspend() {\n            return<\/span> {};\n        }\n        std::<\/span>suspend_always final_suspend() noexcept {\n            return<\/span> {};\n        }\n        void<\/span> return_void() {}\n        void<\/span> unhandled_exception() {}\n    };\n    MyCoroutine(std::<\/span>coroutine_handle<<\/span>promise_type><\/span> handle):<\/span> handle{handle} {}\n    \n    void<\/span> resume() { \n        handle.resume(); \n    }\n    void<\/span> destroy() { \n        handle.destroy(); \n    }\n    \n    std::<\/span>coroutine_handle<<\/span>promise_type><\/span> handle;\n};\n\nMyCoroutine simpleCoroutine<\/span>() {                      \/\/ (2)<\/span>\n    std::<\/span>cout <<<\/span> "Start coroutine<\/span>\\n<\/span>"<\/span>;\n    co_await std::<\/span>suspend_always{};\n    std::<\/span>cout <<<\/span> "Resume coroutine<\/span>\\n<\/span>"<\/span>;\n}\n\nint<\/span> main<\/span>() {\n    MyCoroutine coro =<\/span> simpleCoroutine();\n    std::<\/span>cout <<<\/span> "Coroutine is not executed yet<\/span>\\n<\/span>"<\/span>;\n    coro.resume();\n    std::<\/span>cout <<<\/span> "Suspend coroutine<\/span>\\n<\/span>"<\/span>;\n    coro.resume();\n    coro.destroy();\n    return<\/span> 0<\/span>;\n}\n<\/pre><\/div>\n\n\n\n

This example code demonstrates the basic usage of C++ coroutines and provides an example of a custom coroutine. To implement a C++ coroutine, you must understand four essential components: Coroutine<\/em>, Promise type<\/em>, Awaitable<\/em>, and Coroutine handle<\/em>. I will explain each component through the example code in the following sections.<\/p>\n\n\n\n
Coroutine<\/h3>\n\n\n\n
In C++, coroutines are implemented through the co_return<\/code>, co_await<\/code>, and co_yield <\/code>keywords. These keywords allow developers to express asynchronous behavior in a structured and intuitive way. In the example coroutine, simpleCoroutine<\/code>, I call co_await std::suspend always{}<\/code> to suspend the coroutine. The std::suspend_always <\/code>is a C++ standard provided awaitable that always suspends the coroutine.
<\/p>\n\n\n\n
When you call the function simpleCoroutine<\/code>, it doesn\u2019t execute the coroutine immediately. Instead, it returns a coroutine object that defines promise type<\/code>. Line (2) defines the function simpleCoroutine <\/code>that returns a MyCoroutine <\/code>object. In line (1), I define the MyCoroutine <\/code>class and the promise type. You might wonder why calling a coroutine function doesn\u2019t immediately execute it. Again, this is because C++ Coroutine is designed to be flexible. C++ Coroutine allows you to decide when and how a coroutine should begin and end. This is defined in the promise_type<\/code>.<\/p>\n\n\n\n
Promise Type<\/h3>\n\n\n\n
A promise_type <\/code>controls a coroutine\u2019s behavior. Here are the key responsibilities of a promise_type<\/code>:<\/p>\n\n\n\n
    \n
  • Creating the Coroutine Object: The get_return_object <\/code>function creates an instance of the coroutine and returns it to the caller.<\/li>\n\n\n\n
  • Controlling Suspension: The initial_suspend <\/code>and final_suspend <\/code>functions determine whether the coroutine should be suspended or resumed at the beginning and the end. They return awaitables that dictate how the coroutine behaves.<\/li>\n\n\n\n
  • Handling Return Values: The return_value <\/code>function sets the return value of the coroutine when it completes. It enables the coroutine to produce a result that the caller can retrieve. In the example code, I use return_void<\/code>, indicating this coroutine does not have the return value.<\/li>\n\n\n\n
  • Handling Exceptions: The unhandled_exception <\/code>function is invoked when an unhandled exception occurs within the coroutine. It provides a mechanism to handle exceptions gracefully.<\/li>\n<\/ul>\n\n\n\n
    But where is the promise_type <\/code>used? I do not see the word \u201dpromise\u201d in the example code. Actually, when you write your coroutine, the compiler sees your code slightly differently. The compiler\u2019s simplified view of simpleCoroutine <\/code>is the following:<\/p>\n\n\n\n
    MyCoroutine simpleCoroutine<\/span>() {\n    MyCoroutine::<\/span>promise_type p();\n    MyCoroutine coro_obj =<\/span> p.get_return_object();\n\n    try {\n      co_await p.inital_suspend();\n      std::<\/span>cout <<<\/span> "Start coroutine<\/span>\\n<\/span>"<\/span>;\n      co_await std::<\/span>suspend_always{};\n      std::<\/span>cout <<<\/span> "Resume coroutine<\/span>\\n<\/span>"<\/span>;\n    } catch<\/span>(...) {\n      p.unhandled_exception();\n    }\n    co_await p.final_suspend();\n}\n<\/pre><\/div>\n\n\n\n
    That\u2019s why you need to define promise_type <\/code>in the MyCoroutine <\/code>class. When simpleCoroutine <\/code>is called, the compiler creates a promise_type <\/code>and calls get_return_object<\/code>() to create the MyCoroutine <\/code>object. Before the coroutine body, the compiler calls initial_suspend <\/code>to determine whether to suspend at the beginning. Finally, it calls final_suspend <\/code>to determine whether to suspend at the end. You will get compilation errors if you don\u2019t define promise_type <\/code>and its corresponding functions.<\/p>\n\n\n\n
    Awaitable<\/h3>\n\n\n\n
    An awaitable controls a suspension point behavior. Three functions need to be defined for an awaitable:<\/p>\n\n\n\n
      \n
    • await_ready<\/code><\/strong>: This function determines whether the coroutine can proceed without suspension. It should return true<\/code> if the operation is ready to continue immediately, or false <\/code>if suspension is required. This method is an optimization that allows you to avoid the cost of suspension in cases where it is known that the operation will be completed synchronously.<\/li>\n\n\n\n
    • await_suspend<\/code><\/strong>: This function provides fine-grained control over a suspension point behavior. It passes the current coroutine handle for users to resume the coroutine later or destroy the coroutine. There are three return types for this function:\n
        \n
      • void<\/strong><\/code>: We suspend the coroutine. The control is immediately returned to the caller of the current coroutine.<\/li>\n\n\n\n
      • bool<\/strong><\/code>: If true<\/code>, we suspend the current coroutine and return control to the caller; If false<\/code>, we resume the current coroutine.<\/li>\n\n\n\n
      • coroutine_handle<\/strong><\/code>: We suspend the current coroutine and resume that returned coroutine handle. This is also called asymmetric transfer.<\/li>\n<\/ul>\n<\/li>\n\n\n\n
      • await_resume<\/strong><\/code>: This function specifies what value should be returned to the coroutine when the awaited operation is complete. It resumes the coroutine\u2019s execution, passing the awaited result. If no result is expected or needed, this function can be empty and return void<\/code>.<\/li>\n<\/ul>\n\n\n\n
        But where are these functions used? Again, let\u2019s look into the compiler\u2019s view. When you call co_await std:suspend_always{}<\/code>, the compiler will transform it into the following code:<\/p>\n\n\n\n
        auto<\/span>&&<\/span> awaiter =<\/span> std::<\/span>suspend_always{};\n  if<\/span>(!<\/span>awaiter.await_ready()) {\n    awaiter.await_suspend(std::<\/span>coroutine_handle<><\/span>...);\n    \/\/<suspend\/resume><\/span>\n  }\nawaiter.await_resume();\n<\/pre><\/div>\n\n\n\n
        That\u2019s why you need to define all these functions. The std::suspend_always<\/code> is a C++ built-in awaitable that defines the functions as follows:<\/p>\n\n\n\n
        struct<\/span> suspend_always {\n    constexpr bool<\/span> await_ready() const<\/span> noexcept { return<\/span> false<\/span>; }\n    constexpr void<\/span> await_suspend(coroutine_handle<><\/span>) const<\/span> noexcept {}\n    constexpr void<\/span> await_resume() const<\/span> noexcept {}\n};\n<\/pre><\/div>\n\n\n\n
        Coroutine Handle<\/h3>\n\n\n\n
        Coroutine handles are used to manage the state and lifecycle of a coroutine. They provide a way to access, resume, and destroy coroutines explicitly. In the example, I call handle.resume() <\/code>to resume the coroutine and call handle.destroy()<\/code> to destroy the coroutine.<\/p>\n\n\n\n

        After executing the program, the results are the following:<\/p>\n\n\n\n
        \"\"<\/figure>\n\n\n\n
        What’s Next?<\/h2>\n\n\n\n
        As promised, this post from Dian-Lun Lin was a concise introduction to coroutines. In the next post, Dian-Lun applies the theory to implement a single-threaded scheduler for C++ coroutines.<\/p>\n","protected":false},"excerpt":{"rendered":"
        Today, I will start a miniseries about a scheduler for tasks. The starting point of this miniseries is a straightforward scheduler by Dian-Lun Lin that becomes increasingly sophisticated. I have already written around 15 posts about coroutines. They explain the theory about coroutines and apply this theory in various ways. However, I still fight for […]<\/p>\n","protected":false},"author":21,"featured_media":8607,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[375],"tags":[445],"class_list":["post-8605","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-c-20","tag-coroutines"],"_links":{"self":[{"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/posts\/8605","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/users\/21"}],"replies":[{"embeddable":true,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/comments?post=8605"}],"version-history":[{"count":35,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/posts\/8605\/revisions"}],"predecessor-version":[{"id":8741,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/posts\/8605\/revisions\/8741"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/media\/8607"}],"wp:attachment":[{"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/media?parent=8605"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/categories?post=8605"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/tags?post=8605"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}