33 Execution control library [exec]

33.13 Coroutine utilities [exec.coro.util]

33.13.6 execution​::​task [exec.task]

33.13.6.5 Class task​::​promise_type [task.promise]

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 below; // 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 }; }
1
#
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.
2
#
error-variant is a variant<monostate, remove_cvref_t<E>...>, with duplicate types removed, where E... are template arguments of the specialization of execution​::​completion_signatures denoted by error_types.
🔗
template<class... Args> promise_type(const Args&... args);
3
#
Mandates: The first parameter of type allocator_arg_t (if any) is not the last parameter.
4
#
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().
🔗
task get_return_object() noexcept;
5
#
Returns: A task object whose member handle is coroutine_handle<promise_type>​::​​from_promise​(*this).
🔗
auto initial_suspend() noexcept;
6
#
Returns: An awaitable object of unspecified type ([expr.await]) whose member functions arrange for
  • (6.1)
    the calling coroutine to be suspended,
  • (6.2)
    the coroutine to be resumed on an execution agent of the execution resource associated with SCHED(*this).
🔗
auto final_suspend() noexcept;
7
#
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:
  • (7.1)
    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
  • (7.2)
    set_value(std​::​move(RCVR(*this))) if is_void<T> is true, and otherwise
  • (7.3)
    set_value(std​::​move(RCVR(*this)), *result).
🔗
template<class Err> auto yield_value(with_error<Err> err);
8
#
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.
9
#
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))).
🔗
template<sender Sender> auto await_transform(Sender&& sndr) noexcept;
10
#
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).
🔗
template<class Sch> auto await_transform(change_coroutine_scheduler<Sch> sch) noexcept;
11
#
Effects: Equivalent to: return await_transform(just(exchange(SCHED(*this), scheduler_type(sch.scheduler))), *this);
🔗
void uncaught_exception();
12
#
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.
🔗
coroutine_handle<> unhandled_stopped();
13
#
Effects: Completes the asynchronous operation associated with STATE(*this) by invoking set_stopped(std​::​move(RCVR(*this))).
14
#
Returns: noop_coroutine().
🔗
unspecified get_env() const noexcept;
15
#
Returns: An object env such that queries are forwarded as follows:
  • (15.1)
    env.query(get_scheduler) returns scheduler_type(SCHED(*this)).
  • (15.2)
    env.query(get_allocator) returns alloc.
  • (15.3)
    env.query(get_stop_token) returns token.
  • (15.4)
    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.
🔗
template<class... Args> void* operator new(size_t size, const Args&... args);
16
#
If there is no parameter with type allocator_arg_t then let alloc be Allocator().
Let arg_next be the parameter following the first allocator_arg_t parameter (if any) and let alloc be Allocator(arg_next).
Then PAlloc is allocator_traits<Allocator>​::​template rebind_alloc​<U> where U is an unspecified type whose size and alignment are both __STDCPP_DEFAULT_NEW_ALIGNMENT__.
17
#
Mandates:
  • (17.1)
    The first parameter of type allocator_arg_t (if any) is not the last parameter.
  • (17.2)
    Allocator(arg_next) is a valid expression if there is a parameter of type allocator_arg_t.
  • (17.3)
    allocator_traits<PAlloc>​::​pointer is a pointer type.
18
#
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.
19
#
Returns: A pointer to the allocated storage.
🔗
void operator delete(void* pointer, size_t size) noexcept;
20
#
Preconditions: pointer was returned from an invocation of the above overload of operator new with a size argument equal to size.
21
#
Effects: Deallocates the storage pointed to by pointer using an allocator equal to that used to allocate it.