<!DOCTYPE html><html><head><meta charset="utf-8"><title>D1610 Rename await_resume() to await_result().md</title><style></style></head><body id="preview">
<h1><a id="P1610R0_Rename_await_resume_to_await_result_0"></a>P1610R0 Rename <code>await_resume()</code> to <code>await_result()</code></h1>
<p>By: <a href="mailto:redbeard0531@gmail.com">Mathias Stearn</a> (MongoDB)<br>
Date: 2019-03-10</p>
<h2><a id="What_5"></a>What?</h2>
<p>The coroutine feature recently approved for C++20 defines an API for types that support being <code>co_await</code>ed, consisting of three methods: <code>await_ready()</code>, <code>await_suspend()</code>, and <code>await_resume()</code>. This paper proposes to rename the last to <code>await_result()</code>, which better reflects its purpose and effects.</p>
<h2><a id="Why_9"></a>Why?</h2>
<ul>
<li>What does this method do? It returns the <strong>result</strong> of the co_<strong>await</strong> expression!</li>
<li><code>await_resume()</code> is called even when the coroutine isn’t suspended if <code>await_ready()</code> returns <code>true</code>, so there is no resuming to be done.</li>
<li>It looks like it has symmetry with <code>await_suspend()</code>, but that’s a lie. They are almost completely unrelated.</li>
<li>It is attached to Awaitables, but you don’t resume Awaitables, you resume coroutines.  This subject-object confusion is particularly problematic when writing a coroutine type that is also an Awaitable, such as <code>Future</code> or <code>Task</code>. When you define the <code>await_resume()</code> method for such a type, you need to remember that it isn’t called when the coroutine that your are defining is resumed. Instead, it is called when the consuming coroutine resumes, to get the <em>result</em> of this coroutine.</li>
</ul>
<p><strong>Summary</strong>: This change makes the Awaitable API more intuitive, therefore easier to teach and learn. This is important because that API is the second layer in the “Gor Table” from section 4.4 of <a href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2018/p1362r0.pdf">P1362</a>, so it will be the first form of coroutine customization most users will do.</p>
<h2><a id="Why_not_18"></a>Why not?</h2>
<ul>
<li>Incompatibility with existing code written against the TS. However,
<ul>
<li>We don’t promise compatibility for TSs.</li>
<li>Implementations would be allowed (encouraged?) to fallback to the old name if the new one isn’t present for some transition period.</li>
</ul>
</li>
</ul>
<h2><a id="What_to_do_about_the_TS_24"></a>What to do about the TS?</h2>
<p>If we want to ease the transition, we can add explicit wording to the TS to work with both names. We would need to either prefer one if both are present, or just make that ill-formed.</p>

</body></html>