[exec.spawn.future]

spawn_future attempts to associate the given input sender with the given token's async scope and, on success, eagerly starts the input sender; the return value is a sender that, when connected and started, completes with either the result of the eagerly-started input sender or with set_stopped if the input sender was not started.

2

#

The name spawn_future denotes a customization point object.

For subexpressions sndr, token, and env,

(2.1)
let Sndr be decltype((sndr)),
(2.2)
let Token be remove_cvref_t<decltype((token))>, and
(2.3)
let Env be remove_cvref_t<decltype((env))>.

If any of sender<Sndr>, scope_token<Token>, or queryable<Env> are not satisfied, the expression spawn_future(sndr, token, env) is ill-formed.

3

#

Let try-cancelable be the exposition-only class:

🔗

namespace std::execution { struct try-cancelable { // exposition only virtual void try-cancel() noexcept = 0; // exposition only }; }

4

#

Let spawn-future-state-base be the exposition-only class template:

🔗

namespace std::execution { template<class Completions> struct spawn-future-state-base; // exposition only template<class... Sigs> struct spawn-future-state-base<completion_signatures<Sigs...>> // exposition only : try-cancelable { using variant-t = see below; // exposition only variant-t result; // exposition only virtual void complete() noexcept = 0; // exposition only }; }

5

#

Let Sigs be the pack of arguments to the completion_signatures specialization provided as a parameter to the spawn-future-state-base class template.

Let as-tuple be an alias template that transforms a completion signature Tag(Args...) into the tuple specialization decayed-tuple<Tag, Args...>.

(5.1)
If is_nothrow_constructible_v<decay_t<Arg>, Arg> is true for every type Arg in every parameter pack Args in every completion signature Tag(Args...) in Sigs then variant-t denotes the type variant<monostate, tuple<set_stopped_t>, as-tuple<Sigs>...>, except with duplicate types removed.
(5.2)
Otherwise variant-t denotes the type variant<monostate, tuple<set_stopped_t>, tuple<set_error_t, exception_ptr>, as-tuple<Sigs>...>, except with duplicate types removed.

6

#

Let spawn-future-receiver be the exposition-only class template:

🔗

namespace std::execution { template<class Completions> struct spawn-future-receiver { // exposition only using receiver_concept = receiver_tag; spawn-future-state-base<Completions>* state; // exposition only template<class... T> void set_value(T&&... t) && noexcept { set-complete<set_value_t>(std::forward<T>(t)...); } template<class E> void set_error(E&& e) && noexcept { set-complete<set_error_t>(std::forward<E>(e)); } void set_stopped() && noexcept { set-complete<set_stopped_t>(); } private: template<class CPO, class... T> void set-complete(T&&... t) noexcept { // exposition only constexpr bool nothrow = (is_nothrow_constructible_v<decay_t<T>, T> && ...); try { state->result.template emplace<decayed-tuple<CPO, T...>>(CPO{}, std::forward<T>(t)...); } catch (...) { if constexpr (!nothrow) { using tuple_t = decayed-tuple<set_error_t, exception_ptr>; state->result.template emplace<tuple_t>(set_error_t{}, current_exception()); } } state->complete(); } }; }

7

#

Let ssource-t be an unspecified type that models stoppable-source and default_initializable, such that a default-initialized object of type ssource-t has an associated stop state.

Let ssource be an lvalue of type ssource-t.

Let stoken-t be decltype(ssource.get_token()).

Let future-spawned-sender be the alias template:

template<sender Sender, class Env> using future-spawned-sender = // exposition only decltype(write_env(stop-when(declval<Sender>(), declval<stoken-t>()), declval<Env>()));

8

#

Let spawn-future-state be the exposition-only class template:

🔗

namespace std::execution { template<class Alloc, scope_token Token, sender Sender, class Env> struct spawn-future-state // exposition only : spawn-future-state-base<completion_signatures_of_t<future-spawned-sender<Sender, Env>>> { using sigs-t = // exposition only completion_signatures_of_t<future-spawned-sender<Sender, Env>>; using receiver-t = // exposition only spawn-future-receiver<sigs-t>; using op-t = // exposition only connect_result_t<future-spawned-sender<Sender, Env>, receiver-t>; spawn-future-state(Alloc alloc, Sender&& sndr, Token token, Env env) // exposition only : alloc(std::move(alloc)), op(connect( write_env(stop-when(std::forward<Sender>(sndr), ssource.get_token()), std::move(env)), receiver-t(this))), assoc(token.try_associate()) { if (assoc) start(op); else set_stopped(receiver-t(this)); } void complete() noexcept override; // exposition only void consume(receiver auto& rcvr) noexcept; // exposition only void abandon() noexcept; // exposition only void try-cancel() noexcept override { // exposition only ssource.request_stop(); try-set-stopped(); } void try-set-stopped() noexcept; // exposition only private: using assoc-t = // exposition only remove_cvref_t<decltype(declval<Token&>().try_associate())>; Alloc alloc; // exposition only ssource-t ssource; // exposition only op-t op; // exposition only assoc-t assoc; // exposition only void destroy() noexcept; // exposition only }; template<class Alloc, scope_token Token, sender Sender, class Env> // exposition only spawn-future-state(Alloc alloc, Sender&& sndr, Token token, Env env) -> spawn-future-state<Alloc, Token, Sender, Env>; }

9

#

For purposes of determining the existence of a data race, complete, consume, try-set-stopped, and abandon behave as atomic operations ([intro.multithread]).

These operations on a single object of a type that is a specialization of spawn-future-state appear to occur in a single total order.

10

#

Effects:

(10.1)
No effects if this invocation of complete happens before an invocation of consume, try-set-
stopped, or abandon on *this;
(10.2)
otherwise, if an invocation of consume on *this happens before this invocation of complete and no invocation of try-set-stopped on *this happened before this invocation of complete then there is a receiver, rcvr, registered and that receiver is deregistered and completed as if by consume(rcvr);
(10.3)
otherwise, destroy is invoked.

11

#

Effects:

(11.1)
If this invocation of consume happens before an invocation of complete on *this and no invocation of try-set-stopped on *this happened before this invocation of consume then rcvr is registered to be completed when complete is subsequently invoked on *this;
(11.2)
otherwise, if this invocation of consume happens after an invocation of try-set-stopped on *this and no invocation of complete on *this happened before this invocation of consume then rcvr is completed as if by set_stopped(std::move(rcvr));
(11.3)
otherwise, rcvr is completed as if by: std::move(this->result).visit( [&rcvr](auto&& tuple) noexcept { if constexpr (!same_as<remove_reference_t<decltype(tuple)>, monostate>) { apply([&rcvr](auto cpo, auto&&... vals) { cpo(std::move(rcvr), std::move(vals)...); }, std::move(tuple)); } }); destroy();

12

#

Effects:

(12.1)
If an invocation of consume on *this happens before this invocation of try-set-stopped and no invocation of complete on *this happened before this invocation of try-set-stopped then there is a receiver, rcvr, registered and that receiver is deregistered and completed as if by set_stopped(std::move(rcvr)), destroy();
(12.2)
otherwise, no effects.

13

#

Effects:

(13.1)
If this invocation of abandon happens before an invocation of complete on *this then equivalent to: ssource.request_stop();
(13.2)
otherwise, destroy is invoked.

14

#

Effects: Equivalent to: auto associated = std::move(this->associated); { using traits = allocator_traits<Alloc>::template rebind_traits<spawn-future-state>; typename traits::allocator_type alloc(std::move(this->alloc)); traits::destroy(alloc, this); traits::deallocate(alloc, this, 1); }

15

#

Let future-operation be the exposition-only class template:

namespace std::execution { template<class StatePtr, class Rcvr> struct future-operation { // exposition only struct callback { // exposition only try-cancelable* state; // exposition only void operator()() noexcept { state->try-cancel(); }; }; using stop-token-t = // exposition only stop_token_of_t<env_of_t<Rcvr>>; using stop-callback-t = // exposition only stop_callback_for_t<stop-token-t, callback>; struct rcvr-t { // exposition only using receiver_concept = receiver_tag; future-operation* op; // exposition only template<class... T> void set_value(T&&... ts) && noexcept { op->set-complete<set_value_t>(std::forward<T>(ts)...); } template<class E> void set_error(E&& e) && noexcept { op->set-complete<set_error_t>(std::forward<E>(e)); } void set_stopped() && noexcept { op->set-complete<set_stopped_t>(); } env_of_t<Rcvr> get_env() const noexcept { return execution::get_env(op->rcvr); } }; Rcvr rcvr; // exposition only StatePtr state; // exposition only rcvr-t inner; // exposition only optional<stop-callback-t> stopCallback; // exposition only future-operation(StatePtr state, Rcvr rcvr) noexcept // exposition only : rcvr(std::move(rcvr)), state(std::move(state)), inner(this) {} future-operation(future-operation&&) = delete; void run() & noexcept { // exposition only constexpr bool nothrow = is_nothrow_constructible_v<stop-callback-t, stop-token-t, callback>; try { stopCallback.emplace(get_stop_token(rcvr), callback(state.get())); } catch (...) { if constexpr (!nothrow) { set_error(std::move(rcvr), current_exception()); return; } } state.release()->consume(inner); } template<class CPO, class... T> void set-complete(T&&... ts) noexcept { // exposition only stopCallback.reset(); CPO{}(std::move(rcvr), std::forward<T>(ts)...); } }; }

16

#

The exposition-only class template impls-for ([exec.snd.expos]) is specialized for spawn_future_t as follows:

🔗

namespace std::execution { template<> struct impls-for<spawn_future_t> : default-impls { static constexpr auto start = see below; // exposition only static constexpr auto get-state = see below; // exposition only }; }

17

#

The member impls-for<spawn_future_t>::start is initialized with a callable object equivalent to the following lambda: [](auto& state, auto&) noexcept -> void { state.run(); }

18

#

The member impls-for<spawn_future_t>::get-state is initialized with a callable object equivalent to the following lambda: []<class Sndr, class Rcvr>(Sndr sndr, Rcvr& rcvr) noexcept { auto& [_, data] = sndr; using state_ptr = remove_cvref_t<decltype(data)>; return future-operation<state_ptr, Rcvr>(std::move(data), std::move(rcvr)); }

19

#

For the expression spawn_future(sndr, token, env) let new_sender be the expression token.wrap(sndr) and let alloc and senv be defined as follows:

(19.1)
if the expression get_allocator(env) is well-formed, then alloc is the result of get_allocator(env) and senv is the expression env;
(19.2)
otherwise, if the expression get_allocator(get_env(new_sender)) is well-formed, then alloc is the result of get_allocator(get_env(new_sender)) and senv is the expression JOIN-ENV(prop(get_allocator, alloc), env);
(19.3)
otherwise, alloc is allocator<void>() and senv is the expression env.

20

#

The expression spawn_future(sndr, token, env) has the following effects:

(20.1)
Uses alloc to allocate and construct an object s of type decltype(spawn-future-state(alloc, token.wrap(sndr), token, senv)) from alloc, token.wrap(sndr), token, and senv.

If an exception is thrown then any constructed objects are destroyed and any allocated memory is deallocated.
(20.2)
Constructs an object u of a type that is a specialization of unique_ptr such that:
- (20.2.1)
  u.get() is equal to the address of s, and
- (20.2.2)
  u.get_deleter()(u.release()) is equivalent to u.release()->abandon().
(20.3)
Returns make-sender(spawn_future, std::move(u)).

21

#

The expression spawn_future(sndr, token) is expression-equivalent to spawn_future(sndr, token, execution::env<>()).

33 Execution control library [exec]

33.9 Senders [exec.snd]

33.9.12 Sender adaptors [exec.adapt]

33.9.12.18 execution::spawn_future [exec.spawn.future]

33 Execution control library [exec]

33.9 Senders [exec.snd]

33.9.12 Sender adaptors [exec.adapt]

33.9.12.18 execution​::​spawn_future [exec.spawn.future]

33.9.12.18 execution::spawn_future [exec.spawn.future]