[dcl.fct.def.coroutine] - C++20 → C++23

Files changed (1) hide show

tmp/tmpxxxnlvst/{from.md → to.md} +73 -66

tmp/tmpxxxnlvst/{from.md → to.md} RENAMED Viewed

@@ -31,19 +31,21 @@ task<void> g3(int a, ...) {     // error: variable parameter list not allowed
 — *end example*]
 The *promise type* of a coroutine is
 `std::coroutine_traits<R, P₁, …, Pₙ>::promise_type`, where `R` is the
-return type of the function, and `P₁` … `Pₙ` are the sequence of types
-of the function parameters, preceded by the type of the implicit object
-parameter [[over.match.funcs]] if the coroutine is a non-static member
-function. The promise type shall be a class type.
-In the following, `pᵢ` is an lvalue of type `Pᵢ`, where `p₁` denotes
-`*this` and `p_i+1` denotes the $i^\textrm{th}$ function parameter for a
-non-static member function, and `pᵢ` denotes the $i^\textrm{th}$
-function parameter otherwise.
 A coroutine behaves as if its *function-body* were replaced by:
 ``` bnf
 '{'
@@ -64,75 +66,81 @@ final-suspend ':'
 ```
 where
 - the *await-expression* containing the call to `initial_suspend` is the
-  *initial suspend point*, and
 - the *await-expression* containing the call to `final_suspend` is the
-  *final suspend point*, and
 - *initial-await-resume-called* is initially `false` and is set to
   `true` immediately before the evaluation of the *await-resume*
-  expression [[expr.await]] of the initial suspend point, and
 - *promise-type* denotes the promise type, and
 - the object denoted by the exposition-only name *`promise`* is the
   *promise object* of the coroutine, and
 - the label denoted by the name *`final-suspend`* is defined for
   exposition only [[stmt.return.coroutine]], and
 - *promise-constructor-arguments* is determined as follows: overload
   resolution is performed on a promise constructor call created by
-  assembling an argument list with lvalues `p₁` … `pₙ`. If a viable
- constructor is found [[over.match.viable]], then
- *promise-constructor-arguments* is `(p₁, …, pₙ)`, otherwise
-  *promise-constructor-arguments* is empty.
-The *unqualified-id*s `return_void` and `return_value` are looked up in
-the scope of the promise type. If both are found, the program is
 ill-formed.
-[*Note 1*: If the *unqualified-id* `return_void` is found, flowing off
-the end of a coroutine is equivalent to a `co_return` with no operand.
-Otherwise, flowing off the end of a coroutine results in undefined
-behavior [[stmt.return.coroutine]]. — *end note*]
 The expression `promise.get_return_object()` is used to initialize the
-glvalue result or prvalue result object of a call to a coroutine. The
-call to `get_return_object` is sequenced before the call to
 `initial_suspend` and is invoked at most once.
 A suspended coroutine can be resumed to continue execution by invoking a
 resumption member function [[coroutine.handle.resumption]] of a
 coroutine handle [[coroutine.handle]] that refers to the coroutine. The
-function that invoked a resumption member function is called the
 *resumer*. Invoking a resumption member function for a coroutine that is
 not suspended results in undefined behavior.
 An implementation may need to allocate additional storage for a
 coroutine. This storage is known as the *coroutine state* and is
 obtained by calling a non-array allocation function
 [[basic.stc.dynamic.allocation]]. The allocation function’s name is
-looked up in the scope of the promise type. 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 the promise type,
-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 `p₁` … `pₙ` are the
-succeeding arguments. If no viable function is found
-[[over.match.viable]], 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`.
-The *unqualified-id* `get_return_object_on_allocation_failure` is looked
-up in the scope of the promise type by class member access lookup
-[[basic.lookup.classref]]. If any declarations are found, then the
-result of a call to an allocation function used to obtain storage for
-the coroutine state is assumed to return `nullptr` if it fails to obtain
-storage, and if a global allocation function is selected, the
-`::operator new(size_t, nothrow_t)` form is used. The allocation
-function used in this case shall have a non-throwing
-*noexcept-specification*. If the allocation function returns `nullptr`,
-the coroutine returns control to the caller of the coroutine and the
-return value is obtained by a call to
 `T::get_return_object_on_allocation_failure()`, where `T` is the promise
 type.
 [*Example 2*:
@@ -147,11 +155,11 @@ struct generator {
   struct promise_type {
     int current_value;
     static auto get_return_object_on_allocation_failure() { return generator{nullptr}; }
     auto get_return_object() { return generator{handle::from_promise(*this)}; }
     auto initial_suspend() { return std::suspend_always{}; }
-    auto final_suspend() { return std::suspend_always{}; }
     void unhandled_exception() { std::terminate(); }
     void return_void() {}
     auto yield_value(int value) {
       current_value = value;
       return std::suspend_always{};
@@ -177,30 +185,28 @@ int main() {
 The coroutine state is destroyed when control flows off the end of the
 coroutine or the `destroy` member function
 [[coroutine.handle.resumption]] of a coroutine handle
 [[coroutine.handle]] that refers to the coroutine is invoked. In the
-latter case objects with automatic storage duration that are in scope at
-the suspend point are destroyed in the reverse order of the
-construction. The storage for the coroutine state is released by calling
-a non-array deallocation function [[basic.stc.dynamic.deallocation]]. If
-`destroy` is called for a coroutine that is not suspended, the program
-has undefined behavior.
-The deallocation function’s name is looked up in the scope of the
-promise type. If this lookup fails, the deallocation function’s name is
-looked up in the global scope. If deallocation function lookup finds
-both a usual deallocation function with only a pointer parameter and a
-usual deallocation function with both a pointer parameter and a size
-parameter, then the selected deallocation function shall be the one with
-two parameters. Otherwise, the selected deallocation function shall be
-the function with one parameter. If no usual deallocation function is
-found, the program is ill-formed. The selected deallocation function
-shall be called with the address of the block of storage to be reclaimed
-as its first argument. If a deallocation function with a parameter of
-type `std::size_t` is used, the size of the block is passed as the
-corresponding argument.
 When a coroutine is invoked, after initializing its parameters
 [[expr.call]], a copy is created for each coroutine parameter. For a
 parameter of type cv `T`, the copy is a variable of type cv `T` with
 automatic storage duration that is direct-initialized from an xvalue of
@@ -221,10 +227,11 @@ the coroutine after the lifetime of the entity referred to by that
 parameter has ended is likely to result in undefined
 behavior. — *end note*]
 If the evaluation of the expression `promise.unhandled_exception()`
 exits via an exception, the coroutine is considered suspended at the
-final suspend point.
 The expression `co_await` `promise.final_suspend()` shall not be
 potentially-throwing [[except.spec]].

 — *end example*]
 The *promise type* of a coroutine is
 `std::coroutine_traits<R, P₁, …, Pₙ>::promise_type`, where `R` is the
+return type of the function, and `P₁` … `Pₙ` is the sequence of types of
+the non-object function parameters, preceded by the type of the object
+parameter [[dcl.fct]] if the coroutine is a non-static member function.
+The promise type shall be a class type.
+In the following, `pᵢ` is an lvalue of type `Pᵢ`, where `p₁` denotes the
+object parameter and `p_i+1` denotes the iᵗʰ non-object function
+parameter for a non-static member function, and `pᵢ` denotes the iᵗʰ
+function parameter otherwise. For a non-static member function, `q₁` is
+an lvalue that denotes `*this`; any other `qᵢ` is an lvalue that denotes
+the parameter copy corresponding to `pᵢ`, as described below.
 A coroutine behaves as if its *function-body* were replaced by:
 ``` bnf
 '{'
 ```
 where
 - the *await-expression* containing the call to `initial_suspend` is the
+  *initial await expression*, and
 - the *await-expression* containing the call to `final_suspend` is the
+  *final await expression*, and
 - *initial-await-resume-called* is initially `false` and is set to
   `true` immediately before the evaluation of the *await-resume*
+  expression [[expr.await]] of the initial await expression, and
 - *promise-type* denotes the promise type, and
 - the object denoted by the exposition-only name *`promise`* is the
   *promise object* of the coroutine, and
 - the label denoted by the name *`final-suspend`* is defined for
   exposition only [[stmt.return.coroutine]], and
 - *promise-constructor-arguments* is determined as follows: overload
   resolution is performed on a promise constructor call created by
+  assembling an argument list `q₁` … `qₙ`. If a viable constructor is
+  found [[over.match.viable]], then *promise-constructor-arguments* is
+  `(q₁, …, qₙ)`, otherwise *promise-constructor-arguments* is empty, and
+- a coroutine is suspended at the *initial suspend point* if it is
+  suspended at the initial await expression, and
+- a coroutine is suspended at a *final suspend point* if it is suspended
+  - at a final await expression or
+  - due to an exception exiting from `unhandled_exception()`.
+If searches for the names `return_void` and `return_value` in the scope
+of the promise type each find any declarations, the program is
 ill-formed.
+[*Note 1*: If `return_void` is found, flowing off the end of a
+coroutine is equivalent to a `co_return` with no operand. Otherwise,
+flowing off the end of a coroutine results in undefined behavior
+[[stmt.return.coroutine]]. — *end note*]
 The expression `promise.get_return_object()` is used to initialize the
+returned reference or prvalue result object of a call to a coroutine.
+The call to `get_return_object` is sequenced before the call to
 `initial_suspend` and is invoked at most once.
 A suspended coroutine can be resumed to continue execution by invoking a
 resumption member function [[coroutine.handle.resumption]] of a
 coroutine handle [[coroutine.handle]] that refers to the coroutine. The
+evaluation that invoked a resumption member function is called the
 *resumer*. Invoking a resumption member function for a coroutine that is
 not suspended results in undefined behavior.
 An implementation may need to allocate additional storage for a
 coroutine. This storage is known as the *coroutine state* and is
 obtained by calling a non-array allocation function
 [[basic.stc.dynamic.allocation]]. The allocation function’s name is
+looked up by searching for it in the scope of the promise type.
+- If the search finds any declarations, overload resolution is performed
+  on a function call created by assembling an argument list. The first
+  argument is the amount of space requested, and is a prvalue of type
+  `std::size_t`. The lvalues `p₁` … `pₙ` are the successive arguments.
+  If no viable function is found [[over.match.viable]], overload
+  resolution is performed again on a function call created by passing
+  just the amount of space required as a prvalue of type `std::size_t`.
+- If the search finds no declarations, a search is performed in the
+  global scope. Overload resolution is performed on a function call
+  created by passing the amount of space required as a prvalue of type
+  `std::size_t`.
+If a search for the name `get_return_object_on_allocation_failure` in
+the scope of the promise type [[class.member.lookup]] finds any
+declarations, then the result of a call to an allocation function used
+to obtain storage for the coroutine state is assumed to return `nullptr`
+if it fails to obtain storage, and if a global allocation function is
+selected, the `::operator new(size_t, nothrow_t)` form is used. The
+allocation function used in this case shall have a non-throwing
+*noexcept-specifier*. If the allocation function returns `nullptr`, the
+coroutine returns control to the caller of the coroutine and the return
+value is obtained by a call to
 `T::get_return_object_on_allocation_failure()`, where `T` is the promise
 type.
 [*Example 2*:
   struct promise_type {
     int current_value;
     static auto get_return_object_on_allocation_failure() { return generator{nullptr}; }
     auto get_return_object() { return generator{handle::from_promise(*this)}; }
     auto initial_suspend() { return std::suspend_always{}; }
+    auto final_suspend() noexcept { return std::suspend_always{}; }
     void unhandled_exception() { std::terminate(); }
     void return_void() {}
     auto yield_value(int value) {
       current_value = value;
       return std::suspend_always{};
 The coroutine state is destroyed when control flows off the end of the
 coroutine or the `destroy` member function
 [[coroutine.handle.resumption]] of a coroutine handle
 [[coroutine.handle]] that refers to the coroutine is invoked. In the
+latter case, control in the coroutine is considered to be transferred
+out of the function [[stmt.dcl]]. The storage for the coroutine state is
+released by calling a non-array deallocation function
+[[basic.stc.dynamic.deallocation]]. If `destroy` is called for a
+coroutine that is not suspended, the program has undefined behavior.
+The deallocation function’s name is looked up by searching for it in the
+scope of the promise type. If nothing is found, a search is performed in
+the global scope. If both a usual deallocation function with only a
+pointer parameter and a usual deallocation function with both a pointer
+parameter and a size parameter are found, then the selected deallocation
+function shall be the one with two parameters. Otherwise, the selected
+deallocation function shall be the function with one parameter. If no
+usual deallocation function is found, the program is ill-formed. The
+selected deallocation function shall be called with the address of the
+block of storage to be reclaimed as its first argument. If a
+deallocation function with a parameter of type `std::size_t` is used,
+the size of the block is passed as the corresponding argument.
 When a coroutine is invoked, after initializing its parameters
 [[expr.call]], a copy is created for each coroutine parameter. For a
 parameter of type cv `T`, the copy is a variable of type cv `T` with
 automatic storage duration that is direct-initialized from an xvalue of
 parameter has ended is likely to result in undefined
 behavior. — *end note*]
 If the evaluation of the expression `promise.unhandled_exception()`
 exits via an exception, the coroutine is considered suspended at the
+final suspend point and the exception propagates to the caller or
+resumer.
 The expression `co_await` `promise.final_suspend()` shall not be
 potentially-throwing [[except.spec]].

Diff to HTML by rtfpessoa