33 Execution control library [exec]

33.9 Senders [exec.snd]

33.9.12 Sender adaptors [exec.adapt]

33.9.12.6 execution::on [exec.on]

The on sender adaptor has two forms:

(1.1)
on(sch, sndr), which starts a sender sndr on an execution agent belonging to a scheduler sch's associated execution resource and that, upon sndr's completion, transfers execution back to the execution resource on which the on sender was started.
(1.2)
on(sndr, sch, closure), which upon completion of a sender sndr, transfers execution to an execution agent belonging to a scheduler sch's associated execution resource, then executes a sender adaptor closure closure with the async results of the sender, and that then transfers execution back to the execution resource on which sndr completed.

The name on denotes a pipeable sender adaptor object.

For subexpressions sch and sndr, on(sch, sndr) is ill-formed if any of the following is true:

(2.1)
decltype((sch)) does not satisfy scheduler, or
(2.2)
decltype((sndr)) does not satisfy sender and sndr is not a pipeable sender adaptor closure object ([exec.adapt.obj]), or
(2.3)
decltype((sndr)) satisfies sender and sndr is also a pipeable sender adaptor closure object.

Otherwise, if decltype((sndr)) satisfies sender, the expression on(sch, sndr) is expression-equivalent to: transform_sender( query-or-default(get_domain, sch, default_domain()), make-sender(on, sch, sndr)) except that sch is evaluated only once.

For subexpressions sndr, sch, and closure, if

(4.1)
decltype((sch)) does not satisfy scheduler, or
(4.2)
decltype((sndr)) does not satisfy sender, or
(4.3)
closure is not a pipeable sender adaptor closure object ([exec.adapt.obj]),

the expression on(sndr, sch, closure) is ill-formed; otherwise, it is expression-equivalent to: transform_sender( get-domain-early(sndr), make-sender(on, product-type{sch, closure}, sndr)) except that sndr is evaluated only once.

Let out_sndr and env be subexpressions, let OutSndr be decltype((out_sndr)), and let Env be decltype((env)).

If sender-for<OutSndr, on_t> is false, then the expressions on.transform_env(out_sndr, env) and on.transform_sender(out_sndr, env) are ill-formed.

Otherwise: Let not-a-scheduler be an unspecified empty class type, and let not-a-sender be the exposition-only type: struct not-a-sender { using sender_concept = sender_t; auto get_completion_signatures(auto&&) const { return see below; } }; where the member function get_completion_signatures returns an object of a type that is not a specialization of the completion_signatures class template.

The expression on.transform_env(out_sndr, env) has effects equivalent to: auto&& [_, data, _] = out_sndr; if constexpr (scheduler<decltype(data)>) { return JOIN-ENV(SCHED-ENV(std::forward_like<OutSndr>(data)), FWD-ENV(std::forward<Env>(env))); } else { return std::forward<Env>(env); }

The expression on.transform_sender(out_sndr, env) has effects equivalent to: auto&& [_, data, child] = out_sndr; if constexpr (scheduler<decltype(data)>) { auto orig_sch = query-with-default(get_scheduler, env, not-a-scheduler()); if constexpr (same_as<decltype(orig_sch), not-a-scheduler>) { return not-a-sender{}; } else { return continues_on( starts_on(std::forward_like<OutSndr>(data), std::forward_like<OutSndr>(child)), std::move(orig_sch)); } } else { auto& [sch, closure] = data; auto orig_sch = query-with-default( get_completion_scheduler<set_value_t>, get_env(child), query-with-default(get_scheduler, env, not-a-scheduler())); if constexpr (same_as<decltype(orig_sch), not-a-scheduler>) { return not-a-sender{}; } else { return write-env( continues_on( std::forward_like<OutSndr>(closure)( continues_on( write-env(std::forward_like<OutSndr>(child), SCHED-ENV(orig_sch)), sch)), orig_sch), SCHED-ENV(sch)); } }

Recommended practice: Implementations should use the return type of not-a-sender::get_completion_signatures to inform users that their usage of on is incorrect because there is no available scheduler onto which to restore execution.

Let out_sndr be a subexpression denoting a sender returned from on(sch, sndr) or one equal to such, and let OutSndr be the type decltype((out_sndr)).

Let out_rcvr be a subexpression denoting a receiver that has an environment of type Env such that sender_in<OutSndr, Env> is true.

Let op be an lvalue referring to the operation state that results from connecting out_sndr with out_rcvr.

Calling start(op) shall

(10.1)
remember the current scheduler, get_scheduler(get_env(rcvr));
(10.2)
start sndr on an execution agent belonging to sch's associated execution resource;
(10.3)
upon sndr's completion, transfer execution back to the execution resource associated with the scheduler remembered in step 1; and
(10.4)
forward sndr's async result to out_rcvr.

If any scheduling operation fails, an error completion on out_rcvr shall be executed on an unspecified execution agent.

Let out_sndr be a subexpression denoting a sender returned from on(sndr, sch, closure) or one equal to such, and let OutSndr be the type decltype((out_sndr)).