34 Execution control library [exec]

34.9 Senders [exec.snd]

34.9.13 Sender consumers [exec.consumers]

34.9.13.1 this_thread​::​sync_wait [exec.sync.wait]

1
#
this_thread​::​sync_wait and this_thread​::​sync_wait_with_variant are used to block the current thread of execution until the specified sender completes and to return its async result.
sync_wait mandates that the input sender has exactly one value completion signature.
2
#
Let sync-wait-env be the following exposition-only class type: namespace std::this_thread { struct sync-wait-env { execution::run_loop* loop; // exposition only auto query(execution::get_scheduler_t) const noexcept { return loop->get_scheduler(); } auto query(execution::get_delegation_scheduler_t) const noexcept { return loop->get_scheduler(); } }; }
3
#
Let sync-wait-result-type and sync-wait-with-variant-result-type be exposition-only alias templates defined as follows: namespace std::this_thread { template<execution::sender_in<sync-wait-env> Sndr> using sync-wait-result-type = optional<execution::value_types_of_t<Sndr, sync-wait-env, decayed-tuple, type_identity_t>>; template<execution::sender_in<sync-wait-env> Sndr> using sync-wait-with-variant-result-type = optional<execution::value_types_of_t<Sndr, sync-wait-env>>; }
4
#
The name this_thread​::​sync_wait denotes a customization point object.
For a subexpression sndr, let Sndr be decltype((sndr)).
If sender_in<Sndr, sync-wait-env> is false, the expression this_thread​::​sync_wait(sndr) is ill-formed.
Otherwise, it is expression-equivalent to the following, except that sndr is evaluated only once: apply_sender(get-domain-early(sndr), sync_wait, sndr) Mandates:
  • (4.1)
    The type sync-wait-result-type<Sndr> is well-formed.
  • (4.2)
    same_as<decltype(e), sync-wait-result-type<Sndr>> is true, where e is the apply_sender expression above.
5
#
Let sync-wait-state and sync-wait-receiver be the following exposition-only class templates: namespace std::this_thread { template<class Sndr> struct sync-wait-state { // exposition only execution::run_loop loop; // exposition only exception_ptr error; // exposition only sync-wait-result-type<Sndr> result; // exposition only }; template<class Sndr> struct sync-wait-receiver { // exposition only using receiver_concept = execution::receiver_t; sync-wait-state<Sndr>* state; // exposition only template<class... Args> void set_value(Args&&... args) && noexcept; template<class Error> void set_error(Error&& err) && noexcept; void set_stopped() && noexcept; sync-wait-env get_env() const noexcept { return {&state->loop}; } }; }
🔗
template<class... Args> void set_value(Args&&... args) && noexcept;
6
#
Effects: Equivalent to: try { state->result.emplace(std::forward<Args>(args)...); } catch (...) { state->error = current_exception(); } state->loop.finish();
🔗
template<class Error> void set_error(Error&& err) && noexcept;
7
#
Effects: Equivalent to: state->error = AS-EXCEPT-PTR(std::forward<Error>(err)); // see [exec.general] state->loop.finish();
🔗
void set_stopped() && noexcept;
8
#
Effects: Equivalent to state->loop.finish().
9
#
For a subexpression sndr, let Sndr be decltype((sndr)).
If sender_to<Sndr, sync-wait-receiver<
Sndr>> is false, the expression sync_wait.apply_sender(sndr) is ill-formed; otherwise, it is equivalent to: sync-wait-state<Sndr> state; auto op = connect(sndr, sync-wait-receiver<Sndr>{&state}); start(op); state.loop.run(); if (state.error) { rethrow_exception(std::move(state.error)); } return std::move(state.result);
10
#
The behavior of this_thread​::​sync_wait(sndr) is undefined unless:
  • (10.1)
    It blocks the current thread of execution ([defns.block]) with forward progress guarantee delegation ([intro.progress]) until the specified sender completes.
    [Note 1: 
    The default implementation of sync_wait achieves forward progress guarantee delegation by providing a run_loop scheduler via the get_delegation_scheduler query on the sync-wait-receiver's environment.
    The run_loop is driven by the current thread of execution.
    — end note]
  • (10.2)
    It returns the specified sender's async results as follows:
    • (10.2.1)
      For a value completion, the result datums are returned in a tuple in an engaged optional object.
    • (10.2.2)
      For an error completion, an exception is thrown.
    • (10.2.3)
      For a stopped completion, a disengaged optional object is returned.