{"id":6095,"date":"2021-02-22T20:33:51","date_gmt":"2021-02-22T20:33:51","guid":{"rendered":"https:\/\/www.modernescpp.com\/index.php\/implementing-futures-with-coroutines\/"},"modified":"2023-09-28T06:56:01","modified_gmt":"2023-09-28T06:56:01","slug":"implementing-futures-with-coroutines","status":"publish","type":"post","link":"https:\/\/www.modernescpp.com\/index.php\/implementing-futures-with-coroutines\/","title":{"rendered":"Implementing Simple Futures with Coroutines"},"content":{"rendered":"

Instead of return<\/code>, a coroutine uses co_return<\/code> returning its result. In this post, I want to implement a simple coroutine using co_return.<\/p>\n

<\/p>\n

\"\"<\/p>\n

You may wonder: Although I have presented the theory behind coroutines<\/a>, I want to write once more about coroutines. My answer is straightforward and based on my experience. C++20 does not provide concrete coroutines. Instead, C++20 provides a framework for implementing coroutines. This framework consists of more than 20 functions, some of which you must implement and others can override. Based on these functions, the compiler generates two workflows, which define the behavior of the coroutine. To make it short. Coroutines in C++20 are double-edged swords. On one side, they give you enormous power; on the other side, they are pretty challenging to understand. I dedicated over 80 pages to coroutines in my book “C++20: Get the Details<\/a>“, which has not yet explained everything.<\/p>\n

From my experience, using simple coroutines and modifying them is the easiest – maybe only – way to understand them. And this is precisely the approach I’m pursuing in the following posts. I present simple coroutines and modify them. To make the workflow obvious, I put many comments inside and added only so much theory necessary to understand the internals of coroutines. My explanations are not complete and should only serve as a starting point to deepen your knowledge about coroutines.<\/p>\n

A Short Reminder<\/h2>\n

While you can only call a function<\/strong> and return from it, you can call a coroutine<\/strong>, suspend and resume it, and destroy a suspended coroutine.<\/p>\n

\"FunctionsVersusCoroutines\"<\/p>\n

With the new keywords co_await<\/code> and co_yield<\/code>, C++20 extends the execution of C++ functions with two new concepts.<\/p>\n

Thanks to co_await expression<\/code> it is possible to suspend and resume the execution of the expression. If you use co_await expression<\/code> in a function func<\/code>, the call auto getResult = func()<\/code> does not block if the function call’s result is unavailable. Instead of resource-consuming blocking, you have resource-friendly waiting.
\n<\/code><\/p>\n

co_yield<\/code> expression supports generator functions. The generator function returns a new value each time you call it. A generator function is a data stream from which you can pick values. The data stream can be infinite. Therefore, we are at the center of lazy evaluation with C++.<\/p>\n

Additionally, a coroutine does not return<\/code> its result, a coroutine does co_return<\/code>\u00a0 its result.<\/p>\n

<\/p>\n

\n
\/\/ ...\n\nMyFuture<<\/span>int<\/span>><\/span> createFuture() {\n    co_return 2021<\/span>;\n}\n\nint<\/span> main() {\n\n    auto<\/span> fut =<\/span> createFuture();\n    std::<\/span>cout <<<\/span> \"fut.get(): \"<\/span> <<<\/span> fut.get() <<<\/span> '\\n'<\/span>;\n\n}   \n<\/pre>\n<\/div>\n
In this straightforward example createFuture<\/code> is the coroutine because it uses one of the three new keywords co_return, co_yield,<\/code> or co_await<\/code> and it returns a coroutine MyFuture<int><\/code>. What? This is what often puzzled me. The name coroutine is used for two entities. Let me introduce two new terms. createFuture<\/code> is a coroutine factory <\/strong>that returns a coroutine object<\/strong> fut, <\/code>that can be used to ask for the result: fut.get()<\/code>.<\/p>\n
This theory should be enough. Let’s talk about co_return<\/code>.<\/p>\n
co_return<\/h2>\n
Admittedly, the coroutine in the following program eagerFuture.cpp<\/code> is the simplest coroutine, I can imagine that still does something meaningful: it automatically stores the result of its invocation.<\/p>\n
<\/p>\n
\n
\/\/ eagerFuture.cpp<\/span>\n\n#include <coroutine><\/span>\n#include <iostream><\/span>\n#include <memory><\/span>\n\ntemplate<\/span><<\/span>typename<\/span> T><\/span>\nstruct<\/span> MyFuture {\n    std::<\/span>shared_ptr<<\/span>T><\/span> value;                           \/\/ (3)<\/span>\n    MyFuture(std::<\/span>shared_ptr<<\/span>T><\/span> p):<\/span> value(p) {}\n    ~<\/span>MyFuture() { }\n    T get() {                                          \/\/ (10)<\/span>\n        return<\/span> *<\/span>value;\n    }\n\n    struct<\/span> promise_type {\n        std::<\/span>shared_ptr<<\/span>T><\/span> ptr =<\/span> std::<\/span>make_shared<<\/span>T><\/span>(); \/\/ (4)<\/span>\n        ~<\/span>promise_type() { }\n        MyFuture<T><\/span> get_return_object() {              \/\/ (7)<\/span>\n            return<\/span> ptr;\n        }\n        void<\/span> return_value(T v) {\n            *<\/span>ptr =<\/span> v;\n        }\n        std::<\/span>suspend_never initial_suspend() {          \/\/ (5)<\/span>\n            return<\/span> {};\n        }\n        std::<\/span>suspend_never final_suspend() noexcept {  \/\/ (6)<\/span>\n            return<\/span> {};\n        }\n        void<\/span> unhandled_exception() {\n            std::<\/span>exit(1<\/span>);\n        }\n    };\n};\n\nMyFuture<<\/span>int<\/span>><\/span> createFuture() {                         \/\/ (1)<\/span>\n    co_return 2021<\/span>;                                    \/\/ (9)<\/span>\n}\n\nint<\/span> main() {\n\n    std::<\/span>cout <<<\/span> '\\n'<\/span>;\n\n    auto<\/span> fut =<\/span> createFuture();\n    std::<\/span>cout <<<\/span> \"fut.get(): \"<\/span> <<<\/span> fut.get() <<<\/span> '\\n'<\/span>;   \/\/ (2)<\/span>\n\n    std::<\/span>cout <<<\/span> '\\n'<\/span>;\n\n}\n<\/pre>\n<\/div>\n
MyFuture<\/code> behaves as a future, which runs immediately (see “Asynchronous Function Calls<\/a>“). The call of the coroutine createFuture<\/code> (line 1) returns the future, and the call fut.get<\/code> (line 2) picks up the result of the associated promise.<\/p>\n
There is one subtle difference to a future: the return value of the coroutine createFuture<\/code> is available after its invocation. Due to the lifetime issues of the coroutine, the coroutine is managed by a std::shared_ptr<\/code> (lines 3 and 4). The coroutine always uses std::suspend_never<\/code> (lines 5 and 6) and, therefore, neither does suspend before it runs nor after. This means the coroutine is immediately executed when the function createFuture<\/code> is invoked. The member function get_return_object<\/code> (line 7) returns the handle to the coroutine and stores it in a local variable. return_value<\/code> (lines 8) stores the result of the coroutine, which was provided by co_return 2021<\/code> (line 9). The client invokes fut.get<\/code> (line 2) and uses the future as a handle to the promise. The member function get<\/code> finally returns the result to the client (line 10).<\/p>\n
\"eagerFuture\"<\/p>\n
You may think it is not worth implementing a coroutine that behaves just like a function. You are right! However, this simple coroutine is an ideal starting point for writing various implementations of futures.<\/p>\n
At this point, I should add a bit of theory.<\/p>\n
The Promise Workflow<\/h2>\n
When you use co_yield<\/code>, co_await<\/code>, or co_return<\/code> in a function, the function becomes a coroutine, and the compiler transforms its function body into something equivalent to the following lines.<\/p>\n
<\/p>\n
\n
{\n  Promise prom;                      \/\/ (1)<\/span>\n  co_await prom.initial_suspend();   \/\/ (2)<\/span>\n  try {                                         \n    <<\/span>function body>                  \/\/ (3)<\/span><\/span>\n  }\n  catch<\/span> (...) {\n    prom.unhandled_exception();\n  }\nFinalSuspend:<\/span>\n  co_await prom.final_suspend();     \/\/ (4)<\/span>\n}\n<\/pre>\n<\/div>\n
Do these function names sound familiar to you? Right! These are the member functions of the inner class promise_type<\/code>. Here are the steps the compiler performs when it creates the coroutine object as the return value of the coroutine factory createFuture<\/code>. It first creates the promise object (line 1), invokes its initial_suspend<\/code> member function (line 2), executes the body of the coroutine factory (line 3), and finally, calls the member function final_suspend<\/code> (line 4). Both member functions initial_suspend<\/code> and final_suspend<\/code> in the program eagerFuture.cpp<\/code> return the predefined awaitables std::suspend_never<\/code>.\u00a0 As its name suggests, this awaitable suspends never; hence, the coroutine object suspends never and behaves such as a usual function. An awaitable is something you can await on. The operator co_await needs an awaitable. I will write a post about the awaitable and the second awaiter workflow.<\/p>\n
From this simplified promise workflow, you can deduce which member functions the promise (promise_type<\/code>) at least needs:<\/p>\n