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

Files changed (1) hide show

tmp/tmp2fcc77ju/{from.md → to.md} +215 -0

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

	@@ -0,0 +1,215 @@

+#### 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