[exec.task] - C++23 → Trunk

Files changed (1) hide show

tmp/tmpnqqwociq/{from.md → to.md} +418 -0

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

	@@ -0,0 +1,418 @@

+### `execution::task` <a id="exec.task">[[exec.task]]</a>
+#### `task` overview <a id="task.overview">[[task.overview]]</a>
+The `task` class template represents a sender that can be used as the
+return type of coroutines. The first template parameter `T` defines the
+type of the value completion datum [[exec.async.ops]] if `T` is not
+`void`. Otherwise, there are no value completion datums. Inside
+coroutines returning `task<T, E>` the operand of `co_return` (if any)
+becomes the argument of `set_value`. The second template parameter
+`Environment` is used to customize the behavior of `task`.
+#### Class template `task` <a id="task.class">[[task.class]]</a>
+``` cpp
+namespace std::execution {
+  template<class T, class Environment>
+  class task {
+    // [task.state]
+    template<receiver Rcvr>
+      class state;                              // exposition only
+  public:
+    using sender_concept = sender_t;
+    using completion_signatures = see below;
+    using allocator_type = see below;
+    using scheduler_type = see below;
+    using stop_source_type = see below;
+    using stop_token_type = decltype(declval<stop_source_type>().get_token());
+    using error_types = see below;
+    // [task.promise]
+    class promise_type;
+    task(task&&) noexcept;
+    ~task();
+    template<receiver Rcvr>
+      state<Rcvr> connect(Rcvr&& rcvr);
+  private:
+    coroutine_handle<promise_type> handle;      // exposition only
+  };
+}
+```
+`task<T, E>` models `sender` [[exec.snd]] if `T` is `void`, a reference
+type, or a cv-unqualified non-array object type and `E` is a class type.
+Otherwise a program that instantiates the definition of `task<T, E>` is
+ill-formed.
+The nested types of `task` template specializations are determined based
+on the `Environment` parameter:
+- `allocator_type` is `Environment::allocator_type` if that
+  *qualified-id* is valid and denotes a type, `allocator<byte>`
+  otherwise.
+- `scheduler_type` is `Environment::scheduler_type` if that
+  *qualified-id* is valid and denotes a type, `task_scheduler`
+  otherwise.
+- `stop_source_type` is `Environment::stop_source_type` if that
+  *qualified-id* is valid and denotes a type, `inplace_stop_source`
+  otherwise.
+- `error_types` is `Environment::error_types` if that *qualified-id* is
+  valid and denotes a type,
+  `completion_signatures<set_error_t(exception_ptr)>` otherwise.
+A program is ill-formed if `error_types` is not a specialization of
+`execution::completion_signatures` or if the template arguments of that
+specialization contain an element which is not of the form
+`set_error_t(E)` for some type `E`.
+The type alias `completion_signatures` is a specialization of
+`execution::completion_signatures` with the template arguments (in
+unspecified order):
+- `set_value_t()` if `T` is `void`, and `set_value_t(T)` otherwise;
+- template arguments of the specialization of
+  `execution::completion_signatures` denoted by `error_types`; and
+- `set_stopped_t()`.
+`allocator_type` shall meet the *Cpp17Allocator* requirements.
+#### `task` members <a id="task.members">[[task.members]]</a>
+``` cpp
+task(task&& other) noexcept;
+```
+*Effects:* Initializes *handle* with `exchange(other.`*`handle`*`, {})`.
+``` cpp
+~task();
+```
+*Effects:* Equivalent to:
+``` cpp
+if (handle)
+  handle.destroy();
+```
+``` cpp
+template<receiver Rcvr>
+  state<Rcvr> connect(Rcvr&& recv);
+```
+*Preconditions:* `bool(`*`handle`*`)` is `true`.
+*Effects:* Equivalent to:
+``` cpp
+return state<Rcvr>(exchange(handle, {}), std::forward<Rcvr>(recv));
+```
+#### Class template `task::state` <a id="task.state">[[task.state]]</a>
+``` cpp
+namespace std::execution {
+  template<class T, class Environment>
+  template<receiver Rcvr>
+  class task<T, Environment>::state {           // exposition only
+  public:
+    using operation_state_concept = operation_state_t;
+    template<class R>
+      state(coroutine_handle<promise_type> h, R&& rr);
+    ~state();
+    void start() & noexcept;
+  private:
+    using own-env-t = see belownc;                // exposition only
+    coroutine_handle<promise_type> handle;      // exposition only
+    remove_cvref_t<Rcvr>           rcvr;        // exposition only
+    own-env-t                      own-env;     // exposition only
+    Environment                    environment; // exposition only
+  };
+}
+```
+The type *`own-env-t`* is `Environment::template
+env_type<decltype(get_env({}declval{}<Rcvr>({}))){}>` if that
+*qualified-id* is valid and denotes a type, `env<>` otherwise.
+``` cpp
+template<class R>
+  state(coroutine_handle<promise_type> h, R&& rr);
+```
+*Effects:* Initializes
+- *handle* with `std::move(h)`;
+- *rcvr* with `std::forward<R>(rr)`;
+- *own-env* with *`own-env-t`*`(get_env(`*`rcvr`*`))` if that expression
+  is valid and *`own-env-t`*`()` otherwise. If neither of these
+  expressions is valid, the program is ill-formed.
+- *environment* with `Environment(`*`own-env`*`)` if that expression is
+  valid, otherwise `Environment(get_env(`*`rcvr`*`))` if this expression
+  is valid, otherwise `Environment()`. If neither of these expressions
+  is valid, the program is ill-formed.
+``` cpp
+~state();
+```
+*Effects:* Equivalent to:
+``` cpp
+if (handle)
+  handle.destroy();
+```
+``` cpp
+void start() & noexcept;
+```
+*Effects:* Let *`prom`* be the object *`handle`*`.promise()`. Associates
+*`STATE`*`(`*`prom`*`)`, *`RCVR`*`(`*`prom`*`)`, and
+*`SCHED`*`(`*`prom`*`)` with `*this` as follows:
+- *`STATE`*`(`*`prom`*`)` is `*this`.
+- *`RCVR`*`(`*`prom`*`)` is *rcvr*.
+- *`SCHED`*`(`*`prom`*`)` is the object initialized with
+  `scheduler_type(get_scheduler(get_env(`*`rcvr`*`)))` if that
+  expression is valid and `scheduler_type()` otherwise. If neither of
+  these expressions is valid, the program is ill-formed.
+Let *`st`* be `get_stop_token(get_env(`*`rcvr`*`))`. Initializes
+*`prom`*`.`*`token`* and *`prom`*`.`*`source`* such that
+- *`prom`*`.`*`token`*`.stop_requested()` returns
+  *`st`*`.stop_requested()`;
+- *`prom`*`.`*`token`*`.stop_possible()` returns
+  *`st`*`.stop_possible()`; and
+- for types `Fn` and `Init` such that both `invocable<Fn>` and
+  `constructible_from<Fn, Init>` are modeled,
+  `stop_token_type::callback_type<Fn>` models
+  `stoppable-callback-for<Fn, stop_token_type, Init>`.
+After that invokes *`handle`*`.resume()`.
+#### Class `task::promise_type` <a id="task.promise">[[task.promise]]</a>
+``` cpp
+namespace std::execution {
+  template<class T, class Environment>
+  class task<T, Environment>::promise_type {
+  public:
+    template<class... Args>
+      promise_type(const Args&... args);
+    task get_return_object() noexcept;
+    auto initial_suspend() noexcept;
+    auto final_suspend() noexcept;
+    void uncaught_exception();
+    coroutine_handle<> unhandled_stopped();
+    void return_void();                 // present only if is_void_v<T> is true
+    template<class V>
+      void return_value(V&& value);     // present only if is_void_v<T> is false
+    template<class E>
+      unspecified yield_value(with_error<E> error);
+    template<class A>
+      auto await_transform(A&& a);
+    template<class Sch>
+      auto await_transform(change_coroutine_scheduler<Sch> sch);
+    unspecified get_env() const noexcept;
+    template<class... Args>
+      void* operator new(size_t size, Args&&... args);
+    void operator delete(void* pointer, size_t size) noexcept;
+  private:
+    using error-variant = see belownc;    // exposition only
+    allocator_type    alloc;            // exposition only
+    stop_source_type  source;           // exposition only
+    stop_token_type   token;            // exposition only
+    optional<T>       result;           // exposition only; present only if is_void_v<T> is false
+    error-variant     errors;           // exposition only
+  };
+}
+```
+Let `prom` be an object of `promise_type` and let `tsk` be the `task`
+object created by `prom.get_return_object()`. The description below
+refers to objects `STATE(prom)`, `RCVR(prom)`, and `SCHED(prom)`
+associated with `tsk` during evaluation of `task::state<Rcvr>::start`
+for some receiver `Rcvr`.
+*`error-variant`* is a `variant<monostate,
+remove_cvref_t<E>...>`, with duplicate types removed, where `E...` are
+the parameter types of the template arguments of the specialization of
+`execution::completion_signatures` denoted by `error_types`.
+``` cpp
+template<class... Args>
+  promise_type(const Args&... args);
+```
+*Mandates:* The first parameter of type `allocator_arg_t` (if any) is
+not the last parameter.
+*Effects:* If `Args` contains an element of type `allocator_arg_t` then
+*alloc* is initialized with the corresponding next element of `args`.
+Otherwise, *alloc* is initialized with `allocator_type()`.
+``` cpp
+task get_return_object() noexcept;
+```
+*Returns:* A `task` object whose member *handle* is
+`coroutine_handle<promise_type>::from_promise(*this)`.
+``` cpp
+auto initial_suspend() noexcept;
+```
+*Returns:* An awaitable object of unspecified type [[expr.await]] whose
+member functions arrange for
+- the calling coroutine to be suspended,
+- the coroutine to be resumed on an execution agent of the execution
+  resource associated with *`SCHED`*`(*this)`.
+``` cpp
+auto final_suspend() noexcept;
+```
+*Returns:* An awaitable object of unspecified type [[expr.await]] whose
+member functions arrange for the completion of the asynchronous
+operation associated with *`STATE`*`(*this)` by invoking:
+- `set_error(std::move(`*`RCVR`*`(*this)), std::move(e))` if
+  *`errors`*`.index()` is greater than zero and `e` is the value held by
+  *errors*, otherwise
+- `set_value(std::move(`*`RCVR`*`(*this)))` if `is_void<T>` is `true`,
+  and otherwise
+- `set_value(std::move(`*`RCVR`*`(*this)), *`*`result`*`)`.
+``` cpp
+template<class Err>
+  auto yield_value(with_error<Err> err);
+```
+*Mandates:* `std::move(err.error)` is convertible to exactly one of the
+`set_error_t` argument types of `error_types`. Let *`Cerr`* be that
+type.
+*Returns:* An awaitable object of unspecified type [[expr.await]] whose
+member functions arrange for the calling coroutine to be suspended and
+then completes the asynchronous operation associated with
+*`STATE`*`(*this)` by invoking
+`set_error(std::move(`*`RCVR`*`(*this)), `*`Cerr`*`(std::move(err.error)))`.
+``` cpp
+template<sender Sender>
+  auto await_transform(Sender&& sndr) noexcept;
+```
+*Returns:* If `same_as<inline_scheduler, scheduler_type>` is `true`
+returns `as_awaitable(std::forward<Sender>(sndr), *this)`; otherwise
+returns
+`as_awaitable(affine_on(std::forward<Sender>(sndr), `*`SCHED`*`(*this)), *this)`.
+``` cpp
+template<class Sch>
+  auto await_transform(change_coroutine_scheduler<Sch> sch) noexcept;
+```
+*Effects:* Equivalent to:
+``` cpp
+return await_transform(just(exchange(SCHED(*this), scheduler_type(sch.scheduler))), *this);
+```
+``` cpp
+void uncaught_exception();
+```
+*Effects:* If the signature `set_error_t(exception_ptr)` is not an
+element of `error_types`, calls `terminate()` [[except.terminate]].
+Otherwise, stores `current_exception()` into *errors*.
+``` cpp
+coroutine_handle<> unhandled_stopped();
+```
+*Effects:* Completes the asynchronous operation associated with
+*`STATE`*`(*this)` by invoking
+`set_stopped(std::move(`*`RCVR`*`(*this)))`.
+*Returns:* `noop_coroutine()`.
+``` cpp
+unspecified get_env() const noexcept;
+```
+*Returns:* An object `env` such that queries are forwarded as follows:
+- `env.query(get_scheduler)` returns
+  `scheduler_type(`*`SCHED`*`(*this))`.
+- `env.query(get_allocator)` returns *alloc*.
+- `env.query(get_stop_token)` returns *token*.
+- For any other query `q` and arguments `a...` a call to
+  `env.query(q, a...)` returns *`STATE`*`(*this)`.
+  `environment.query(q, a...)` if this expression is well-formed and
+  `forwarding_query(q)` is well-formed and is `true`. Otherwise
+  `env.query(q, a...)` is ill-formed.
+``` cpp
+template<class... Args>
+  void* operator new(size_t size, const Args&... args);
+```
+If there is no parameter with type `allocator_arg_t` then let `alloc` be
+`allocator_type()`. Otherwise, let `arg_next` be the parameter following
+the first `allocator_arg_t` parameter, and let `alloc` be
+`allocator_type(arg_next)`. Let `PAlloc` be
+`allocator_traits<allocator_type>::template rebind_alloc<U>`, where `U`
+is an unspecified type whose size and alignment are both
+\_\_STDCPP_DEFAULT_NEW_ALIGNMENT\_\_.
+*Mandates:*
+- The first parameter of type `allocator_arg_t` (if any) is not the last
+  parameter.
+- `allocator_type(arg_next)` is a valid expression if there is a
+  parameter of type `allocator_arg_t`.
+- `allocator_traits<PAlloc>::pointer` is a pointer type.
+*Effects:* Initializes an allocator `palloc` of type `PAlloc` with
+`alloc`. Uses `palloc` to allocate storage for the smallest array of `U`
+sufficient to provide storage for a coroutine state of size `size`, and
+unspecified additional state necessary to ensure that `operator delete`
+can later deallocate this memory block with an allocator equal to
+`palloc`.
+*Returns:* A pointer to the allocated storage.
+``` cpp
+void operator delete(void* pointer, size_t size) noexcept;
+```
+*Preconditions:* `pointer` was returned from an invocation of the above
+overload of `operator new` with a size argument equal to `size`.
+*Effects:* Deallocates the storage pointed to by `pointer` using an
+allocator equal to that used to allocate it.

Diff to HTML by rtfpessoa