33 Execution control library [exec]

33.13 Coroutine utilities [exec.coro.util]

33.13.6 execution::task [exec.task]

33.13.6.1 task overview [task.overview]

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.

33.13.6.2 Class template task [task.class]

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:

(2.1)
allocator_type is Environment::allocator_type if that qualified-id is valid and denotes a type, allocator<byte> otherwise.
(2.2)
scheduler_type is Environment::scheduler_type if that qualified-id is valid and denotes a type, task_scheduler otherwise.
(2.3)
stop_source_type is Environment::stop_source_type if that qualified-id is valid and denotes a type, inplace_stop_source otherwise.
(2.4)
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 completion_signatures<ErrorSigs...> or ErrorSigs contains 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):

(4.1)
set_value_t() if T is void, and set_value_t(T) otherwise;
(4.2)
template arguments of the specialization of execution::completion_signatures denoted by error_types; and
(4.3)
set_stopped_t().

allocator_type shall meet the Cpp17Allocator requirements.

33.13.6.3 task members [task.members]

🔗

task(task&& other) noexcept;

Effects: Initializes handle with exchange(other.handle, {}).

🔗

~task();

Effects: Equivalent to: if (handle) handle.destroy();

🔗

template<receiver R>
  state<R> connect(R&& recv);

Preconditions: bool(handle) is true.

Effects: Equivalent to: return state<R>(exchange(handle, {}), std::forward<R>(recv));

33.13.6.4 Class template task::state [task.state]

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 below; // 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.

🔗

template<class R>
  state(coroutine_handle<promise_type> h, R&& rr);

Effects: Initializes

(2.1)
handle with std::move(h);
(2.2)
rcvr with std::forward<R>(rr);
(2.3)
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.

🔗

~state();

Effects: Equivalent to: if (handle) handle.destroy();

🔗

void start() & noexcept;

Effects: Let prom be the object handle.promise().

Associates STATE(prom), RCVR(prom), and SCHED(prom) with *this as follows:

(4.1)
STATE(prom) is *this.
(4.2)
RCVR(prom) is rcvr.
(4.3)
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

(4.4)
prom.token.stop_requested() returns st.stop_requested();
(4.5)
prom.token.stop_possible() returns st.stop_possible(); and
(4.6)
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().

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 }; }

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 template arguments of the specialization of execution::completion_signatures denoted by error_types.

🔗

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().

🔗

task get_return_object() noexcept;

Returns: A task object whose member handle is coroutine_handle<promise_type>::from_promise(*this).

🔗

auto initial_suspend() noexcept;

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;

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);

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))).

🔗

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).

🔗

template<class Sch>
  auto await_transform(change_coroutine_scheduler<Sch> sch) noexcept;

Effects: Equivalent to: return await_transform(just(exchange(SCHED(*this), scheduler_type(sch.scheduler))), *this);

🔗

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.

🔗

coroutine_handle<> unhandled_stopped();

Effects: Completes the asynchronous operation associated with STATE(*this) by invoking set_stopped(std::move(RCVR(*this))).

Returns: noop_coroutine().

🔗

unspecified get_env() const noexcept;

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);

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__.

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.

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.

🔗

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.