11 KiB
[task.promise]
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 is truetemplatevoid return_value(V&& value); // present only if is_void_v is falsetemplateunspecified yield_value(with_error error); templateauto await_transform(A&& a); templateauto await_transform(change_coroutine_scheduler 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 result; // exposition only; present only if is_void_v is falseerror-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::start for some receiver Rcvr.
error-variant is a variant<monostate, remove_cvref_t...>, with duplicate types removed, where E... are the parameter types of the template arguments of the specialization ofexecution::completion_signatures denoted byerror_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 iscoroutine_handle<promise_type>::from_promise(*this).
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).
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 ande is the value held by errors, otherwise
set_value(std::move(RCVR(*this))) if is_void is true, and otherwise
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 theset_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 withSTATE(*this) by invoking set_error(std::move(RCVR(*this)),Cerr(std::move(err.error))).
template<[sender](exec.snd.concepts#concept:sender "33.9.3 Sender concepts [exec.snd.concepts]") Sender> auto await_transform(Sender&& sndr) noexcept;
Returns: If same_as<inline_scheduler, scheduler_type> is true returns as_awaitable(std::forward(sndr), *this); otherwise returnsas_awaitable(affine_on(std::forward(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:
-
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...) returnsSTATE(*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 letalloc 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, 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::pointer is a pointer type.
Effects: Initializes an allocator palloc of type PAlloc withalloc.
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.