<!DOCTYPE html>
    <html>
    <head>
        <meta http-equiv="Content-type" content="text/html;charset=UTF-8">
        <title>P0912R5 - Merge Coroutines TS into C++20 working draft</title>
        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/katex.min.css" integrity="sha384-9eLZqc9ds8eNjO3TmqPeYcDj8n+Qfa4nuSiGYa6DjLNcv9BtN69ZIulL9+8CqC9Y" crossorigin="anonymous">
        <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/Microsoft/vscode/extensions/markdown-language-features/media/markdown.css">
        <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/Microsoft/vscode/extensions/markdown-language-features/media/highlight.css">
        <link href="https://cdn.jsdelivr.net/npm/katex-copytex@latest/dist/katex-copytex.min.css" rel="stylesheet" type="text/css">
        <style>
.task-list-item { list-style-type: none; } .task-list-item-checkbox { margin-left: -20px; vertical-align: middle; }
</style>
        <style>
            body {
                font-family: -apple-system, BlinkMacSystemFont, 'Segoe WPC', 'Segoe UI', 'Ubuntu', 'Droid Sans', sans-serif;
                font-size: 14px;
                line-height: 1.6;
            }
        </style>
        
        <script src="https://cdn.jsdelivr.net/npm/katex-copytex@latest/dist/katex-copytex.min.js"></script>
    </head>
    <body>
        <style type="text/css">
    p {text-align:justify}
    li {text-align:justify}
    blockquote.note
    {
      background-color:#E0E0E0;
      padding-left: 15px;
      padding-right: 15px;
      padding-top: 1px;
      padding-bottom: 1px;
    }
    ins {background-color:#A0FFA0}
    del {background-color:#FFA0A0}
    table {border-collapse: collapse;}
    table, th, td {
      border: 1px solid black;
      border-collapse: collapse;
    }
  </style>
<table>
<thead>
<tr>
<th>Document Number:</th>
<th>P0912R5</th>
</tr>
</thead>
<tbody>
<tr>
<td>Date:</td>
<td>2019-02-22</td>
</tr>
<tr>
<td>Audience:</td>
<td>WG21</td>
</tr>
<tr>
<td>Revises:</td>
<td>P0912R4</td>
</tr>
<tr>
<td>Reply to:</td>
<td><a href="mailto:gorn@microsoft.com">gorn@microsoft.com</a></td>
</tr>
</tbody>
</table>
<h1 id="merge-coroutines-ts-into-c20-working-draft">Merge Coroutines TS into C++20 working draft</h1>
<h2 id="abstract">Abstract</h2>
<p>This paper proposes merging Working Draft of Coroutines TS [N4775] into the C++20 working draft [N4800].</p>
<h2 id="revision-history">Revision history</h2>
<p>r0: initial revision</p>
<p>r1:</p>
<ul>
<li>Markdown rendered as HTML.</li>
<li>Replaced ligature ff with two letters ff.</li>
<li>Expanded on compiler availability.</li>
<li>Reworded the closing paragraph.</li>
<li>Make insertions <ins>green</ins>.</li>
<li>Updated working draft numbers</li>
</ul>
<p>r2:</p>
<ul>
<li>... keywords s/were/are added ...</li>
<li>P0664R3 =&gt; P0664R4</li>
<li>Added list of edits requested by LWG on 2018-06-08.</li>
</ul>
<p>r3:</p>
<ul>
<li>document numbers and edition instructions updated</li>
</ul>
<p>r4:</p>
<ul>
<li>document numbers and edition instructions updated</li>
</ul>
<p>r5:</p>
<ul>
<li>incorporated the resolutions to Coroutines Issues #25 #27 (<a href="https://wg21.link/P1356R0">https://wg21.link/P1356R0</a>)</li>
<li>incorporated the resolution to Coroutines Issues #31 #35 (<a href="https://wg21.link/P0664R7">https://wg21.link/P0664R7</a>)</li>
</ul>
<h2 id="introduction">Introduction</h2>
<ul>
<li>Coroutines of this kind were available in a shipping compiler since 2014.</li>
<li>We have been receiving and acting upon developer feedback for 5 years.</li>
<li>The software built using coroutines has been deployed on more than <strong>400 million</strong> devices in the hands of delighted consumers.</li>
<li>The software built using coroutines on Linux and Windows is powering the foundational services of Windows Azure cloud services.</li>
<li>Coroutines have been used by thousands of software developers in various companies.</li>
<li>We have two publicly available implementations of coroutines TS in MSVC since version 2015 SP2 (2016) and clang version 5 (2017).</li>
<li>We have an independent coroutine implementation in EDG frontend (2015).</li>
<li>GCC implementation is in progress.</li>
<li>There are several open source coroutine abstraction libraries, including an extensive open source coroutine library <a href="https://github.com/lewissbaker/cppcoro">cppcoro</a> that utilizes most of the coroutine features with tests that can be used to smoke test emerging coroutine implementation for completeness and correctness.</li>
<li>Other libraries provide coroutines TS bindings for its types, for example, Facebook's Folly, Just::Thread Pro and others.</li>
</ul>
<p>Coroutines address the dire need by dramatically simplifying development of asynchronous code.
Coroutines have been available and in use for 5 years. We have shipping implementations from two major
compiler vendors. It is time to merge Coroutines TS to the working paper.</p>
 <!-- to unblock development related libraries utilizing coroutine language facilities. -->
<h2 id="wording">Wording</h2>
<ul>
<li>
<p>Apply coroutine wording from N4775 to the working draft with the following changes:</p>
<ul>
<li>replace <code>experimental::</code> with nothing</li>
<li>replace <code>&lt;experimental/coroutine&gt;</code> with <code>&lt;coroutine&gt;</code></li>
<li>in synopsis in [coroutine.trivial.awaitables] and [support.coroutine]
<ul>
<li>remove &quot;namespace experimental {&quot; and &quot;} // namespace experimental&quot;</li>
<li>remove &quot;inline namespace coroutines_v1 {&quot; and &quot;} // namespace coroutines_v1&quot;</li>
</ul>
</li>
<li>exclude changes to [stmt.iter] and [stmt.ranged] (issue #35 incorporated)</li>
<li>LaTex specific instructions: before applying the changes, in the coroutine TS LaTeX source, replace all occurrences of \cxxref{<i>stable-name</i>} with \ref{<i>stable-name</i>}.</li>
</ul>
</li>
<li>
<p>Add underlined text to rationale in [diff.cpp17.lex]:</p>
</li>
</ul>
<blockquote>
<p><strong>Rationale:</strong> Required for new features. The <code>requires</code> keyword is added to introduce constraints through a <em>requires-clause</em> or a <em>requires-expression</em>. The <code>concept</code> keyword is added to enable the definition of concepts (12.6.8). <ins>The <code>co_await</code>, <code>co_yield</code>, and <code>co_return</code> keywords are added to enable the definition of coroutines (\ref{dcl.fct.def.coroutine}).</ins> Effect on original feature: Valid ISO C++ 2017 code using <code>concept</code><ins>, <code>co_await</code>, <code>co_yield</code>, <code>co_return</code>,</ins> or <code>requires</code> as an identifier is not valid in this International Standard.</p>
</blockquote>
<ul>
<li>Add underlined text to &quot;Effect on original feature&quot; in [diff.cpp17.library]:</li>
</ul>
<blockquote>
<p><strong>Effect on original feature:</strong> The following C++ headers are new: <code>&lt;compare&gt;</code><ins>, <code>&lt;coroutine&gt;</code>,</ins> and <code>&lt;syncstream&gt;</code>. Valid C++ 2017 code that #includes headers with these names may be invalid in this International Standard.</p>
</blockquote>
<ul>
<li>Apply the following modifications that implement the resolutions of issues 25, 27, and 31</li>
<li>modify [expr.await]/2 as follows:</li>
</ul>
<blockquote>
<p>An <em>await-expression</em> shall appear only in a potentially-evaluated expression within the <em>compound-statement</em> of a <em>function-body</em> outside of a <em>handler</em> (Clause 18). In a declaration-statement or in the simple-declaration (if any) of a for-init-statement, an <del>await-expression</del><ins><em>await-expression</em></ins> shall appear only in an initializer of that declaration-statement or simple-declaration. <ins>An <em>await-expression</em> shall not appear in the initializer of a block-scope variable with static or thread storage duration.</ins></p>
</blockquote>
<ul>
<li>in section [dcl.fct.def.coroutine] add two paragraphs after paragraph 11:</li>
</ul>
<blockquote>
<p><ins>12. If the evaluation of the expression <em>p</em><code>.unhandled_exception()</code> exits via an exception, the coroutine is considered suspended at the final suspend point.</ins></p>
</blockquote>
<blockquote>
<p><ins>13. The expression <code>co_await</code> <em>p</em><code>.final_suspend()</code> shall not be potentially-throwing ([except.spec]).</ins></p>
</blockquote>
<ul>
<li>add the underlined text at the beginning of [coroutine.handle.resumption]:</li>
</ul>
<blockquote>
<p><ins>1. Resuming a coroutine via <code>resume</code>, <code>operator()</code>, or <code>destroy</code> on an execution agent other than the one it was suspended on has implementation-defined behavior unless each is either an instance of <code>std::thread</code> or the thread that executes <code>main</code>.</ins></p>
</blockquote>
<blockquote>
<p><ins><i>[Note:</i> A coroutine that is resumed on a different execution agent should avoid relying on consistent thread identity throughout, such as holding a mutex object across a suspend point. — <i>end note ]</i></ins></p>
</blockquote>
<blockquote>
<p><ins><i>[Note:</i> A concurrent resumption of the coroutine may result in a data race. — <i>end note ]</i></ins></p>
</blockquote>
<ul>
<li>remove all occurrences of this note from [coroutine.handle.resumption]:</li>
</ul>
<blockquote>
<p><del><i>[ Note:</i> A concurrent resumption of the coroutine via resume, operator(), or destroy may result in a data race. <i>—end note ]</i></del></p>
</blockquote>

    </body>
    </html>