diff --git a/docs/overview.md b/docs/overview.md index f82860537..b5544874d 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -10,16 +10,18 @@ This section defines a few terms used throughout the description on this page. T
completion signal -When an asynchronous operation completes it _signals_ its completion by calling a completion function on a receiver: + +When an asynchronous operation completes it _signals_ its completion by calling a completion function on a receiver: -- std::execution::set_value(_receiver_, _args_...) is called when an operation completes successfully. A call to this completion function is referred to as _value completion signal_. -- std::execution::set_error(_receiver_, _error_) is called when an operation fails to deliver its success results. A call to this completion function is referred to as _error completion signal_. -- std::execution::set_stopped() is called when an operation was cancelled. A call to this completion function is referred to as _cancellation completion signal_. -- Collectively the value, error, and cancellation completion signals are referred to as _completion signal_. Note that any started asynchronous operation triggers exactly one completion signal. +- std::execution::set_value(_receiver_, _args_...) is called when an operation completes successfully. A call to this completion function is referred to as _value completion signal_. +- std::execution::set_error(_receiver_, _error_) is called when an operation fails to deliver its success results. A call to this completion function is referred to as _error completion signal_. +- std::execution::set_stopped() is called when an operation was cancelled. A call to this completion function is referred to as _cancellation completion signal_. +- Collectively the value, error, and cancellation completion signals are referred to as _completion signal_. Note that any started asynchronous operation triggers exactly one completion signal.
environment -The term _enviroment_ refers to the bag of properties associated with an _object_ by the call std::execution::get_env(_object_). By default the environment for objects is empty (std::execution::env<>). In particular, environments associated with receivers are used to provide access to properties like the stop token, scheduler, or allocator associated with the receiver. The various properties associated with an object are accessed via queries. + +The term _enviroment_ refers to the bag of properties associated with an _object_ by the call std::execution::get_env(_object_). By default the environment for objects is empty (std::execution::env<>). In particular, environments associated with receivers are used to provide access to properties like the stop token, scheduler, or allocator associated with the receiver. The various properties associated with an object are accessed via queries.
## Concepts @@ -27,6 +29,7 @@ This section lists the concepts from `std::execution`.
inlinable_receiver<Rcvr, Child> + The concecpt inlinable_receiver<Rcvr, Child> detects if a receiver of type Rcvr can be obtained from a Child pointer using Rcvr::make_receiver_for(child). It is unspecified if any of the standard library receivers is a inlinable_receiver. @@ -34,19 +37,20 @@ pointer using Rcvr::make_receiver_for(child). It is u
operation_state<State> + -Operation states represent asynchronous operations ready to be started or executing. Operation state objects are normally neither movable nor copyable. Once started the object needs to be kept alive until a completion signal is received. Users don’t interact with operation states explicitly except when implementing new sender algorithms. +Operation states represent asynchronous operations ready to be started or executing. Operation state objects are normally neither movable nor copyable. Once started the object needs to be kept alive until a completion signal is received. Users don’t interact with operation states explicitly except when implementing new sender algorithms. Required members for _State_: - The type `operation_state_concept` is an alias for `operation_state_tag` or a type derived thereof. -- state.start() & noexcept +- state.start() & noexcept
Example -This example shows a simple operation state object which immediately completes successfully without any values (as () would do). Normally start() initiates an asynchronous operation completing at some point later. +This example shows a simple operation state object which immediately completes successfully without any values (as () would do). Normally start() initiates an asynchronous operation completing at some point later. ```c++ template @@ -67,11 +71,12 @@ static_assert(std::execution::operation_state>);
receiver<Receiver> + -Receivers are used to receive completion signals: -when an asynchronous operation completes the corresponding completion signal +Receivers are used to receive completion signals: +when an asynchronous operation completes the corresponding completion signal is called with the appropriate arguments. In addition receivers provide access to the -environment for the operation via the get_env method. +environment for the operation via the get_env method. Users don’t interact with receivers explicitly except when implementing new sender algorithms. Required members for _Receiver_: @@ -79,20 +84,20 @@ Required members for _Receiver_: - The type `receiver_concept` is an alias for `receiver_tag` or a type derived thereof`. - Rvalues of type _Receiver_ are movable. - Lvalues of type _Receiver_ are copyable. -- std::execution::get_env(_receiver_) returns an object. By default this operation returns std::execution::env<>. +- std::execution::get_env(_receiver_) returns an object. By default this operation returns std::execution::env<>. Typical members for _Receiver_: -- get_env() const noexcept -- set_value(args…) && noexcept -> void -- set_error(error) && noexcept -> void -- set_stopped() && noexcept -> void +- get_env() const noexcept +- set_value(args...) && noexcept -> void +- set_error(error) && noexcept -> void +- set_stopped() && noexcept -> void
Example -The example receiver prints the name of each the received completion signal before forwarding it to a receiver. It forwards the request for an environment (get_env) to the nested receiver. This example is resembling a receiver as it would be used by a sender injecting logging of received signals. +The example receiver prints the name of each the received completion signal before forwarding it to a receiver. It forwards the request for an environment (get_env) to the nested receiver. This example is resembling a receiver as it would be used by a sender injecting logging of received signals. ```c++ template @@ -104,18 +109,18 @@ struct example_receiver auto get_env() const noexcept { return std::execution::get_env(this->nested); } - template - auto set_value(A&&… a) && noexcept -> void { - std::cout << “set_value\n”; - std::execution::set_value(std::move(this->nested), std::forward(a)…); + template + auto set_value(A&&... a) && noexcept -> void { + std::cout << "set_value\n"; + std::execution::set_value(std::move(this->nested), std::forward(a)...); } template auto set_error(E&& e) && noexcept -> void { - std::cout << “set_error\n”; + std::cout << "set_error\n"; std::execution::set_error(std::move(this->nested), std::forward(e)); } auto set_stopped() && noexcept -> void { - std::cout << “set_stopped\n”; + std::cout << "set_stopped\n"; std::execution::set_stopped(std::move(this->nested)); } }; @@ -127,14 +132,15 @@ static_assert(std::execution::receiver>);
receiver_of<Receiver, Completions> + -The concept receiver_of<Receiver, Completions> tests whether std::execution::receiver<_Receiver_> is true and if an object of type _Receiver_ can be invoked with each of the completion signals in _Completions_. +The concept receiver_of<Receiver, Completions> tests whether std::execution::receiver<_Receiver_> is true and if an object of type _Receiver_ can be invoked with each of the completion signals in _Completions_.
Example -The example defines a simple receiver and tests whether it models `receiver_of` with different completion signals in _Completions_ +The example defines a simple receiver and tests whether it models `receiver_of` with different completion signals in _Completions_ (note that not all cases are true). ```c++ @@ -149,21 +155,21 @@ struct example_receiver // matching the exact signals models receiver_of: static_assert(std::execution::receiver_of); -// providing a superset of signal models models receiver_of: + >>); +// providing a superset of signal models receiver_of: static_assert(std::execution::receiver_of); + >>); // providing only a subset of signals doesn’t model receiver_of: static_assert(not std::execution::receiver_of); + >>); ```
@@ -171,12 +177,13 @@ static_assert(not std::execution::receiver_of
scheduler<Scheduler> -Schedulers are used to specify the execution context where the asynchronous work is to be executed. A scheduler is a lightweight handle providing a schedule operation yielding a sender with a value completion signal without parameters. The completion is on the respective execution context. + +Schedulers are used to specify the execution context where the asynchronous work is to be executed. A scheduler is a lightweight handle providing a schedule operation yielding a sender with a value completion signal without parameters. The completion is on the respective execution context. Requirements for _Scheduler_: - The type _Scheduler_::scheduler_concept is an alias for `scheduler_tag` or a type derived thereof. -- schedule(_scheduler_) -> sender -- The value completion scheduler of the sender’s environment is the _scheduler_: +- schedule(_scheduler_) -> sender +- The value completion scheduler of the sender’s environment is the _scheduler_: scheduler == std::execution::get_completion_scheduler<std::execution::set_value_t>( std::execution::get_env(std::execution::schedule(scheduler)) @@ -187,25 +194,25 @@ Requirements for _Scheduler_:
sender<Sender> + -Senders represent asynchronous work. They may get composed from multiple senders to model a workflow. Senders can’t be run directly. Instead, they are passed to a sender consumer which connects the sender to a receiver to produce an operation_state which may get started. When using senders to represent work the inner workings shouldn’t matter. They do become relevant when creating sender algorithms. +Senders represent asynchronous work. They may get composed from multiple senders to model a workflow. Senders can’t be run directly. Instead, they are passed to a sender consumer which connects the sender to a receiver to produce an operation_state which may get started. When using senders to represent work the inner workings shouldn’t matter. They do become relevant when creating sender algorithms. Requirements for _Sender_: - The type _Sender_::sender_concept is an alias for `sender_tag` or a type derived thereof or _Sender_ is a suitable _awaitable_. -- std::execution::get_env(_sender_) is valid. By default this operation returns std::execution::env<>. +- std::execution::get_env(_sender_) is valid. By default this operation returns std::execution::env<>. - Rvalues of type _Sender_ can be moved. - Lvalues of type _Sender_ can be copied. Typical members for _Sender_: -- get_env() const noexcept -- get_completion_signatures(_env_) const noexcept -> std::execution::completion_signatures<...> -- _Sender_::completion_signatures is a type alias for std::execution::completion_signatures<...> (if there is no get_completion_signatures member). -- connect(_sender_, receiver) -> operation_state +- get_env() const noexcept +- get_completion_signatures<Sender, Env...>() const noexcept -> std::execution::completion_signatures<...> +- connect(_sender_, receiver) -> operation_state
Example -The example shows a sender implementing an operation similar to just(_value). +The example shows a sender implementing an operation similar to just(_value). ```c++ struct example_sender @@ -242,28 +249,25 @@ static_assert(std::execution::sender);
sender_in<Sender, Env = std::execution::env<>> + -The concept sender_in<Sender, Env> tests whether _Sender_ is a sender, _Env_ is a destructible type, and std::execution::get_completion_signatures<_Sender_, _Env_>() yields a specialization of std::execution::completion_signatures. +The concept sender_in<Sender, Env> tests whether _Sender_ is a sender, _Env_ is a destructible type, and std::execution::get_completion_signatures<_Sender_, _Env_>() yields a specialization of std::execution::completion_signatures.
sender-to<Sender, Receiver> -The concept sender-to<Sender, Receiver> tests if std::execution::sender_in<_Sender_, std::execution::env_of_t<_Receiver_>> is true, and if _Receiver_ can receive all completion signals which can be sent by _Sender_, and if _Sender_ can be connected to _Receiver_. - -To determine if _Receiver_ can receive all completion signals from _Sender_ it checks that for each _Signature_ in std::execution::get_completion_signals(_sender_, std::declval<std::execution::env_of_t<_Receiver_>>()) the test std::execution::receiver_of<_Receiver_, _Signature_> yields true. To determine if _Sender_ can be connected to _Receiver_ the concept checks if connect(std::declval<_Sender_>(), std::declval<_Receiver_>) is a valid expression. -
-
-sends_stopped<Sender, Env = std::execution::env<>> +The concept sender-to<Sender, Receiver> tests if std::execution::sender_in<_Sender_, std::execution::env_of_t<_Receiver_>> is true, and if _Receiver_ can receive all completion signals which can be sent by _Sender_, and if _Sender_ can be connected to _Receiver_. -The concept sends_stopped<Sender, Env> determines if _Sender_ may send a stopped completion signal. To do so, the concepts determines if std::execution::get_completion_signals(_sender_, _env_) contains the signatures std::execution::set_stopped_t(). +To determine if _Receiver_ can receive all completion signals from _Sender_ it checks that for each _Signature_ in std::execution::get_completion_signatures(_sender_, std::declval<std::execution::env_of_t<_Receiver_>>()) the test std::execution::receiver_of<_Receiver_, _Signature_> yields true. To determine if _Sender_ can be connected to _Receiver_ the concept checks if connect(std::declval<_Sender_>(), std::declval<_Receiver_>) is a valid expression.
stoppable_token<Token> -A stoppable_token<Token>, e.g., obtained via std::execution::get_stop_token(env) is used to support cancellation of asynchronous operations. Using token.stop_requested() an active operation can poll whether it was requested to cancel. An inactive operation waiting for a notification can use an object of a specialization of the template Token::callback_type to get notified when cancellation is requested. + +A stoppable_token<Token>, e.g., obtained via std::execution::get_stop_token(env) is used to support cancellation of asynchronous operations. Using token.stop_requested() an active operation can poll whether it was requested to cancel. An inactive operation waiting for a notification can use an object of a specialization of the template Token::callback_type to get notified when cancellation is requested. Required members for _Token_: -- Token::callback_type<Callback> can be specialized with a std::callable<Callback> type. +- Token::callback_type<Callback> can be specialized with a std::invocable<Callback> type. - token.stop_requested() const noexcept -> bool - token.stop_possible() const noexcept -> bool - std::copyable<Token> @@ -274,9 +278,9 @@ Required members for _Token_: Example: concept use ```c++ -static_assert(std::execution::unstoppable_token); -static_assert(std::execution::unstoppable_token); -static_assert(std::execution::unstoppable_token); +static_assert(not std::execution::stoppable_token); +static_assert(std::execution::stoppable_token); +static_assert(std::execution::stoppable_token); ```
@@ -295,7 +299,7 @@ void compute(std::stoppable_token auto token)
Example: inactive -This example shows how an operation_state can use the callback_type together with a token to get notified when cancellation is requested. +This example shows how an operation_state can use the callback_type together with a token to get notified when cancellation is requested. ```c++ template @@ -310,18 +314,18 @@ struct example_state }; using operation_state_concept = std::execution::operation_state_tag; using env = std::execution::env_of_t; - using token = std::execution::stop_callback_of_t; - using callback = std::execution::stop_callback_of_t; + using token = std::execution::stop_token_of_t; + using callback = std::execution::stop_callback_for_t; std::remove_cvref_t receiver; std::optional cancel{}; std::atomic outstanding{}; auto start() & noexcept { this->outstanding += 2u; this->cancel.emplace( - std::execution::get_stop_token(this->receiver), + std::execution::get_stop_token(std::execution::get_env(this->receiver)), on_cancel{*this} ); - if (this->outstanding != 2u) + if (--this->outstanding == 2u) std::execution::set_stopped(std::move(this->receiver)); else { register_work(this); @@ -348,11 +352,12 @@ struct example_state
unstoppable_token<Token> + The concept unstoppable_token<Token> is modeled by a Token if stoppable_token<Token> is true and it can statically be determined that both token.stop_requested() and token.stop_possible() are constexpr epxressions yielding false. This concept is used to avoid extra work when using stop tokens which will never indicate that cancellations are requested.
Example -The concept yields true for the std::execution::never_stop_token: +The concept yields true for the std::execution::never_stop_token: ```c++ static_assert(std::execution::unstoppable_token); @@ -368,11 +373,11 @@ The queries are used to obtain properties associated with an object.
Example defining a query on an environment -This example shows how to define an environment class which provides a get_allocator query. The objects stores a std::pmr::memory_resource* and returns a correspondingly initialized std::pmr::polymorphic_allocator<>. +This example shows how to define an environment class which provides a get_allocator query. The objects stores a std::pmr::memory_resource* and returns a correspondingly initialized std::pmr::polymorphic_allocator<>. ``` struct alloc_env { - std::pmr::memory_resource res{std::pmr::new_delete_resource()}; + std::pmr::memory_resource* res{std::pmr::new_delete_resource()}; auto query(get_allocator_t const&) const noexcept { return std::pmr::polymorphic_allocator<>(this->res); @@ -382,6 +387,7 @@ struct alloc_env {
forwarding_query(query) -> bool + Default: false
The expression forwarding_query(query) is a constexpr query used to determine if the query query should be forwarded when wrapping an environment. The expression is required to be a core constant expression if query is a core constant expression. @@ -419,22 +425,24 @@ struct custom_t: forwarding_query_t {
get_await_completion_adaptor(queryable) -> awaiter + If the expression get_await_completion_adaptor(queryable) is valid it yields an awaiter depending on the queryable. This query is used while getting an awaiter from a sender.
get_env(queryable) -> env + Default: env<>
-The expression get_env(queryable) is used to get the environment env associated with queryable. To provide a non-default environment for a queryable a get_env member needs to be defined. If queryable doesn’t provide the get_env query an object of type env<> is returned. +The expression get_env(queryable) is used to get the environment env associated with queryable. To provide a non-default environment for a queryable a get_env member needs to be defined. If queryable doesn’t provide the get_env query an object of type env<> is returned. The value of the expression is
  1. the result of as_const(queryable).get_env() if this expression is valid and noexcept.
  2. -
  3. env<> otherwise. +
  4. env<> otherwise.
Example -The example defines an environment class env which stores a pointer to the relevant data and is returned as the environment for the type `queryable`: +The example defines an environment class env which stores a pointer to the relevant data and is returned as the environment for the type `queryable`: ```c++ struct data { /*...*/ }; @@ -455,6 +463,7 @@ Note that the `get_env` member is both `const` and `noexcept`.
get_allocator(env) -> allocator + Default: none
The expression get_allocator(env) returns an allocator for any memory allocations in the respective context. If env doesn’t support this query any attempt to access it will result in a compilation error. The value of the expression get_allocator(env) is the result of as_const(env).query(get_allocator) if @@ -467,11 +476,11 @@ Otherwise the expression is ill-formed.
Example -This example shows how to define an environment class which provides a get_allocator query. The objects stores a std::pmr::memory_resource* and returns a correspondingly initialized std::pmr::polymorphic_allocator<>. +This example shows how to define an environment class which provides a get_allocator query. The objects stores a std::pmr::memory_resource* and returns a correspondingly initialized std::pmr::polymorphic_allocator<>. ``` struct alloc_env { - std::pmr::memory_resource res{std::pmr::new_delete_resource()}; + std::pmr::memory_resource* res{std::pmr::new_delete_resource()}; auto query(get_allocator_t const&) const noexcept { return std::pmr::polymorphic_allocator<>(this->res); @@ -484,23 +493,23 @@ struct alloc_env {
get_completion_domain<Tag>(attrs) -> domain + Default: none
The expression get_completion_domain<Tag>(attrs) yields the completion domain for the completion signal Tag associated with the sender attrs. This query can be used to determine the domain a sender sender completes on for a given completion signal Tag by using get_completion_domain<Tag>(get_env(sender), ev...). The value of the expression is
    -
  1. equivalent to as_const(env).query(get_completion_domain<Tag>, ev...) if +
  2. equivalent to as_const(attrs).query(get_completion_domain<Tag>, ev...) if Tag is one of the types set_value_t, set_error_t, or set_stopped_t and the expression is valid;
  3. -
  4. equivalent to as_const(env).query(get_completion_domain<Tag>) if Tag is one of the types set_value_t, set_error_t, or set_stopped_t and the expression is valid;
  5. -
  6. equivalent to get_completion_domain<set_value_t>(get_env(sender), ev...) if Tag is void and the expression is valid;
  7. -
  8. equivalent to TRY-QUERY(get_completion_scheduler<Tag>(attrs, env...), get_completion_domain<set_value_t>, ev...) if this expression is well-formed;
  9. +
  10. equivalent to get_completion_domain<set_value_t>(get_env(attrs), ev...) if Tag is void and the expression is valid;
  11. +
  12. equivalent to TRY-QUERY(get_completion_scheduler<Tag>(attrs, env...), get_completion_domain<attrs>, ev...) if this expression is well-formed;
  13. equivalent to default_domain if scheduler<decltype(attrs)> is true and 0u < sizeof...(ev);
  14. ill-formed otherwise.
-Otherwise the expression is invalid.
get_completion_scheduler<Tag>(env) -> scheduler + Default: none
The expression get_completion_scheduler<Tag>(env) yields the completion scheduler for the completion signal Tag associated with env. This query can be used to determine the scheduler a sender sender completes on for a given completion signal Tag by using get_completion_scheduler<Tag>(get_env(sender)). The value of the expression is equivalent to as_const(env).query(get_completion_scheduler<Tag>) if @@ -513,8 +522,9 @@ The expression get_completion_scheduler<Tag>(env) yiel Otherwise the expression is invalid.
-get_completion_signatures(sender, env) -The expression get_completion_signatures(sender, env) returns an object whose type is a specialization of completion_signatures defining the possible completion signatures of sender when connected to a receiver whose environment get_env(receiver) is env. A sender can define the result of this query either by defining a member function get_completion_signatures or using a type alias completion_signatures. +get_completion_signatures<Sender, Env>() + +The expression get_completion_signatures<Sender, Env()) returns an object whose type is a specialization of completion_signatures defining the possible completion signatures of the sender type Sender when connected to a receiver whose environment get_env(receiver) returns an object of type Env. A sender defines the result of this query by defining a static consteval member function get_completion_signatures. To determine the result the sender is first transformed using transform_sender(domain, sender, env) to get new-sender with type New-Sender-Type. With that the result type is
    @@ -526,7 +536,7 @@ To determine the result the sender is first transformed usin
    Example -Even when a sender doesn’t need to compute the completion signatures based on an environment it is necessary to provide get_completion_signatures member function, e.g.: +Even when a sender doesn’t need to compute the completion signatures based on an environment it is necessary to provide get_completion_signatures member function, e.g.: ```c++ struct sender { @@ -547,6 +557,7 @@ struct sender {
    get_delegation_scheduler(env) -> scheduler + The expression get_delegation_scheduler(env) yields the scheduler associated with env which is used for forward progress delegation. The value of the expression is equivalent to as_const(env).query(get_delegation_scheduler) -> scheduler if
    1. this expression is valid;
    2. @@ -557,17 +568,18 @@ Otherwise the expression is invalid.
    get_domain(env) -> domain + The expression get_domain(env) yields the domain associated with env. The value of the expression is equivalent to return D() where D is the type of the expression
    1. auto(as_const(env).query(get_domain)) if this expression is valid;
    2. otherwise, get_completion_domain<set_value_t>(get_scheduler(env), HIDE-SCHED(env)) if this expression is valid;
    3. default_domain() (except env is evaluated).
    -Otherwise the expression is invalid.
    get_forward_progress_guarantee(scheduler) -> forward_progress_guarantee -The expression get_forward_progress_guarantee(scheduler) yields the forward progress guarantee of the scheduler’s execution agent. The value of the expression is equivalent to as_const(env).query(get_forward_progress_guarantee) if + +The expression get_forward_progress_guarantee(scheduler) yields the forward progress guarantee of the scheduler’s execution agent. The value of the expression is equivalent to as_const(scheduler).query(get_forward_progress_guarantee) if
    1. this expression is valid;
    2. this expression is noexcept;
    3. @@ -577,21 +589,23 @@ Otherwise the expression is invalid.
    get_scheduler(env) -> scheduler + The expression get_scheduler(env) yields the scheduler associated with env. The value of the expression is equivalent to as_const(env).query(get_scheduler) if
    1. this expression is valid;
    2. this expression is noexcept;
    3. -
    4. the expression’s type satisfies scheduler. +
    5. the expression’s type satisfies scheduler.
    Otherwise the expression is invalid.
    get_start_scheduler(env) -> scheduler -The expression get_start_scheduler(env) yields the scheduler associated with env. The value of the expression is equivalent to as_const(env).query(get_scheduler) if + +The expression get_start_scheduler(env) yields the scheduler associated with env. The value of the expression is equivalent to as_const(env).query(get_start_scheduler) if
    1. this expression is valid;
    2. this expression is noexcept;
    3. -
    4. the expression’s type satisfies scheduler. +
    5. the expression’s type satisfies scheduler.
    Otherwise the expression is invalid. @@ -601,6 +615,7 @@ from connect(sndr, rcvr) gets started on
    get_stop_token(env) -> stoppable_token + The expression get_stop_token(env) yields the stop token associated with env. The value is the result of the expression as_const(env).query(get_stop_token) if
    • the expression is valid;
    • @@ -614,22 +629,27 @@ Otherwise the value is never_stop_token{}.
      connect(sender, receiver) -> operation_state + The expression connect(sender, receiver) combines sender and receiver into an operation state state. When this state gets started using start(state) the operation represented by sender gets started and reports its completion to receiver or an object copied or moved from receiver. While the operation state state isn’t started it can be destroyed but once it got started it needs to stay valid until one of the completion signals is called on receiver.
      set_error(receiver, error) noexcept -> void + The expression set_error(receiver, error) invokes the set_error completion signal on receiver with the argument error, i.e., it invokes receiver.set_error(error).
      set_stopped(receiver) noexcept -> void + The expression set_stopped(receiver) invokes the set_stopped completion signal on receiver, i.e., it invokes receiver.set_stopped().
      set_value(receiver, value...) noexcept -> void + The expression set_value(receiver, value...) invokes the set_value completion signal on receiver with the argument(s) value..., i.e., it invokes receiver.set_value(value...).
      start(state) noexcept -> void + The expression start(state) starts the execution of the operation_state object state. Once this expression started executing the object state is required to stay valid at least until one of the completion signals of state’s receiver is invoked. Once started exactly one of the completion signals is eventually called.
      @@ -641,6 +661,7 @@ Sender factories create a sender which forms the start of a graph of lazy work i
      just(value...) -> sender-of<set_value_t(Value...)> + The expression just(value...) creates a sender which sends value... on the set_value (success) channel when started (note that value... can be empty). Completions @@ -650,6 +671,7 @@ The expression just(value...) creates a sender which sends <
      just_error(error) -> sender-of<set_error_t(Error)> + The expression just_error(error) creates a sender which sends error on the set_error (failure) channel when started. Completions @@ -659,6 +681,7 @@ The expression just_error(error) creates a sender which send
      just_stopped() -> sender-of<set_stopped_t()> + The expression just_stopped() creates a sender which sends a completion on the set_stopped (cancellation) channel when started. Completions @@ -668,6 +691,7 @@ The expression just_stopped() creates a sender which sends a comple
      read_env(query) -> sender-of<set_value_t(query-result)> + The expression read_env(query) creates a sender which sends the result of querying query the environment of the receiver it gets connected to on the set_value channel when started. Put differently, it calls set_value(move(receiver), query(get_env(receiver))). For example, in a coroutine it may be useful to extra the stop token associated with the coroutine which can be done using read_env: ```c++ @@ -681,6 +705,7 @@ auto token = co_await read_env(get_stop_token);
      schedule(scheduler) -> sender-of<set_value_t()> + The expression schedule(scheduler) creates a sender which upon success completes on the set_value channel without any arguments running on the execution context associated with scheduler. Depending on the scheduler it is possible that the sender can complete with an error if the scheduling fails or using set_stopped() if the operation gets cancelled before it is successful. Completions @@ -696,26 +721,32 @@ The sender adaptors take one or more senders and adapt their respective behavior
      affine(sender) -> sender-of<completions-of(sender)> -The expression affine(sender) creates a sender which completes on the same scheduler it was started on, even if sender changes the scheduler. The scheduler to resume on is determined using get_start_scheduler(get_env(rcvr)) where rcvr is the receiver the sender is connected to. The scheduler sched returned from get_start_scheduler(get_env(rcvr)) has to be infallible, i.e., the completion signtures of scheduler(sched) only contain set_value_t(). + +The expression affine(sender) creates a sender which completes on the same scheduler it was started on, even if sender changes the scheduler. The scheduler to resume on is determined using get_start_scheduler(get_env(rcvr)) where rcvr is the receiver the sender is connected to. The scheduler sched returned from get_start_scheduler(get_env(rcvr)) has to be infallible, i.e., the completion signtures of schedulesched) only contain set_value_t(). The primary use of affine is implementing scheduler affinity for task.
      associate(sndr, token) -> sender +
      bulk(sndr, policy, shape, fun) -> sender +
      bulk_chunked(sndr, policy, shape, fun) -> sender +
      bulk_unchunked(sndr, policy, shape, fun) -> sender +
      continues_on(sender, scheduler) -> sender-of<completions-of(sender) + completions-of(schedule(scheduler))> + The expression continues_on(sender, scheduler) creates a sender cs which starts sender when started. The results from sender are stored. Once that is cs creates a sender using schedule(scheduler) and completes itself on the execution once that sender completes. Completions @@ -726,22 +757,27 @@ The expression continues_on(sender, scheduler) create
      into_variant(sender) -> sender-of<set_value_t(std::variant<Tuple...>)> + The expression into_variant(sender) creates a sender which transforms the results of possibly multiple set_value completions of sender into one set_value completion representing the different upstream results as different options of a variant<Tuple...> where each Tuple is a tuple of values initialized with the respective arguments passed to set_value. The order of options in the variant isn’t specified.
      let_error(upstream, fun) -> sender + The expression let_error(upstream, fun) yields a sender sndr which uses an error completion (set_error) of upstream as an argument to invoke fun which has to return another sender inner-sndr and the completion of inner-sndr becomes the completion of sndr. If this invocation results in an exception sndr completes with an error completion the result of std::current_exception. If upstream completes successfully (set_value) or with a cancellation (set_stopped) this completion becomes the completion of sndr.
      let_stopped(upstream, fun) -> sender + The expression let_stopped(upstream, fun) yields a sender sndr which uses a cancellation completion (set_stopped) of upstream to invoke fun which has to return another sender inner-sndr and the completion of inner-sndr becomes the completion of sndr. If this invocation results in an exception sndr completes with an error completion the result of std::current_exception. If upstream completes successfully (set_value) or with an error (set_error) this completion becomes the completion of sndr.
      let_value(upstream, fun) -> sender + The expression let_value(upstream, fun) yields a sender sndr which uses a successful completion (set_value) of upstream as arguments to invoke fun which has to return another sender inner-sndr and the completion of inner-sndr becomes the completion of sndr. If this invocation results in an exception sndr completes with an error completion the result of std::current_exception. If upstream completes with a cancellation (set_stopped) or with an error (set_error) this completion becomes the completion of sndr.
      on(sched, sndr), on(sndr, sched, closure) + The on algorithm is a pipeable sender adaptor. Let on-sender be
      • sndr when the form on(sched, sndr) is used;
      • @@ -752,18 +788,22 @@ The on algorithm completes on the original scheduler (obtained usin
      schedule_from(sender) -> sender + The expression schedule_from(sender) yields a sender which behaves likes sender. The purpose of the schedule_from is to allow schedulers to customize the way how to transition off the execution context.
      spawn_future(sndr, token) -> sender +
      `split` +
      starts_on(scheduler, sender) -> sender + The expression starts_on(scheduler, sender) yields a sender which starts sender on the scheduler's context, i.e., it starts schedule(scheduler) and then starts sender @@ -771,16 +811,20 @@ where the scheduler's sender completes.
      stopped_as_error(sndr) +
      stopped_as_optional(sndr) +
      then(upstream, fun) -> sender -The expression then(upstream, fun) yields a sender sndr which on successful completion of upstream (set_value) calls fun with the arguments passed to set_value and yields the function return as its own result. If the function throws or upstream completes with an error (set_error) the exception or the error becomes sndr's result. If upstream completes with a cancellation (set_stopped). + +The expression then(upstream, fun) yields a sender sndr which on successful completion of upstream (set_value) calls fun with the arguments passed to set_value and yields the function return as its own result. If the function throws or upstream completes with an error (set_error) the exception or the error becomes sndr's result. If upstream completes with a cancellation (set_stopped) sndr also completes with set_stopped.
      unstoppable(sender) -> sender + The expression unstoppable(sender) yields a sender which passes its receiver's environment to sender except that the get_stop_token query return never_stop_token: @@ -789,21 +833,26 @@ is unstoppable.
      upon_error(upstream, fun) -> sender + The expression upon_error(upstream, fun) yields a sender sndr which passes an error completion (set_error) of upstream to fun and uses this result of this function invocation for its own successful (set_value) completion. If the function invocation throws std::current_exception() becomes sndr's error (set_error) completion. The success (set_value) and cancellation (set_stopped) completions of upstream are forwarded.
      upon_stopped(upstream, fun) -> sender + The expression upon_stopped(upstream, fun) yields a sender sndr which turns a cancellation completion (set_stopped) result of upstream to fun and uses this result of this function invocation for its own successful (set_value) completion. If the function invocation throws std::current_exception() becomes sndr's error (set_error) completion. The success (set_value) and error (set_error) completions of upstream are forwarded.
      when_all(sender...) -> sender + The expression when_all(sender...) yields a sender sndr which completes successfully (set_value) when all nested senders sender... completed successfully using the results of the nested senders in order. If any of the senders completes with an error (set_error) or a cancellation (set_stopped) the first such completion becomes the completion of sndr once all nested senders completed. A stop is requested for the stop source(s) whose token was passed to the nested senders.
      when_all_with_variant(sender...) -> sender +
      write_env(sender, env) -> sender + The expression write_env(sender, env) creates a sender which passes a receiver to sender which combines the environment env with the environment from the receiver's environment. The @@ -833,24 +882,29 @@ Note that `write_env` affects the sender passed as first argument or, when using
      sync_wait(sender) -> std::optional<std::tuple<T...>> +
      sync_wait_with_variant(sender) -> std::optional<std::variant<std::tuple<T...>...>> +
      spawn(sndr, token) -> void +
      ## Helpers
      adapt-for-await-completion(s) + The expression is equivalent to get_await_completion_adaptor(get_env(s))(s) except that s is evaluated only once.
      as_awaitable(expr, promise) + The expression as_awaitable(expr, promise) tries to create an awaitable from expr and promise. It tries the following transformations: @@ -868,6 +922,7 @@ tries the following transformations:
      completion_signatures<Sig...> + The template specialization completion_signatures<Sig...> is a list of completion signatures used to declare and compute the result types of senders. @@ -882,6 +937,7 @@ It has two exposition-only members template: - `default_domain`
      env<Ev...> + The expression env(ev...) creates an environment by combining the environments ev.... If multiple of the environments support an identical query, the first one from the first environment is used. @@ -889,12 +945,14 @@ one from the first environment is used. - `env_of_t`
      error_types_of_t<Sndr, Env = env<>, Variant = variant-or-empty> + The template specialization error_types_of_t<<sndr, Env, Variant> gets Sndr error completion signatures when using the environment Env. The results is represented as a Variant<E... where E... is the list of argument types to the completion signatures.
      - `fwd_env` - `operation_state_tag`
      prop<Query, Value> + The expression prop(query, value) create an object which can be queried for query query which results in value. @@ -902,13 +960,14 @@ be queried for query query which results in value run_loop + The class run_loop provides a scheduler to execute work on. It is used to implement sync_wait(sndr). The public methods on an object loop of type run_loop are:
      • loop.get_scheduler() to get a scheduler scheduling work on loop.
      • loop.finish() to request loop to exit processing work items. Note that run_loop doesn't maintain a stop source, i.e., when this operation is invoked the work doesn't get cancelled.
      • -
      • loop.run() to have the current thread execute work items scheduled on loop. The thread will continue processing work items as long as loop.finish() wasn't called or there is work scheduled on loop. +
      • loop.run() to have the current thread execute work items scheduled on loop. The thread will continue processing work items as long as loop.finish() wasn't called or there is work scheduled on loop.
      @@ -919,6 +978,7 @@ an object loop of type run_loop are:
      bool sends_stopped<Sndr, Env = env<>> + The Boolean variable sends_stopped<Sndr, Env> is true if the completion signatures of Sndr when using the environment Env contain a cancellation signature (set_stopped_t()).
      @@ -926,6 +986,7 @@ The Boolean variable sends_stopped<Sndr, Env> i
      tag_of_t<Sndr> +
      • if auto&&[tag, data, children...] = sndr; is well-formed the type decltype(auto(tag));
      • otherwise ill-formed.
      • @@ -937,6 +998,7 @@ The Boolean variable sends_stopped<Sndr, Env> i - `transform_completion_signatures_of`
        value_types_of_t<Sndr, Env = env<>, Tuple = decayed-tuple, Variant = variant-or-empty> + The template specialization value_types_of_t<Sndr, Env, Tuple, Variant> gets Sndr success completion signatures when using the environment Env. The resulting type is a Variant of Tuple elements where each Tuple represents the argument types of one of the value completion signatures.
        @@ -949,6 +1011,7 @@ The template specialization value_types_of_t<Sndr, Env, <
        as-except-ptr(err) + Turns err smartly into an exception_ptr:
        1. if same_as<decay_t<decltype(err)>, exception_ptr> ⇒ err
        2. @@ -959,6 +1022,7 @@ Turns err smartly into an exception_ptr:
          awaitable-sender<Sndr, Promise> + The concept check awaitable-sender<Sndr, Promise> determines if the Sndr could work with the environment provided by Promise and if Promise supports a suitable unhandled_stopped() method. @@ -966,12 +1030,14 @@ and if Promise supports a suitable unhandled_stopped()
          concept class-type<T> + Determines if the type T is a decayed class type: decays-to<T, T> && is_class_v<T>
          COMMON-DOMAIN(domains...) + The expression COMMON-DOMAIN(domains...) is
            @@ -982,6 +1048,7 @@ The expression COMMON-DOMAIN(domains...) is
            COMPL-DOMAIN<Tag>(sndr, ev...) + The expression COMPL-DOMAIN<Tag>(sndr, ev...) gets sndrs completion domain given the optional environment ev...: @@ -989,12 +1056,11 @@ domain given the optional environment ev...:
          • get_completion_domain(get_env(sndr), ev..) if this expression is well-formed,
          • indeterminate_domain() otherwise.
          - -Note: it seems this exposition-only name is actually unused!
          concept completion-signature<Signature> + This concept determines if the type Signature is a completion signature, i.e., if it has one of these three forms:
            @@ -1006,12 +1072,14 @@ if it has one of these three forms:
            concept decays-to<From, To> + Determines if To is the result of decaying the type From: same_as<decay_t<From>, To>
            FWD-ENV(env) + The expression FWD-ENV(env) yields a queryable object q supporting only forwardable queries. Let qry be a query object and a... be a possibly emnpty pack of arguments. Then q.query(qry, a...) is
            • equivalent to env.query(qry, a...) if forwarding_query(qry) is true
            • @@ -1021,36 +1089,43 @@ The expression FWD-ENV(env) yields a queryable object
              FWD-ENV-T(Env) -The type FWD-ENV-T(Env) is decltype(FWD-ENV(decl_val<Env>())). + +The type FWD-ENV-T(Env) is decltype(FWD-ENV(declval<Env>())).
              gather-signatures<Tag, Signatures, Tuple, Variant> + The template specializaton gather-signatures<Tag, Signatures, Tuple, Variant> represents the completion signatures in the type list Signatures using Tag (one of set_value_t, set_error_t, or set_stopped_t) as a Variant of Tuples. Each Tuple has the element types of of one of the matching completion signatures.
              concept has-completions<Rcvr, Completions> + This concept determines if an object of type Rcvr supports ech of the completion signatures in Completions.
              HIDE-SCHED(q) + For a query object tag and arguments a... the expressions HIDE-SCHED(q).query(tag, a...) is
              • undefined if decay_t<decltype(tag)> is get_scheduler_t or get_domain_t
              • equivalent to q.query(tag, a...) otherwise
              • +
              infallible-scheduler<Sched, Env> + Determines if Sched is a scheduler (i.e., scheduler<Sched> is true) and if sched's sender has only a set_value_t() completion signature when used with an environment with an unstoppable_token<Tok> stop token Tok. If the stop token Tok is not unstoppable_token<Tok> the completion signatures can include a set_stopped_t() completion signature in addition to the set_value_t() completion signature.
              JOIN-ENV(ev1, ev2) + The expression JOIN-ENV(ev1, ev2) yields a queryable object env such that for a query qry and a pack of arguments a... the result of the expression env.query(qry, a...) is
                @@ -1063,17 +1138,20 @@ The expression JOIN-ENV(ev1, ev2) yields a queryable object
                make-sender(tag, data = empty{}, child...) + Creates and object of type basic-sender<decltype(tag), decay_t<decltype(data)>, decay_t<decltype(child)>...> that's direct initialized with the forwarded arguments.
                MAKE-ENV(qry, value) + The expression MAKE-ENV(qry, value) creates a queryable object env such that for a pack of arguments a ... the expression env.query(qry, a...) yields value.
                constexpr bool MATCHING-SIG<F1, F2> + Determines if the two function signatures F1 and F2 match: If same_as<F1, R1(A1...)> and same_as<F2, R2(A2...)> then @@ -1082,12 +1160,14 @@ If same_as<F1, R1(A1...)> and same_as<F2, R2(A2...)&
                concept movable-value<T> + Determines if objects of type T are movable, non-array values: -move_constructible<decay_t<T>> && constructible_from<decay_t<T>> && (!is_array_v<remove_reference_t<T>>) +move_constructible<decay_t<T>> && constructible_from<decay_t<T>, T> && (!is_array_v<remove_reference_t<T>>)
                struct product-type<T...> + The type product-type<T...> is a tuple-like type. Instead of constructors it supports only direct initialization, allowing it to hold inplace constructed elements. It supports p.get<I>() and p.apply(fun) @@ -1096,6 +1176,7 @@ member functions.
                concept queryable<T> + Determines if objects of type T are queryable: destructible<T>. The semantic implication is that using the queryable object with query objects behave as required. @@ -1103,6 +1184,7 @@ that using the queryable object with query objects behave as required.
                query-with-default(tag, env, value) + Returns
                • tag(env) if this expression is well-formed
                • @@ -1112,64 +1194,73 @@ Returns
                  concept receiver-of<Rcvr, Signatures> + This concept determines if an object of type Rcvr is a receiver (i.e., receiver<Rcvr> is true) and supports each of the completion signatures in Signatures.
                  SCHED-ENV(sch) + The expression SCHED-ENV(sch) yields a queryable o such that
                    -
                  • get_start_scheduler(o) is equivalent to get_start_scheduler(get_env(o))
                  • -
                  • get_domain(o) is equivalent to get_start_scheduler(get_env(o))
                  • +
                  • get_start_scheduler(sch) is equivalent to get_start_scheduler(get_env(o))
                  • +
                  • get_domain(sch) is equivalent to get_get_domain(get_env(o))
                  scope-join-t + The type scope-join-t is used with basic-sender to create a sender which completes when a counting scope becomes closed and empty.
                  scope-state-type + The type scope-state-type is used to represent the state a counting scope is currently in. The values are
                    -
                  • unused
                  • -
                  • open
                  • -
                  • open-and-joining
                  • -
                  • closed
                  • -
                  • closed-and-joining
                  • -
                  • unused-and-closed
                  • -
                  • joined
                  • +
                  • unused
                  • +
                  • open
                  • +
                  • open-and-joining
                  • +
                  • closed
                  • +
                  • closed-and-joining
                  • +
                  • unused-and-closed
                  • +
                  • joined
                  -
                  +
                  sender-awaitable<Sndr, Promise> + The specialization sender-awaitable<Sndr, Promise> is an awaiter implemented by getting the result of the Sndr completion.
                  concept single-sender<Sndr, Env...> + The test single-sender<Sndr, Env...> is true if Sndr has exactly one successful completion signature when using an environment of type Env....
                  single-sender-value-type<Sndr, Env...> + The type single-sender-value-type<Sndr, Env...> is defined if Sndr has exactly one successful completion signature set_value_t(T...) when using an environment of type Env.... The type is
                  • T... if 1u == sizeof...(T) (i.e., there is one element);
                  • void if 0u == sizeof...(T) (i.e., there is no element);
                  • -
                  • std::tuple<T...> otherwise. +
                  • std::tuple<T...> otherwise.
                  stop-when(sndr, token) +
                  TRY-QUERY(q, tag, a...) + Tries to apply the query tag to the queryable object q: if passing the arguments a... is valid passes these arguments (AS-CONST(q).query(tag, a...)), otherwise queries q for tag without the arguments (AS-CONST(q).query(tag)), although the @@ -1178,17 +1269,20 @@ arguments are evaluated.
                  concept valid-completion-for<Signature, Rcvr> + This concept determines if an object of type Rcvr supports the completion signature Signature.
                  concept valid-specialization<T, Args...> + This concept determines the class template T can be specialized with arguments Args..., i.e., if T<Args...> is valid.
                  concept simple-allocator<Alloc> + The concept simple-allocator<Alloc> determines if Alloc is a basic allocator. If `alloc` is an object of type @@ -1196,8 +1290,8 @@ The concept simple-allocator<Alloc> determines if
                  • `alloc.allocate(n)` has type `Alloc::value_type*`.
                  • -
                  • `alloc.deallocate(alloc.allocate(n), n)` needs to be valid. -
                  • The type `Alloc` needs to be copy-constructible. -
                  • Two objects of type `Alloc` need to be equality comparable. +
                  • `alloc.deallocate(alloc.allocate(n), n)` needs to be valid.
                  • +
                  • The type `Alloc` needs to be copy-constructible.
                  • +
                  • Two objects of type `Alloc` need to be equality comparable.