<!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">P0664R6</td>
</tr>
<tr>
<td align="left">Revises</td>
<td align="left">P0664R5</td>
</tr>
<tr>
<td align="left">Date:</td>
<td align="left">Revised 2018-10-04</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/N4760">N4760</a>.</p>
<p>Previous issue list is <a href="wg21.link/P0664R5">P0664R5</a>.</p>
<h2> Table of content </h2>

<ul>
  <li>
      CWG issues:
      <a href="#24">24</a>
      <a href="#25">25</a>
      <a href="#26">26</a>
      <a href="#27">27</a>
      <a href="#28">28</a>
      <a href="#33">33</a>
    </li>
<!--    <li>
      Adopted at Rapperswil 2018 issues: <a href="#29">29</a>
    </li> -->
    <li>
        Not ready issues:
        <a href="#30">30</a>
        <a href="#31">31</a>
        <a href="#32">32</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>
-->

<!-- ================================================================================ -->
<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> Active
 <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><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>
<!--
 <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>

-->

<!-- --------------------------------------------------------------------------------------- -->
<h3><a name="25" href="#25">25.</a> Allow unhandled exception escape the user-defined body of 
  the coroutine and give it well defined semantics </h3>
  <p><b>Section:</b> 11.4.4 [dcl.fct.def.coroutine] <b>Status:</b>
    Active
   <b>Submitter:</b> Eric Niebler <b>Opened:</b> 2018-03-10 <b>Last modified:</b> 2018-05-05</p>

   <p><i>[EWG Approved Rapperswil-2018/06/09]</i></p>

   <p><b>Issue:</b></p>
  <p>
    Currently, an unhandled exception can never escape the user-authored 
    body of the coroutine with triggering undefined behavior. 
  
    <blockquote>
        <pre>
            {
              P p;
              co_await p.initial_suspend(); <i>// initial suspend point</i>
              try {
                F  // user authored body
              } catch(...) { p.unhandled_exception(); }
            <i>final_suspend</i>:
              co_await p.final_suspend(); <i></i>// final suspend point</i>
            }  
          </pre>
    </blockquote>
    
  <p>
  An exception from <code>F</code> is captured by the try-catch and
  a customization point <code>unhandled_exception</code> is called,
  where, typically, an exception_ptr is created and propagated to
  the consumer awaiting on async task, or, in case of a generator,
  will be delivered to the user
  when they dereference the iterator.
  </p>
  <p>
  Though the current behavior is perfectly reasonable for asynchronous
  scenarios, it is sub-optimal <!-- creates optimizing difficulties in the case of --> 
  for synchronous generators. Capturing an exception, storing it in an 
  <code>exception_ptr</code> and then rethrowing the exception during,
  say, iterator's <code>operator*</code> is a needless work if the desired
  behavior is to let the exception propagate to the caller
  whenever it asks for the next value.
   <!-- out if no exception
  was actually thrown by the user-authored body.-->
  </p>
  <p><b>Background information:</b>
  When a coroutine is first invoked, any exception thrown before entering
  the user-authored body (for example allocation failure, promise constructor failure,
  failure to copy parameters, etc) propagates into the caller as with any 
  normal function call. However, when the coroutine suspends and subsequently resumed, 
  if an exception is thrown by an evaluation of 
  <code><em>p</em>.unhandled_exception()</code> or 
  an evaluation of <code>co_await <em>p</em>.final_suspend()</code>
  the behavior is undefined. Note that a coroutine can be only resumed or destroyed
  when suspended at a particular suspend point. An exception leaving the coroutine
  at arbitrary point of the execution leaves the coroutine in the undefined state.
  </p>
  <p>
    The proposed resolution is to eliminate the undefined behavior in the following manner:
    <ol>
      <li>Allow an exception to escape <code><em>p</em>.unhandled_exception()</code>
        and, in that case, consider the coroutine to be at the final suspend point. Reminder: when
        a coroutine is at the final suspend point, the coroutine can only be
        destroyed and a call to member function <code>done()</code> of the 
        coroutine handle associated with that coroutine returns <code>true</code>.
      </li>
      <li>
        Eliminate possibility of an exception being thrown from 
        evaluation of an expression <code>co_await <em>p</em>.final_suspend()</code>
        by stating that <code>final_suspend</code> member function of
        the coroutine promise and <code>await_resume</code>, <code>await_ready</code>,
        and <code>await_suspend</code> members of the object returned from 
        <code>final_suspend</code> shall have non-throwing exception specification.
      </li>
    </ol>
  </p>
  <p>
    This resolution allows generator implementations to define <code>unhandled_exception</code>
    as follows:
    <pre>  void unhandled_exception() { throw; } </pre>
    With this implementation, if a user of the generator pulls the next value,
    and during computation of the next value an exception will occur in the 
    user authored body it will be propagate back to the user and the coroutine
    will be put into a final suspend state and ready to be destroyed when
    generator destructors is run.
  </p>
  <p><b>Proposed Wording:</b></p>
  In subclause 11.4.4, add two new paragraph after paragraph 11.

  <p>
  <ol start=12>
    <li><ins>If the evaluation of an expression <code><em>p</em>.unhandled_exception()</code>
      exits via an exception, the coroutine is considered suspended at the final suspend point.
     </ins></li>
     <li><ins>
      The member functions <code>final_suspend</code>, 
      <code>await_resume</code>, <code>await_ready</code>,
      <code>await_suspend</code> and <code>operator co_await</code> (if any)
      used in evaluation of <code></code>
      expression <code>co_await <em>p</em>.final_suspend()</code> shall 
      have non-throwing exception specification.
</ins></li>
  </ol>
</p>

<!-- --------------------------------------------------------------------------------------- -->
<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>
      Active
     <b>Submitter:</b> Gor Nishanov <b>Opened:</b> 2018-03-10 <b>Last modified:</b> 2018-03-10</p>

     <p><i>[EWG Approved Rapperswil-2018/06/09]</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>

(3.5) — h is an object of type <ins>convertible to</ins> std::experimental::coroutine_handle&lt;P&gt; referring to the enclosing coroutine.

</blockquote>

<h3><a name="27" href="#27">27.</a> Make suspension in dynamic initializers of <code>static</code> and <code>thread_local</code> local variables ill-formed</h3>
    <p><b>Section:</b> 8.3.8/2 [expr.await] <b>Status:</b>
      Active
     <b>Submitter:</b> Richard Smith <b>Opened:</b> 2018-03-25 <b>Last modified:</b> 2018-03-25</p>

     <p><i>[EWG Approved Rapperswil-2018/06/09]</i></p>

     <p><b>Proposed wording:</b></p>

Add underlined text to 8.3.8/2:

<blockquote>
An <i>await-expression</i> shall appear only in a potentially-evaluated
expression within the <i>compound-statement</i> of a <i>function-body</i> 
outside of a <i>handler</i> (Clause 18). 
In a declaration-statement or in
the simple-declaration (if any) of a for-init-statement, an await-expression shall appear only in
an initializer of that declaration-statement or 
simple-declaration<ins> unless it is used to initialize a block-scope variable with static or thread storage duration</ins>.
</blockquote>

<!--
<hr>
 ================================================================================ 
<h2>CWG issues </h2>
-->
<hr>
<!-- --------------------------------------------------------------------------------------- -->
<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>
      Active
     <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]

<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> Active <b>Submitter:</b> Mathias Stearn <b>Opened:</b> 2018-06-09 

<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>
<!--
<h3><a name="29" href="#29">29.</a> Simplify wording for 11.4.4/7 and /8</h3>
    <p><b>Section:</b> 11.4.4 [dcl.fct.def.coroutine] <b>Status:</b>
      Active
     <b>Submitter:</b> Ben Craig <b>Opened:</b> 2018-03-20 <b>Last modified:</b> 2018-03-20</p>
<p><b>Proposed wording improvement:</b></p>

Modify paragraph 7 and 8 of 11.4.4 as follows:

<blockquote>
  <dl>
    <dt>7</dt>
    <dd> An implementation may need to allocate additional storage for a 
    coroutine. This storage is known as the coroutine state and is obtained by calling 
    <ins>the coroutine allocator</ins>. <del> a non-array allocation 
      function (6.7.4.1). The allocation function’s name is looked up in 
      the scope of P. If this lookup fails, the allocation function’s name
       is looked up in the global scope. If the lookup finds an allocation
        function in the scope of P, overload resolution is performed on a 
        function call created by assembling an argument list. 
        The first argument is the amount of space requested, 
        and has type std::size_t. The lvalues p1 ... pn are the succeeding 
        rguments. If no viable function is found, overload resolution is 
        performed again on a function call created by passing just the amount of 
        space required as an argument of type std::size_t.</del>
    </dd>
    </dl>
    
    <dl>
      <dt>8</dt>
    <dd>
    The unqualified-id get_return_object_on_allocation_failure is looked up in the scope of 
    class P by class member access lookup (3.4.5). If a declaration is found, then the 
    result of a call to <ins>the coroutine allocator</ins> <del>an allocation function 
      used to obtain storage for the coroutine state</del> is assumed to return nullptr 
      if it fails to obtain storage <del>, and if a global allocation function is selected, 
        the ::operator new(size_t, nothrow_t) form shall be used</del>. 
        If an allocation function returns nullptr, the coroutine returns control to the 
        caller of the coroutine and the return value is obtained by a call to
         P::get_return_object_on_allocation_failure(). The allocation function used 
         in this case must have a non-throwing noexcept-specification.
    </dd>
    </dl>
</blockquote>
Add new paragraph after paragraph 8 of 11.4.4 as follows:
<blockquote>
  <ins>
    The coroutine allocator is a non array allocation function (6.7.4.1).
    The allocation function’s name is looked up in the scope of P.
    If this lookup fails, the allocation function’s name is looked up in the global
    scope.  If the lookup finds an allocation function in the scope of P,
    overload resolution is performed on a function call created by assembling an
    argument list.  The first argument is the amount of space requested, and has type
    size_t.  If the unqualified-id get_return_object_on_allocation_failure declaration
    is found when looked up in the scope of class P by class member access lookup (6.4.5),
    then the second argument has type <code>nothrow_t</code> and the allocation function
    must have a non-throwing noexcept-specification.  If the unqualified-id 
    <code>get_return_object_on_allocation_failure</code> declaration is not found, 
    then lvalues p1 … pn are the succeeding arguments.  If no matching function is
    found for the size_t, p1 … pn argument list, then overload resolution is performed
    again on a function call created by passing just the amount of space required as an
    argument of type <code>size_t</code>.
  </ins>
</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="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> Not ready <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>

<!-- --------------------------------------------------------------------------------------- -->
<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> Not ready <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>
  <em>Paper requested. Volunteer found</em>
</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> Not ready <b>Submitter:</b> SG1 <b>Opened:</b> 2018-06-08 

<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>Paper requested. Volunteer found</em>
</p>

</body>
</html>
