{"id":105019,"date":"2021-03-30T07:00:00","date_gmt":"2021-03-30T14:00:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/oldnewthing\/?p=105019"},"modified":"2021-04-01T07:57:43","modified_gmt":"2021-04-01T14:57:43","slug":"20210330-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20210330-00\/?p=105019","title":{"rendered":"C++ coroutines: Basic implementation of a promise type"},"content":{"rendered":"

Last time, we diagrammed out how the pieces of a coroutine fit together<\/a>. Today we’ll fill in the diagram with code.<\/p>\n

Fortunately, most of the hard work has already been done for us by the result_holder<\/code> class we already wrote. We just need to adapt it to the format required by the coroutine specification.<\/p>\n

namespace std::experimental\r\n{\r\n    template <typename T, typename... Args>\r\n    struct coroutine_traits<result_holder<T>, Args...>\r\n    {\r\n        struct promise_type\r\n        {\r\n            result_holder<T> holder;\r\n\r\n            result_holder<T> get_return_object() const noexcept\r\n            {\r\n                return holder;\r\n            }\r\n\r\n            void return_value(T const& v) const\r\n            {\r\n                holder.set_result(v);\r\n            }\r\n\r\n            void unhandled_exception() const noexcept\r\n            {\r\n                holder.set_exception(std::current_exception());\r\n            }\r\n\r\n            suspend_never initial_suspend() const noexcept\r\n            {\r\n                return{};\r\n            }\r\n\r\n            suspend_never final_suspend() const noexcept\r\n            {\r\n                return{};\r\n            }\r\n        };\r\n    };\r\n}\r\n<\/pre>\n
When the compiler encounters a function which contains a co_await<\/code> or co_return<\/code>, it realizes that it’s dealing with a coroutine. It collects the following:<\/p>\n
    \n
  • The return type of the function.<\/li>\n
  • The type of *this<\/code>, if it’s defined as an instance member function.<\/li>\n
  • The types of the parameters, if any.<\/li>\n<\/ul>\n
    It takes all of these types and looks for a coroutine_traits<\/code> specialization that matches it. For example, given<\/p>\n
    ReturnType FreeFunction(ArgType1& arg1, ArgType2 arg2);\r\n<\/pre>\n
    the compiler looks for the type<\/p>\n
    std::experimental::coroutine_traits<\r\n    ReturnType, ArgType1&, ArgType2>\r\n<\/pre>\n
    For an instance method<\/p>\n
    ReturnType SomeClass<\/span>::Member(ArgType1& arg1, ArgType2 arg2) const<\/span>;\r\n<\/pre>\n
    the compiler looks for<\/p>\n
    std::experimental::coroutine_traits<\r\n    ReturnType, SomeClass<\/span> const<\/span>&, ArgType1&, ArgType2>\r\n<\/pre>\n
    In practice, few coroutines care about anything other than the return type, so you will generally see the second and subsequent template type parameters declared but ignored.\u00b9<\/p>\n
    The specialized coroutine_traits<\/code> must have a nested type called promise_type<\/code>. This could be defined inline or it could be an alias (via typedef<\/code> or using<\/code>) for another type define elsewhere.<\/p>\n
    The promise_type<\/code> is the promise object that is stored inside the coroutine state. The get_return_object()<\/code> method is called to create the thing that is returned to the caller of the coroutine. In our case, we want to return a copy of our result_holder<\/code>: The result_holder<\/code> state becomes the way that the coroutine and the caller communicate with each other:<\/p>\n\n\n\n\n\n\n
     <\/td>\n <\/td>\nCoroutine state<\/th>\n <\/td>\n <\/td>\n <\/td>\nCaller<\/th>\n<\/tr>\n
     <\/td>\n <\/td>\nbookkeeping<\/td>\n <\/td>\n <\/td>\n <\/td>\n <\/td>\n<\/tr>\n
    promise<\/td>\n\n
    \u00a0<\/div>\n<\/td>\n
    		holder<\/code><\/td>\n\u2192<\/td>\nresult_holder<\/code> state<\/td>\n\u2190<\/td>\nholder<\/code><\/td>\n<\/tr>\n
     <\/td>\n <\/td>\nstack frame<\/td>\n <\/td>\n <\/td>\n <\/td>\n <\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    When the coroutine reaches its co_return<\/code>, the compiler calls p.return_value()<\/code> with the returned value, which we pass onward to the holder by calling set_value<\/code>. (If there is no returned value, then the compiler uses p.return_void()<\/code>.)\u00b2 That will in turn update the state, and the state will release any waiting coroutines, which resumes the caller.<\/p>\n
    On the other hand, if an exception escapes the coroutine, then the compiler will call p.unhandled_exception()<\/code>, and we deal with the exception by stowing it in the holder<\/code>. Again, this will update the state, and the state will release any waiting coroutines, which resumes the caller. And when the caller performs an await_result<\/code> to obtain the result of the co_await<\/code>, our state<\/code> object rethrows the exception.<\/p>\n
    So that’s the magic of how the result of the coroutine (either a return value or an exception) gets transferred from the coroutine back to the awaiter.<\/p>\n
    Wait, what are these last two method initial_suspend<\/code> and final_suspend<\/code>? We’ll look at those next time.<\/p>\n
    \u00b9 You could create fancy coroutines that change their implementation depending on what the parameters are. For example, you might define a marker type like<\/p>\n
    struct with_sugar_t {};\r\ninline constexpr with_sugar_t with_sugar{};\r\n<\/pre>\n
    and then have a special version of the result_holder<\/code> coroutine promise that is used if the coroutine function is declared as<\/p>\n
    result_holder<int> Nicely(with_sugar_t);\r\n<\/pre>\n
    Okay, so I don’t have a really good motivation for this feature, but it does exist.<\/p>\n
    \u00b2 It is illegal to have both return_value<\/code> and return_void<\/code> in a promise type, even if one of them is removed by SFINAE:<\/p>\n
                template<typename Dummy = void>\r\n            std::enable_if_t<std::is_same_v<T, void>, Dummy>\r\n                return_void() const\r\n            {\r\n                holder.set_result(); \r\n            }\r\n\r\n            template<typename Dummy = void>\r\n            std::enable_if_t<!std::is_same_v<T, void>, Dummy>\r\n                return_value(T const& value) const\r\n            {\r\n                holder.set_result(value); \r\n            }\r\n<\/pre>\n
    The reason is that in order for the compiler to perform substitution in order to determine which methods are callable, it needs to know what was passed to all of the co_return<\/code> statements, so it can try substituting them into return_value<\/code>‘s parameter and see which ones succeed. But it hasn’t started compiling the coroutine function body yet, so it doesn’t know what to try to substitute for value<\/code>.<\/p>\n
    This is a frustrating limitation because it prevents you from writing a single promise that covers both void<\/code>-completing coroutines and value-completing coroutines. You always have to make two types, one for return_void<\/code> and another for return_value<\/code>.<\/p>\n","protected":false},"excerpt":{"rendered":"
    Filling in the diagram with code.<\/p>\n","protected":false},"author":1069,"featured_media":111744,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[25],"class_list":["post-105019","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"
    Filling in the diagram with code.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/105019","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/users\/1069"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/comments?post=105019"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/105019\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media\/111744"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media?parent=105019"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=105019"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=105019"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}