{"id":105063,"date":"2021-04-08T07:00:00","date_gmt":"2021-04-08T14:00:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/oldnewthing\/?p=105063"},"modified":"2021-04-06T21:50:40","modified_gmt":"2021-04-07T04:50:40","slug":"20210408-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20210408-00\/?p=105063","title":{"rendered":"C++ coroutines: Awaiting the simple_task"},"content":{"rendered":"

Last time, we accepted the parameter passed to co_return<\/code> and stored it into our promise<\/a>. This time, we’ll deal with the consumption side and wait for the answer to appear.<\/p>\n

        \/\/ \u27e6awaiter support methods\u27e7 \u2254\r\n        bool client_await_ready()\r\n        {\r\n            assert(m_waiting == nullptr);\r\n            return !m_holder.is_empty();\r\n        }\r\n\r\n        auto client_await_suspend(\r\n            std::experimental::coroutine_handle<> handle)\r\n        {\r\n            auto guard = std::lock_guard{ m_mutex };\r\n            if (!m_holder.is_empty()) return false;\r\n            m_waiting = handle;\r\n            return true;\r\n        }\r\n\r\n        T client_await_resume()\r\n        {\r\n            return m_holder.get_value();\r\n        }\r\n\r\n        auto get_awaiter() noexcept\r\n        {\r\n            \/\/ \u27e6return an awaiter that waits for the coroutine\r\n            \/\/ to complete\u27e7 \u2254\r\n            struct awaiter\r\n            {\r\n                simple_promise_base& self;\r\n\r\n                bool await_ready()\r\n                {\r\n                    return self.client_await_ready();\r\n                }\r\n\r\n                auto await_suspend(\r\n                    std::experimental::coroutine_handle<> handle)\r\n                {\r\n                    return self.client_await_suspend(handle);\r\n                }\r\n\r\n                T await_resume()\r\n                {\r\n                    return self.client_await_resume();\r\n                }\r\n            };\r\n            return awaiter{ *this };\r\n        }\r\n<\/pre>\n
The real work happens in the client_<\/code> methods in the simple_promise_base<\/code>, and the awaiter just forwards everything to those methods, so I’m going to talk about the awaiter and the client_<\/code> methods as if they were the same thing.<\/p>\n
Our awaiter’s await_ready<\/code> first asserts that nobody else is waiting for promise. We allow only one co_await<\/code> because multiple co_await<\/code> is not compatible with a move-only type: If the type is move-only, then you can’t return it more than once because returning it also gives it away. There’s nothing to return to the second co_await<\/code>.<\/p>\n
Moving the value in response to co_await<\/code> also avoids potentially-expensive copies.<\/p>\n
After the correctness check, we see if the awaited-for coroutine is still running by seeing if the result holder is still empty. If it’s not empty, then the coroutine has already produced a result; we return true<\/code> to go straight to await_resume<\/code>.<\/p>\n
If await_ready<\/code> concludes that the awaited-for coroutine is still running, then the compiler will suspend the current coroutine and then call await_suspend<\/code>. We use a mutex for this, because we need to avoid a race between signing up for resumption and the awaited-for coroutine reaching its final_suspend<\/code> (which resumes the coroutine). We make one last check if the awaited-for coroutine is still running, to close the race window where the awaited-for coroutine finishes in between the await_ready<\/code> and the acquisition of the lock in await_suspend<\/code>.<\/p>\n
When the coroutine resumes, await_resume<\/code> produces the value or rethrows the exception. Note that we specify the return type explicitly as T<\/code> rather than using auto<\/code>. This is important in the case where T<\/code> is a reference.<\/p>\n
The resumption occurs when the awaited-for coroutine reaches its final_suspend<\/code>.<\/p>\n
        auto final_suspend() noexcept\r\n        {\r\n            \/\/ \u27e6return an awaiter that decrements the reference count\r\n            \/\/  and resumes any awaiting coroutine\u27e7 \u2254\r\n            struct awaiter : std::experimental::suspend_always\r\n            {\r\n                simple_promise_base& self;\r\n                void await_suspend(std::experimental::coroutine_handle<>) const noexcept\r\n                {\r\n                    std::experimental::coroutine_handle<> handle;\r\n                    {\r\n                        auto guard = std::lock_guard{ self.m_mutex };\r\n                        handle = self.m_waiting;\r\n                    }\r\n                    self.decrement_ref();\r\n                    if (handle) handle.resume();\r\n                }\r\n            };\r\n            return awaiter{ {}, *this };\r\n        }\r\n<\/pre>\n
At final suspension, we first check to see if a coroutine is actively awaiting our result. This requires the mutex to avoid racing against the get_awaiter<\/code> we saw above.<\/p>\n
Once we capture the awaiting coroutine’s handle (if any), we decrement our own reference count, since the coroutine is no longer running. The only reference count remaining belongs to the simple_task<\/code>. (If the caller threw away the simple_task<\/code> without awaiting it, then that decrement will destruct the coroutine state immediately.)<\/p>\n
And then we resume the awaiting coroutine, if any. When that awaiting coroutine destructs the simple_task<\/code>, that will drop the reference count to zero and destruct the coroutine state.<\/p>\n
The last missing piece is the reference count management. Sadly, this is the largest single piece of the entire coroutine infrastructure, and it’s almost entirely uninteresting! We’ll take up the boring details next time.<\/p>\n
Bonus chatter<\/b>: It’s important that we wait until await_suspend<\/code> to decrement the reference on the promise, rather than doing it eagerly in await_ready<\/code>. The await_ready<\/code> method is called while the coroutine is still in the executing state, and you cannot destruct an executing coroutine. On the other hand, await_suspend<\/code> is called after the coroutine has transitioned to the suspended state, at which point it is now safe to destroy.<\/p>\n","protected":false},"excerpt":{"rendered":"
Let me know when it’s ready.<\/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-105063","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"
Let me know when it’s ready.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/105063","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=105063"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/105063\/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=105063"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=105063"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=105063"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}