[exec.as.awaitable] - C++23 → Trunk

Files changed (1) hide show

tmp/tmpmxqeaw7w/{from.md → to.md} +154 -0

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

	@@ -0,0 +1,154 @@

+### `execution::as_awaitable` <a id="exec.as.awaitable">[[exec.as.awaitable]]</a>
+`as_awaitable` transforms an object into one that is awaitable within a
+particular coroutine. Subclause [[exec.coro.util]] makes use of the
+following exposition-only entities:
+``` cpp
+namespace std::execution {
+  template<class Sndr, class Promise>
+    concept awaitable-sender =
+      single-sender<Sndr, env_of_t<Promise>> &&
+      sender_to<Sndr, awaitable-receiver> &&    // see below
+      requires (Promise& p) {
+        { p.unhandled_stopped() } -> convertible_to<coroutine_handle<>>;
+      };
+  template<class Sndr>
+    concept has-queryable-await-completion-adaptor =            // exposition only
+      sender<Sndr> &&
+      requires(Sndr&& sender) {
+        get_await_completion_adaptor(get_env(sender));
+      };
+  template<class Sndr, class Promise>
+    class sender-awaitable;                                     // exposition only
+}
+```
+The type `sender-awaitable<Sndr, Promise>` is equivalent to:
+``` cpp
+namespace std::execution {
+  template<class Sndr, class Promise>
+  class sender-awaitable {
+    struct unit {};                                             // exposition only
+    using value-type =                                          // exposition only
+      single-sender-value-type<Sndr, env_of_t<Promise>>;
+    using result-type =                                         // exposition only
+      conditional_t<is_void_v<value-type>, unit, value-type>;
+    struct awaitable-receiver;                                  // exposition only
+    variant<monostate, result-type, exception_ptr> result{};    // exposition only
+    connect_result_t<Sndr, awaitable-receiver> state;           // exposition only
+  public:
+    sender-awaitable(Sndr&& sndr, Promise& p);
+    static constexpr bool await_ready() noexcept { return false; }
+    void await_suspend(coroutine_handle<Promise>) noexcept { start(state); }
+    value-type await_resume();
+  };
+}
+```
+*`awaitable-receiver`* is equivalent to:
+``` cpp
+struct awaitable-receiver {
+  using receiver_concept = receiver_t;
+  variant<monostate, result-type, exception_ptr>* result-ptr;   // exposition only
+  coroutine_handle<Promise> continuation;                       // exposition only
+  // see below
+};
+```
+Let `rcvr` be an rvalue expression of type *`awaitable-receiver`*, let
+`crcvr` be a const lvalue that refers to `rcvr`, let `vs` be a pack of
+subexpressions, and let `err` be an expression of type `Err`. Then:
+- If `constructible_from<result-type, decltype((vs))...>` is satisfied,
+  the expression `set_value( rcvr, vs...)` is equivalent to:
+  ``` cpp
+  try {
+    rcvr.result-ptr->template emplace<1>(vs...);
+  } catch(...) {
+    rcvr.result-ptr->template emplace<2>(current_exception());
+  }
+  rcvr.continuation.resume();
+  ```
+  Otherwise, `set_value(rcvr, vs...)` is ill-formed.
+- The expression `set_error(rcvr, err)` is equivalent to:
+  ``` cpp
+  rcvr.result-ptr->template emplace<2>(AS-EXCEPT-PTR(err));    // see [exec.general]
+  rcvr.continuation.resume();
+  ```
+- The expression `set_stopped(rcvr)` is equivalent to:
+  ``` cpp
+  static_cast<coroutine_handle<>>(rcvr.continuation.promise().unhandled_stopped()).resume();
+  ```
+- For any expression `tag` whose type satisfies `forwarding-query` and
+  for any pack of subexpressions `as`,
+  `get_env(crcvr).query(tag, as...)` is expression-equivalent to:
+  ``` cpp
+  tag(get_env(as_const(crcvr.continuation.promise())), as...)
+  ```
+``` cpp
+sender-awaitable(Sndr&& sndr, Promise& p);
+```
+*Effects:* Initializes *state* with
+``` cpp
+connect(std::forward<Sndr>(sndr),
+        awaitable-receiver{addressof(result), coroutine_handle<Promise>::from_promise(p)})
+```
+``` cpp
+value-type await_resume();
+```
+*Effects:* Equivalent to:
+``` cpp
+if (result.index() == 2)
+  rethrow_exception(get<2>(result));
+if constexpr (!is_void_v<value-type>)
+  return std::forward<value-type>(get<1>(result));
+```
+`as_awaitable` is a customization point object. For subexpressions
+`expr` and `p` where `p` is an lvalue, `Expr` names the type
+`decltype((expr))` and `Promise` names the type
+`decay_t<decltype((p))>`, `as_awaitable(expr, p)` is
+expression-equivalent to, except that the evaluations of `expr` and `p`
+are indeterminately sequenced:
+- `expr.as_awaitable(p)` if that expression is well-formed. *Mandates:*
+  `is-awaitable<A, Promise>` is `true`, where `A` is the type of the
+  expression above.
+- Otherwise, `(void(p), expr)` if `is-awaitable<Expr, U>` is `true`,
+  where `U` is an unspecified class type that is not `Promise` and that
+  lacks a member named `await_transform`. *Preconditions:*
+  `is-awaitable<Expr, Promise>` is `true` and the expression
+  `co_await expr` in a coroutine with promise type `U` is
+  expression-equivalent to the same expression in a coroutine with
+  promise type `Promise`.
+- Otherwise, `sender-awaitable{adapted-expr, p}` if
+  ``` cpp
+  has-queryable-await-completion-adaptor<Expr>
+  ```
+  and
+  ``` cpp
+  awaitable-sender<decltype((adapted-expr)), Promise>
+  ```
+  are both satisfied, where *`adapted-expr`* is
+  `get_await_completion_adaptor(get_env(expr))(expr)`, except that
+  `expr` is evaluated only once.
+- Otherwise, `sender-awaitable{expr, p}` if
+  `awaitable-sender<Expr, Promise>` is `true`.
+- Otherwise, `(void(p), expr)`.

Diff to HTML by rtfpessoa