<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
    "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta charset="utf-8">
<title>C++ Coroutine TS Issues</title>
<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>
</head>
<body>
<h1>C++ Coroutine TS Issues</h1>
<table>
<tr>
<td align="left">Doc. no.</td>
<td align="left">P0664R8</td>
</tr>
<tr>
<td align="left">Revises</td>
<td align="left">P0664R7</td>
</tr>
<tr>
<td align="left">Date:</td>
<td align="left">Revised 2019-02-21</td>
</tr>
<tr>
<td align="left">Project:</td>
<td align="left">Programming Language C++</td>
</tr>
<tr>
<td align="left">Reference:</td>
<td align="left">ISO/IEC TS 22277, C++ Extensions for Coroutines</td>
</tr>
<tr>
<td align="left">Audience:</td>
<td align="left">CWG</td>
</tr>
<tr>
<td align="left">Reply to:</td>
<td align="left">Gor Nishanov &lt;<a href="mailto:gorn@microsoft.com">gorn@microsoft.com</a>&gt;</td>
</tr>
</table>
<h2> Introduction </h2>
<p>All proposed resolutions wording is relative to <a href="https://wg21.link/N4775">N4775</a>.</p>
<p>Previous issue list is <a href="wg21.link/P0664R7">P0664R7</a>.</p>
<h2> Table of content </h2>

<ul>
  <li>
      CWG Issues:
      <a href="#24">24</a>
      <a href="#33">33</a>
      <a href="#34">34</a>
    </li>
  <li>
    Resolved issues:
    <a href="#28">28</a>
    <a href="#31">31</a>
    <a href="#32">32</a>
    <a href="#35">35</a>
  </li>

<!--    <li>
      Adopted at Rapperswil 2018 issues: <a href="#29">29</a>
    </li> -->
    <li>
        Not ready issues:
        <a href="#26">26</a>
        <a href="#30">30</a>
      </li>
    </ul>
<!--
<h2> Table of content </h2>

<ul>
  <li>
    <b>[CWG Approved Toronto-7/12/2017]</b> Coroutine issues reviewed and approved by CWG: <a href="#2">2</a> <a href="#6">6</a> <a href="#7">7</a> <a href="#18">18</a> <a href="#21">21</a>
  </li>
  <li>
    <b>[LWG Approved Toronto-7/11/2017]</b> Coroutine issues reviewed and approved by LWG: <a href="#9">9</a> <a href="#10">10</a> <a href="#11">11</a> <a href="#14">14</a> <a href="#15">15</a> <a href="#22">22</a> <a href="#23">23</a>
  </li>
  <br>
  <i>Issues rejected or requiring no action for now:</i>
  <br><br>
  <li>
    Core comments requesting rebase of a TS to C++17: <a href="#3">3</a> <a href="#5">5</a> <a href="#17">17</a>
  </li>
  <li>
    Core comments (no action): <a href="#4">4</a>
  </li>
  <li>
    Core comments (rejected, no consensus for change): <a href="#8">8</a>
  </li>
  <li>
    LWG issues with no wording: <a href="#12">12</a> <a href="#16">16</a> <a href="#19">19</a> <a href="#20">20</a>
  </li>
  <li>
     Evolution issues with no wording: <a href="#1">1</a> <a href="#13">13</a>
</ul>
-->

<hr>
<!-- ================================================================================ -->
<h2>CWG issues </h2>
<hr>
<!-- --------------------------------------------------------------------------------------- -->
<h3><a name="24" href="#24">24.</a>
  The specification of initial suspend point does not correctly captures the intent</h3>
  <p><b>Section:</b> 11.4.4 [dcl.fct.def.coroutine] <b>Status:</b> Ready
   <b>Submitter:</b> Gor Nishanov <b>Opened:</b> 2018-03-08 <b>Last modified:</b> 2018-05-05</p>

   <p><i>[EWG Approved Rapperswil-2018/06/09]</i></p>
   <p><i>[San Diego-2018/11/10: Alternative resolution for this issue is proposed. Waiting for details]</i></p>
   <p><i>[EWG Alternative resolution was not accepted -2019/02/20]</i></p>

  <p><b>Issue:</b></p>
  <p>
      Common use of the <code>initial_suspend</code> point in asynchronous coroutines is to suspend the coroutine
      during the initial invocation and post a request to resume the coroutine by a different execution agent.
      If an execution agent at a later point cannot resume the coroutine, for example, because it is being shutdown,
      an error will be reported to a coroutine by resuming the coroutine
      and subsequently throwing an exception from <code>await_resume</code>.
  </p>
  <p>
      Currently, the invocation of <code>initial_suspend</code> is specified in [dcl.fct.def.coroutine] as:
  </p>
  <pre>
    {
      P p;
      co_await p.initial_suspend(); <i>// initial suspend point</i>
      try { F } catch(...) { p.unhandled_exception(); }
    <i>final_suspend</i>:
      co_await p.final_suspend(); <i></i>// final suspend point</i>
    }
  </pre>
  <p>
    As specified, an exception from <code>await_resume</code> of <code>initial_suspend</code> will be thrown
    outside of the <code>try-catch</code> and will not be captured by <code>p.unhandled_exception()</code> and
    whoever waits for eventual completion of a coroutine will never learn about its completion.
  </p>
  <p>
    This is a specification defect. The intent is to capture an exception thrown by <code>await_resume</code> of
    an awaitable returned by <code>initial_suspend</code> within the <code>try-catch</code> enclosing of
    the user authored body <code>F</code>.
  </p>
  <p>
  The correct behavior has been implemented in MSVC staring with version 2015 and in clang trunk.
  </p>

  <p><b>Proposed resolution:</b></p>

  <p>Add underlying text to paragraph 11.4.4/3 as follows:<p>
    <blockquote>
        <pre>
            {
              P p;
              co_await p.initial_suspend(); <i>// initial suspend point</i>
              try {
                F
              } catch(...) { p.unhandled_exception(); }
            <i>final_suspend</i>:
              co_await p.final_suspend(); <i></i>// final suspend point</i>
            }
          </pre>
          <ins>except that any exception thrown after the <i>initial suspend point</i>
            and before the flow of execution reaches <i>F</i> also results in
            entering the <i>handler</i> of the <i>try-block</i> and,</ins>
            where an object denoted as <i>p</i> is the <em>promise object</em> of the coroutine
            and its type <em>P</em> is the <em>promise type</em> of the coroutine, ...
          </blockquote>

<hr>
<!-- --------------------------------------------------------------------------------------- -->
<h3><a name="33" href="#33">33.</a> Parameter copy wording does not capture the intent. </h3>
<p><b>Section:</b> 11.4.4/11 [dcl.fct.def.coroutine] <b>Status:</b> Ready <b>Submitter:</b> Mathias Stearn <b>Opened:</b> 2018-06-09

<p><i>[Clarification Requested by CWG - San Diego - 2018/11/07]</i></p>
<p><i>[EWG: Yes, we meant it! - Kona - 2019/02/21]</i></p>

<p><b>Issue:</b></p>
<p>
  The intent is that copies/moves of parameters (if required) are created
  preserving the exact type (including references, r-references, etc).
  The wording in 11.4.4[dcl.fct.def.coroutine]/11 does not seem to
  express that clearly.
</p>
<p><b>Proposed wording:</b></p>

Modify paragraph 11 of 11.4.4/[dcl.fct.def.coroutine] as follows:

<blockquote>

When a coroutine is invoked, a copy is created for each coroutine parameter. Each such copy
is an object <ins>or reference</ins> with automatic storage duration <ins>and has the same type as the corresponding parameter.</ins>
<del>that</del><ins>Each copy</ins> is direct-initialized <ins>([dcl.init])</ins> from
<del>an lvalue referring to</del>
the corresponding parameter<del> if the parameter is an lvalue reference, and from an xvalue referring
to it otherwise</del>. <ins>If the type of the copy is an rvalue reference type, then, for the purpose of this initialization
  the value category of the corresponding parameter is an rvalue.</ins>
A <del>reference to</del><ins>use of</ins> a parameter in the function-body of the coroutine and in the call
to the coroutine promise constructor is replaced by <del>a reference to</del> its copy. The initialization and
destruction of each parameter copy occurs in the context of the called coroutine. Initializations
of parameter copies are sequenced before the call to the coroutine promise constructor and
indeterminately sequenced with respect to each other. The lifetime of parameter copies ends
immediately after the lifetime of the coroutine promise object ends. [ <i>Note:</i> If a coroutine has a
parameter passed by reference, resuming the coroutine after the lifetime of the entity referred to
by that parameter has ended is likely to result in undefined behavior. <i>—end note</i> ]

</blockquote>

<hr>
<!-- --------------------------------------------------------------------------------------- -->
<h3><a name="34" href="#34">34.</a> Mandate the return type for return_void and return_value to be <code>void.</code> </h3>
<p><b>Status:</b> Active <b>Submitter:</b> Gor Nishanov <b>Opened:</b> 2018-01-16

<p><b>Issue:</b></p>
<p>
  Mandate that the return type of <code>return_value</code> and <code>return_void</code>
  customization points to be of type <code>void</code> to leave room for
  possible future evolution.
</p>
<p><b>Proposed wording attempt 1:</b></p>
Modify the paragraph 2 of [stmt.return.coroutine] as follows:

<blockquote>
    <p>
    (2.1) -- <em>S</em> is <em>p</em><code>.return_value(</code><em>expr-or-braced-init-list</em><code>)</code>,
    if the operand is a <em>braced-init-list</em> or an expression of non-<code>void</code> type;
    </p>
    <p>
      (2.1) -- <em>S</em> is <code>{</code> <em>expression</em><sub>opt</sub> <code>; p.return_void(); }</code>, otherwise;
    </p>
    <p>
    <em>S</em> shall be a prvalue of type void. <ins><em>p</em><code>.return_void()</code> shall be a prvalue of type <code>void</code>.</ins>
    </p>
</blockquote>

<p><b>Proposed wording attempt 2:</b></p>
Add new paragraph after paragraph 3 of [stmt.return.coroutine]:
<blockquote>
  <p>
    3. If <em>p</em><code>.return_void()</code> is a valid expression, flowing off the end of a coroutine is equivalent to a
    <em>co_return</em> with no operand; otherwise flowing off the end of a coroutine results in undefined
    behavior.
  </p>
  <p><ins>
      4. The return type of <code>return_void</code> and
      <code>return_value</code> shall be <code>void</code>.
    </ins>
    </p>
  </blockquote>



<!--
<p><b>Recommendation:</b></p>

<p> Defer resolution of this issue until proposed change is implemented and tried out on existing code. </p>
-->
<!-- <i>[Accepted: Jacksonville-3/10/2018]</i> -->

<!-- <i>[Reject. No consensus for change. Toronto-7/10/2017]</i> -->

<!-- --------------------------------------------------------------------------------------- -->

<!--
<h3><a name="29" href="#29">29.</a>  Make coroutine handle comparison operators stricter</h3>
<p><b>Section:</b> 21.11.2.6 [coroutine.handle.compare] <b>Status:</b> Active <b>Submitter:</b> (Unknown passerby) <b>Opened:</b> 2018-03-08 <b>Last modified:</b> 2018-03-08</p>

<p><b>Issue:</b></p>
<p>
  Coroutine handle comparisons operators are defined with signature:
</p>
<pre>
    constexpr bool operator@(coroutine_handle&lt;&gt; x, coroutine_handle&lt;&gt; y) noexcept;
</pre>
<p>
  where <code>@</code> is one of the operators <code>== != &lt; &gt; &lt;= &gt;=</code>.
</p>
<p>
  This allows comparisons of coroutine handles with unrelated promise types (due to implicit conversion of
  <code>coroutine_handle&lt;Whatever&gt;</code> to <code>coroutine_handle&lt;&gt;</code>.
  This is probably not beneficial to the user.
  </p><p>The suggestion is to alter
  the coroutine comparison operators to have the signature:
</p>
<pre>
    <ins>template &lt;class Promise&gt;</ins>
    constexpr bool operator@(coroutine_handle&lt;<ins>Promise</ins>&gt; x, coroutine_handle&lt;<ins>Promise</ins>&gt; y) noexcept;
</pre>
<p>
  where <code>@</code> is one of the operators <code>== != &lt; &gt; &lt;= &gt;=</code>.
</p>
-->
<!-- <i>[Reject. No consensus for change. Toronto-7/10/2017]</i> -->

<hr>
<!-- ================================================================================ -->
<h2>Not ready issues </h2>

<hr>
<!-- --------------------------------------------------------------------------------------- -->
<h3><a name="26" href="#26">26.</a> Relax requirements on a coroutine_handle passed to <code>await_suspend</code> </h3>
    <p><b>Section:</b> 8.3.8 [expr.await] <b>Status:</b>
      Waiting for more information
     <b>Submitter:</b> Gor Nishanov <b>Opened:</b> 2018-03-10 <b>Last modified:</b> 2018-11-10</p>

     <p><i>[EWG Approved Rapperswil-2018/06/09]</i></p>
     <p><i>[San Diego-2018/11/10: Alternative resolution for this issue is proposed. Waiting for details.] </i></p>

     <p><b>Issue:</b></p>
<p>
  One of the implementation strategies for coroutines is to chop
  original function into as many functions (parts) as there are suspend points.
  In that case, it is possible for a compiler create a unique
  per suspend per function <code>coroutine_handle</code> which
  <code>resume</code>
  and <code>destroy</code> members can be direct calls to corresponding
  parts of the function.
</p>
<p>Though no compiler is doing it now, we can allow implementors
  to experiment with this approach by relaxing the requirement
  on the <code>coroutine_handle</code> passed
  to <code>await_suspend</code>.
</p>
<p><b>Proposed wording:</b></p>

Add underlined text to 8.3.8/3.5:

<blockquote>
  <!--of a class type that is either-->
(3.5) — h is an object of <ins>a class</ins> type <ins>that is either</ins> std::experimental::coroutine_handle&lt;P&gt;
<ins>or that has a public and unambiguous base class of type std::experimental::coroutine_handle&lt;P&gt;</ins>
referring to the enclosing coroutine.

</blockquote>


  <!--
   <p><b>Proposed resolution #1 (easy but still does not capture the intent):</b></p>

  <p>Modify paragraph 5.3.8/3 as follows:<p>
  <blockquote>
      <pre>
          {
            P p;
            <ins>try {</ins>
              co_await p.initial_suspend(); <i>// initial suspend point</i>
            <del>try {</del>
              F
            } catch(...) { p.unhandled_exception(); }
          <i>final_suspend</i>:
            co_await p.final_suspend(); <i></i>// final suspend point</i>
          }
        </pre>
  </blockquote>
  Though this is easy to specify, it violates the design intent.
  Specified in this form, it will capture exceptions that occur
  in the call to <code>initial_suspend</code> and calls to
  <code>await_ready</code> and <code>await_suspend</code> of
  the returned awaitable.

  <p><b>Proposed resolution #2 (help with wording needed):</b></p>
  We probably need to rework 8.4.4/3 from being a pseudocode into a
  description with pure words as the desired behavior is not
  directly expressible in pseudocode. </p>
  <p>
  Here is an unsatisfactory description of the desired behavior in pseudo pseudocode.
  <blockquote>
    <pre>
        {
          P p;
          <ins>{</ins>
            <ins>auto &amp;&amp; <i>init</i> = </ins><del>co_await</del> p.initial_suspend(); <i>// initial suspend point</i>
            <ins>// await_ready and await_suspend of expansion of</ins>
            <ins>// co_await of <i>init</i> called here</ins>
            try {
              <ins>// await_resume of expansion of</ins>
              <ins>// co_await of <i>init</i> called here</ins>
                F
            } catch(...) { p.unhandled_exception(); }
          <ins>}</ins>
        <i>final_suspend</i>:
          co_await p.final_suspend(); <i></i>// final suspend point</i>
        }
      </pre>
  </blockquote>
  </p>

  -->
<hr>
<!-- --------------------------------------------------------------------------------------- -->
<h3><a name="30" href="#30">30.</a> Re-enable coroutine return type
deduction when coroutine <code>task</code> and <code>generator</code>
types are available </h3>
<p><b>Section:</b> 10.1.7.4 [coroutine.handle] <b>Status:</b> Waiting for paper <b>Submitter:</b> Gor Nishanov <b>Opened:</b> 2018-05-05 <b>Last modified:</b> 2018-05-05</p>

<p><b>Issue:</b></p>
<p>
  We stripped out automatic return type deduction for coroutines from N4499 in 2015.
  Put back the wording to do it once the appropriate types are available
  in the standard library.
</p>

<hr>
<!-- ================================================================================ -->
<h2>Resolved issues </h2>

<!-- --------------------------------------------------------------------------------------- -->
<h3><a name="28" href="#28">28.</a> Simplify stable name for Coroutines to be [def.coroutine] </h3>
    <p><b>Section:</b> 11.4.4 [dcl.fct.def.coroutine] <b>Status:</b> Resolved
     <b>Submitter:</b> Gor Nishanov <b>Opened:</b> 2018-03-10 <b>Last modified:</b> 2018-03-10</p>
<p><b>Proposed wording:</b></p>
[<del>dcl.fct.</del>def.coroutine]
<p><i>[Editor of C++ WD will decide on the stable name during merge]</i></p>

<!-- --------------------------------------------------------------------------------------- -->
<h3><a name="31" href="#31">31.</a> Add a note warning about thread switching near await and/or coroutine_handle wording. </h3>
<p><b>Status:</b> Adopted <b>Submitter:</b> SG1 <b>Opened:</b> 2018-06-08

<p><b>Issue:</b></p>
<p>
  Add a note warning about thread switching near await and/or coroutine_handle wording
</p>

<p><b>Proposed wording</b></p>
<p><i>[LWG Approved Kona-2019/02/19]</i></p>
<p><i>[This wording per SG1 also addresses issue 32]</i></p>
<p><i>[Incorporated in the working draft]</i></p>

<p>
  Modify [coroutine.handle.resumption] as follows:

  <blockquote>
      <p><b>xx.xx.xx coroutine_handle resumption [coroutine.handle.resumption]</b></p>

      <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>
      <p><i>[LWG question for CWG: "thread that executes main" or "thread of execution that executes main"?]</i></p>

      <p><ins>
      <em> [ Note:</em> 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. <em>— end note ]</em>
      </ins></p>
      <p><ins>
          <em> [ Note:</em> A concurrent resumption of the coroutine may
              result in a data race. <em>— end note ]</em>
       </p> </ins>

       <p>
         <code>
           void operator()() const; <br>
           void resume() const;
         </code>
          <p>
            ... <br>
              <del><em>[ Note: </em>A concurrent resumption of the coroutine via resume, operator(), or destroy may
result in a data race. <em>—end note ]</em></del>
            </p>
       </p>
       <p>
          <code>
            void destroy() const;
          </code>
           <p>
             ... <br>
               <del><em>[ Note: </em>A concurrent resumption of the coroutine via resume, operator(), or destroy may
 result in a data race. <em>—end note ]</em></del>
             </p>
        </p>
   </blockquote>

</p>

<hr>
<!-- --------------------------------------------------------------------------------------- -->
<h3><a name="32" href="#32">32.</a> Add a normative text making it UB to migrate coroutines between certain kind of execution agents. </h3>
<p><b>Status:</b> Resolved <b>Submitter:</b> SG1 <b>Opened:</b> 2018-06-08 <b>Resolved:</b> 2019-01-16

<p><b>Issue:</b></p>
<p>
  Add a normative text making it UB to migrate coroutines between certain kind of execution agents.
  Clarify that migrating between std::threads is OK. But migrating between CPU and GPU is UB.
</p>
  <p>
  <em>[Resolved by the wording offered in issue <a href="#31">31</a> - 2019/01/16]</em>
</p>
<hr>

<!-- --------------------------------------------------------------------------------------- -->
<h3><a name="35" href="#35">35.</a> Remove <code>for co_await</code> statement. </h3>
<p><b>Status:</b> Adopted <b>Submitter:</b> Gor Nishanov <b>Opened:</b> 2018-01-16
<p><i>[EWG Approved Kona-2019/02/19]</i></p>
<p><i>[Incorporated in the working draft]</i></p>

<p><b>Issue:</b></p>
<p>
  The wording <code>for co_await</code> statement makes assumptions of what
  future asynchronous generator interface will be. Remove it for now as not to
  constraint the design space for asynchronous generators.
</p>
<p><b>Proposed wording change:</b></p>
Strike sections [stmt.iter] and [stmt.ranged] from Coroutines TS working document.

</body>
</html>
