1. Introduction
This paper proposes a self-contained design for a Standard C++ framework for managing asynchronous execution on generic execution contexts. It is based on the ideas in [P0443R14] and its companion papers.
1.1. Motivation
Today, C++ software is increasingly asynchronous and parallelism, a trend that is likely to only continue going forward. Asynchrony and parallelism appears everywhere, from processor hardware interfaces, to networking, to file I/O, to GUIs, to accelerators. Every C++ domain and every platform need to deal with asynchrony and parallelism, from scientific computing to video games to financial services, from the smallest mobile devices to your laptop to GPUs in the world’s fastest supercomputer.
While the C++ Standard Library has a rich set concurrency primitives (
,
,
, etc) and lower level building blocks (
, etc), we lack a Standard vocabulary and framework for asynchrony and parallelism that C++ programmers desperately need.
/
/
, C++11’s intended exposure for asynchrony, is inefficient, hard to use correctly, and severely lacking in genericity, making it unusable in many contexts.
We introduced parallel algorithms to the C++ Standard Library in C++17, and while they are an excellent start, they are all inherently synchronous and not composable.
This paper proposes a Standard C++ model for asynchrony, based around three key abstractions: schedulers, senders, and receivers, and a set of customizable asynchronous algorithms.
1.2. Priorities
-
Be composable and generic, allowing users to write code that can be used with many different types of execution contexts.
-
Encapsulate common asynchronous patterns in customizable and reusable algorithms, so users don’t have to invent things themselves.
-
Make it easy to be correct by construction.
-
Support both lazy and eager execution in a way that does not compromise the efficiency of either and allows users to write code that is agnostic to eagerness.
-
Support the diversity of execution contexts and execution agents, because not all execution agents are created equal; some are less capable than others, but not less important.
-
Allow everything to be customized by an execution context, including transfer to other execution contexts, but don’t require that execution contexts customize everything.
-
Care about all reasonable use cases, domains and platforms.
-
Errors must be propagated, but error handling must not present a burden.
-
Support cancellation, which is not an error.
-
Have clear and concise answers for where things execute.
-
Be able to manage and terminate the lifetimes of objects asynchronously.
1.3. Examples
See § 4.11 User-facing sender factories, § 4.12 User-facing sender adaptors, and § 4.13 User-facing sender consumers for short explanations of the algorithms used in these code examples.
1.3.1. Hello world
using namespace std :: execution ; executor auto sch = get_thread_pool (). scheduler (); // 1 sender auto begin = schedule ( sch ); // 2 sender auto hi_again = then ( begin , []{ // 3 std :: cout << "Hello world! Have an int." ; // 3 return 13 ; // 3 }); // 3 sender auto add_42 = then ( hi_again , []( int arg ) { return arg + 42 ; }); // 4 auto [ i ] = std :: this_thread :: sync_wait ( add_42 ). value (); // 5
This example demonstrates the basics of schedulers, senders, and receivers:
-
First we need to get a scheduler from somewhere, such as a thread pool. A scheduler is a lightweight handle to an execution resource.
-
To start a chain of work on a scheduler, we call § 4.11.1 execution::schedule, which returns a sender that completes on the scheduler. sender describes asynchronous work and sends a signal (value, error, or done) to some recipient(s) when that work completes.
-
We use sender algorithms to produce senders and compose asynchronous work. § 4.12.2 execution::then is a sender adaptor that takes an input sender and a
, and calls thestd :: invocable
on the signal sent by the input sender. The sender returned bystd :: invocable
sends the result of that invocation. In this case, the input sender came fromthen
, so itsschedule
, meaning it won’t send us a value, so ourvoid
takes no parameters. But we return anstd :: invocable
, which will be sent to the next recipient.int -
Now, we add another operation to the chain, again using § 4.12.2 execution::then. This time, we get sent a value - the
from the previous step. We addint
to it, and then return the result.42 -
Finally, we’re ready to submit the entire asynchronous pipeline and wait for its completion. Everything up until this point has been completely asynchronous; the work may not have even started yet. To ensure the work has started and then block pending its completion, we use § 4.13.2 std::this_thread::sync_wait, which will either return a
with the value sent by the last sender, or an emptystd :: optional < std :: tuple < ... >>
if the last sender sent a done signal, or it throws an exception if the last sender sent an error.std :: optional
1.3.2. Asynchronous inclusive scan
using namespace std :: execution ; sender auto async_inclusive_scan ( scheduler auto sch , // 2 std :: span < const double > input , // 1 std :: span < double > output , // 1 double init , // 1 std :: size_t tile_count ) // 3 { std :: size_t const tile_size = ( input . size () + tile_count - 1 ) / tile_count ; std :: vector < double > partials ( tile_count + 1 ); // 4 partials [ 0 ] = init ; // 4 return transfer_just ( sch , std :: move ( partials )) // 5 | bulk ( tile_count , // 6 [ = ]( std :: size_t i , std :: vector < double >& partials ) { // 7 auto start = i * tile_size ; // 8 auto end = std :: min ( input . size (), ( i + 1 ) * tile_size ); // 8 partials [ i + 1 ] = *-- std :: inclusive_scan ( begin ( input ) + start , // 9 begin ( input ) + end , // 9 begin ( output ) + start ); // 9 }) // 10 | then ( // 11 []( std :: vector < double >& partials ) { std :: inclusive_scan ( begin ( partials ), end ( partials ), // 12 begin ( partials )); // 12 return std :: move ( partials ); // 13 }) | bulk ( tile_count , // 14 [ = ]( std :: size_t i , std :: vector < double >& partials ) { // 14 auto start = i * tile_size ; // 14 auto end = std :: min ( input . size (), ( i + 1 ) * tile_size ); // 14 std :: for_each ( output + start , output + end , // 14 [ = ] ( double & e ) { e = partials [ i ] + e ; } // 14 ); }) | then ( // 15 [ = ]( std :: vector < double >& partials ) { // 15 return output ; // 15 }); // 15 }
This example builds an asynchronous computation of an inclusive scan:
-
It scans a sequence of
s (represented as thedouble std :: span < const double >
) and stores the result in another sequence ofinput
s (represented asdouble std :: span < double >
).output -
It takes a scheduler, which specifies what execution context the scan should be launched on.
-
It also takes a
parameter that controls the number of execution agents that will be spawned.tile_count -
First we need to allocate temporary storage needed for the algorithm, which we’ll do with a
,std :: vector
. We need onepartials
of temporary storage for each execution agent we create.double -
Next we’ll create our initial sender with § 4.11.3 execution::transfer_just. This sender will send the temporary storage, which we’ve moved into the sender. The sender has a completion scheduler of
, which means the next item in the chain will usesch
.sch -
Senders and sender adaptors support composition via
, similar to C++ ranges. We’ll useoperator |
to attach the next piece of work, which will spawnoperator |
execution agents using § 4.12.8 execution::bulk (see § 4.10 Most sender adaptors are pipeable for details).tile_count -
Each agent will call a
, passing it two arguments. The first is the agent’s index (std :: invocable
) in the § 4.12.8 execution::bulk operation, in this case a unique integer ini
. The second argument is what the input sender sent - the temporary storage.[ 0 , tile_count ) -
We start by computing the start and end of the range of input and output elements that this agent is responsible for, based on our agent index.
-
Then we do a sequential
over our elements. We store the scan result for our last element, which is the sum of all of our elements, in our temporary storagestd :: inclusive_scan
.partials -
After all computation in that initial § 4.12.8 execution::bulk pass has completed, every one of the spawned execution agents will have written the sum of its elements into its slot in
.partials -
Now we need to scan all of the values in
. We’ll do that with a single execution agent which will execute after the § 4.12.8 execution::bulk completes. We create that execution agent with § 4.12.2 execution::then.partials -
§ 4.12.2 execution::then takes an input sender and an
and calls thestd :: invocable
with the value sent by the input sender. Inside ourstd :: invocable
, we callstd :: invocable
onstd :: inclusive_scan
, which the input senders will send to us.partials -
Then we return
, which the next phase will need.partials -
Finally we do another § 4.12.8 execution::bulk of the same shape as before. In this § 4.12.8 execution::bulk, we will use the scanned values in
to integrate the sums from other tiles into our elements, completing the inclusive scan.partials -
returns a sender that sends the outputasync_inclusive_scan
. A consumer of the algorithm can chain additional work that uses the scan result. At the point at whichstd :: span < double >
returns, the computation may not have completed. In fact, it may not have even started.async_inclusive_scan
1.3.3. Asynchronous dynamically-sized read
using namespace std :: execution ; sender auto async_read ( sender auto buffer , auto handle ); // 1 struct dynamic_buffer { // 3 std :: unique_ptr < std :: byte [] > data ; // 3 std :: size_t size ; // 3 }; // 3 sender auto async_read_array ( auto handle ) { // 2 return just ( dynamic_buffer {}) // 4 | let_value ([] ( dynamic_buffer & buf ) { // 5 return just ( std :: as_writeable_bytes ( std :: span ( & buf . size , 1 )) // 6 | async_read ( handle ) // 7 | then ( // 8 [ & ] ( std :: size_t bytes_read ) { // 9 assert ( bytes_read == sizeof ( buf . size )); // 10 buf . data = std :: make_unique ( new std :: byte [ buf . size ]); // 11 return std :: span ( buf . data . get (), buf . size ); // 12 } | async_read ( handle ) // 13 | then ( [ & ] ( std :: size_t bytes_read ) { assert ( bytes_read == buf . size ); // 14 return std :: move ( buf ); // 15 } }); }
This example demonstrates a common asynchronous I/O pattern - reading a payload of a dynamic size by first reading the size, then reading the number of bytes specified by the size:
-
is a pipeable sender adaptor. It’s a customization point object, but this is what it’s call signature looks like. It takes a sender parameter which must send an input buffer in the form of aasync_read
, and a handle to an I/O context. It will asynchronously read into the input buffer, up to the size of thestd :: span < std :: byte >
. It returns a sender which will send the number of bytes read once the read completes.std :: span -
takes an I/O handle and reads a size from it, and then a buffer of that many bytes. It returns a sender that sends aasync_read_array
object that owns the data that was sent.dynamic_buffer -
is an aggregate struct that contains adynamic_buffer
and a size.std :: unique_ptr < std :: byte [] > -
The first thing we do inside of
is create a sender that will send a new, emptyasync_read_array
object using § 4.11.2 execution::just. We can attach more work to the pipeline usingdynamic_array
composition (see § 4.10 Most sender adaptors are pipeable for details).operator | -
We need the lifetime of this
object to last for the entire pipeline. So, we usedynamic_array
, which takes an input sender and alet_value
that must return a sender itself (see § 4.12.4 execution::let_* for details).std :: invocable
sends the value from the input sender to thelet_value
. Critically, the lifetime of the sent object will last until the sender returned by thestd :: invocable
completes.std :: invocable -
Inside of the
let_value
, we have the rest of our logic. First, we want to initiate anstd :: invocable
of the buffer size. To do that, we need to send aasync_read
pointing tostd :: span
. We can do that with § 4.11.2 execution::just.buf . size -
We chain the
onto the § 4.11.2 execution::just sender withasync_read
.operator | -
Next, we pipe a
that will be invoked after thestd :: invocable
completes using § 4.12.2 execution::then.async_read -
That
gets sent the number of bytes read.std :: invocable -
We need to check that the number of bytes read is what we expected.
-
Now that we have read the size of the data, we can allocate storage for it.
-
We return a
to the storage for the data from thestd :: span < std :: byte >
. This will be sent to the next recipient in the pipeline.std :: invocable -
And that recipient will be another
, which will read the data.async_read -
Once the data has been read, in another § 4.12.2 execution::then, we confirm that we read the right number of bytes.
-
Finally, we move out of and return our
object. It will get sent by the sender returned bydynamic_buffer
. We can attach more things to that sender to use the data in the buffer.async_read_array
1.4. What this proposal is not
This paper is not a patch on top of [P0443R14]; we are not asking to update the existing paper, we are asking to retire it in favor of this paper, which is already self-contained; any example code within this paper can be written in Standard C++, without the need to standardize any further facilities.
This paper is not an alternative design to [P0443R14]; rather, we have taken the design in the current executors paper, and applied targeted fixes to allow it to fulfill the promises of the sender/receiver model, as well as provide all the facilities we consider essential when writing user code using standard execution concepts; we have also applied the guidance of removing one-way executors from the paper entirely, and instead provided an algorithm based around senders that serves the same purpose.
1.5. Design changes from P0443
-
The
concept has been removed and all of its proposed functionality is now based on schedulers and senders, as per SG1 direction.executor -
Properties are not included in this paper. We see them as a possible future extension, if the committee gets more comfortable with them.
-
Users now have a choice between using a strictly lazy vs a possibly eager version of most sender algorithms.
-
Senders now advertise what scheduler, if any, their evaluation will complete on.
-
The places of execution of user code in P0443 weren’t precisely defined, whereas they are in this paper. See § 4.5 Senders can propagate completion schedulers.
-
P0443 did not propose a suite of sender algorithms necessary for writing sender code; this paper does. See § 4.11 User-facing sender factories, § 4.12 User-facing sender adaptors, and § 4.13 User-facing sender consumers.
-
P0443 did not specify the semantics of variously qualified
overloads; this paper does. See § 4.7 Senders can be either multi-shot or single-shot.connect -
Specific type erasure facilities are omitted, as per LEWG direction. Type erasure facilities can be built on top of this proposal, as discussed in § 5.9 Ranges-style CPOs vs tag_invoke.
-
A specific thread pool implementation is omitted, as per LEWG direction.
1.6. Prior art
This proposal builds upon and learns from years of prior art with asynchronous and parallel programming frameworks in C++.
Futures, as traditionally realized, require the dynamic allocation and management of a shared state, synchronization, and typically type-erasure of work and continuation. Many of these costs are inherent in the nature of "future" as a handle to work that is already scheduled for execution. These expenses rule out the future abstraction for many uses and makes it a poor choice for a basis of a generic mechanism.
Coroutines suffer many of the same problems, but can avoid synchronizing when chaining dependent work because they typically start suspended. In many cases, coroutine frames require unavoidable dynamic allocation. Consequently, coroutines in embedded or heterogeneous environments require great attention to detail. Nor are coroutines good candidates for cancellation because the early and safe termination of coroutines requires unsatisfying solutions. On the one hand, exceptions are inefficient and disallowed in many environments. Alternatively, clumsy ad-hoc mechanisms, whereby
returns a status code, hinder correctness. See [P1662R0] for a complete discussion.
Callbacks are the simplest, most powerful, and most efficient mechanism for creating chains of work, but suffer problems of their own. Callbacks must propagate either errors or values. This simple requirement yields many different interface possibilities, but the lack of a standard obstructs generic design. Additionally, few of these possibilities accommodate cancellation signals when the user requests upstream work to stop and clean up.
1.7. Field experience
This proposal draws heavily from our field experience with libunifex, Thrust, and Agency. It is also inspired by the needs of countless other C++ frameworks for asynchrony, parallelism, and concurrency, including:
Before this proposal is approved, we will present a new implementation of this proposal written from the specification and intended as a contribution to libc++. This implementation will demonstrate the viability of the design across the use cases and execution contexts that the committee has identified as essential.
2. Revision history
2.1. R0
Initial revision, still in progress.
3. Design - introduction
The following four sections describe the entirety of the proposed design.
-
§ 3 Design - introduction describes the conventions used through the rest of the design sections, as well as an example illustrating how we envision code will be written using this proposal.
-
§ 4 Design - user side describes all the functionality from the perspective we intend for users: it describes the various concepts they will interact with, and what their programming model is.
-
§ 5 Design - implementer side describes the machinery that allows for that programming model to function, and the information contained there is necessary for people implementing senders and sender algorithms (including the standard library ones) - but is not necessary to use senders productively.
3.1. Conventions
The following conventions are used throughout the design section:
-
The namespace proposed in this paper is the same as in [P0443R14]:
; however, for brevity, thestd :: execution
part of this name is omitted. When you seestd ::
, treat that asexecution :: foo
.std :: execution :: foo -
Universal references and explicit calls to
/std :: move
are omitted in code samples and signatures for simplicity; assume universal references and perfect forwarding unless stated otherwise.std :: forward -
None of the names proposed here are names that we are particularly attached to; consider the names to be reasonable placeholders that can freely be changed, should the committee want to do so.
3.2. Queries and algorithms
A query is a
that takes some set of objects (usually one) as parameters and returns facts about those objects without modifying them. Queries are usually customization point objects, but in some cases may be functions.
An algorithm is a
that takes some set of objects as parameters and causes those objects to do something. Algorithms are usually customization point objects, but in some cases may be functions.
4. Design - user side
4.1. Execution contexts describe the place of execution
An execution context is a resource that represents the place where execution will happen. This could be a concrete resource - like a specific thread pool object, or a GPU - or a more abstract one, like the current thread of execution. Execution contexts don’t need to have a representation in code; they are simply a term describing certain properties of execution of a function.
4.2. Schedulers represent execution contexts
A scheduler is a lightweight handle that represents a strategy for scheduling work onto an execution context. Since execution contexts don’t necessarily manifest in C++ code, it’s not possible to program
directly against their API. A scheduler is a solution to that problem: the scheduler concept is defined by a single sender algorithm,
, which returns a sender that will complete on an execution context determined
by the scheduler. Logic that you want to run on that context can be placed in the receiver’s completion-signalling method.
execution :: scheduler auto sch = get_thread_pool (). scheduler (); execution :: sender auto snd = execution :: schedule ( sch ); // snd is a sender (see below) describing the creation of a new execution resource // on the execution context associated with sch
Note that a particular scheduler type may provide other kinds of scheduling operations
which are supported by its associated execution context. It is not limited to scheduling
purely using the
API.
Future papers will propose additional scheduler concepts that extend
to add other capabilities. For example:
-
A
concept that extendstime_scheduler
to support time-based scheduling. Such a concept might provide access toscheduler
,schedule_after ( sched , duration )
andschedule_at ( sched , time_point )
APIs.now ( sched ) -
Concepts that extend
to support opening, reading and writing files asynchronously.scheduler -
Concepts that extend
to support connecting, sending data and receiving data over the network asynchronously.scheduler
4.3. Senders describe work
A sender is an object that describes work. Senders are similar to futures in existing asynchrony designs, but unlike futures, the work that is being done to arrive at the values they will send is also directly described by the sender object itself. A sender is said to send some values if a receiver connected (see § 5.3 execution::connect) to that sender will eventually receive said values.
The primary defining sender algorithm is § 5.3 execution::connect; this function, however, is not a user-facing API; it is used to facilitate communication between senders and various sender algorithms, but end user code is not expected to invoke it directly.
The way user code is expected to interact with senders is by using sender algorithms. This paper proposes an initial set of such sender algorithms, which are described in § 4.4 Senders are composable through sender algorithms, § 4.11 User-facing sender factories, § 4.12 User-facing sender adaptors, and § 4.13 User-facing sender consumers. For example, here is how a user can create a new sender on a scheduler, attach a continuation to it, and then wait for execution of the continuation to complete:
execution :: scheduler auto sch = get_thread_pool (). scheduler (); execution :: sender auto snd = execution :: schedule ( sch ); execution :: sender auto cont = execution :: then ( snd , []{ std :: fstream file { "result.txt" }; file << compute_result ; }); std :: this_thread :: sync_wait ( cont ); // at this point, cont has completed execution
4.4. Senders are composable through sender algorithms
Asynchronous programming often departs from traditional code structure and control flow that we are familiar with. A successful asynchronous framework must provide an intuitive story for composition of asynchronous work: expressing dependencies, passing objects, managing object lifetimes, etc.
The true power and utility of senders is in their composability. With senders, users can describe generic execution pipelines and graphs, and then run them on and across a variety of different schedulers. Senders are composed using sender algorithms:
-
sender factories, algorithms that take no senders and return a sender.
-
sender adaptors, algorithms that take (and potentially
) senders and return a sender.execution :: connect -
sender consumers, algorithms that take (and potentially
) senders and do not return a sender.execution :: connect
4.5. Senders can propagate completion schedulers
One of the goals of executors is to support a diverse set of execution contexts, including traditional thread pools, task and fiber frameworks (like HPX) and Legion), and GPUs and other accelerators (managed by runtimes such as CUDA or SYCL). On many of these systems, not all execution agents are created equal and not all functions can be run on all execution agents. Having precise control over the execution context used for any given function call being submitted is important on such systems, and the users of standard execution facilities will expect to be able to express such requirements.
[P0443R14] was not always clear about the place of execution of any given piece of code. Precise control was present in the two-way execution API present in earlier executor designs, but it has so far been missing from the senders design. There has been a proposal ([P1897R3]) to provide a number of sender algorithms that would enforce certain rules on the places of execution of the work described by a sender, but we have found those sender algorithms to be insufficient for achieving the best performance on all platforms that are of interest to us. The implementation strategies that we are aware of result in one of the following situations:
-
trying to submit work to one execution context (such as a CPU thread pool) from another execution context (such as a GPU or a task framework), which assumes that all execution agents are as capable as a
(which they aren’t).std :: thread -
forcibly interleaving two adjacent execution graph nodes that are both executing on one execution context (such as a GPU) with glue code that runs on another execution context (such as a CPU), which is prohibitively expensive for some execution contexts (such as CUDA or SYCL).
-
having to customise most or all sender algorithms to support an execution context, so that you can avoid problems described in 1. and 2, which we believe is impractical and brittle based on months of field experience attempting this in Agency.
None of these implementation strategies are acceptable for many classes of parallel runtimes, such as task frameworks (like HPX) or accelerator runtimes (like CUDA or SYCL).
Therefore, in addition to the
sender algorithm from [P1897R3], we are proposing a way for senders to advertise what scheduler (and by extension what execution context) they will complete on.
Any given sender may have completion schedulers for some or all of the signals (value, error, or done) it completes with (for more detail on the completion signals, see § 5.1 Receivers serve as glue between senders).
When further work is attached to that sender by invoking sender algorithms, that work will also complete on an appropriate completion scheduler.
4.5.1. execution :: get_completion_scheduler
is a query that retrieves the completion scheduler for a specific completion signal from a sender.
Calling
on a sender that does not have a completion scheduler for a given signal is ill-formed.
If a scheduler advertises a completion scheduler for a signal in this way, that sender must ensure that it sends that signal on an execution agent belonging to an execution context represented by a scheduler returned from this function.
See § 4.5 Senders can propagate completion schedulers for more details.
execution :: scheduler auto cpu_sched = new_thread_scheduler {}; execution :: scheduler auto gpu_sched = cuda :: scheduler (); execution :: sender auto snd0 = execution :: schedule ( cpu_sched ); execution :: scheduler auto completion_sch0 = execution :: get_completion_scheduler < execution :: set_value_t > ( snd0 ); // completion_sch0 is equivalent to cpu_sched execution :: sender auto snd1 = execution :: then ( snd0 , []{ std :: cout << "I am running on cpu_sched! \n " ; }); execution :: scheduler auto completion_sch1 = execution :: get_completion_scheduler < execution :: set_value_t > ( snd1 ); // completion_sch1 is equivalent to cpu_sched execution :: sender auto snd2 = execution :: transfer ( snd1 , gpu_sched ); execution :: sender auto snd3 = execution :: then ( snd2 , []{ std :: cout << "I am running on gpu_sched! \n " ; }); execution :: scheduler auto completion_sch3 = execution :: get_completion_scheduler < execution :: set_value_t > ( then3 ); // completion_sch3 is equivalent to cpu_sched
4.6. Execution context transitions are explicit
[P0443R14] does not contain any mechanisms for performing an execution context transition. The only sender algorithm that can create a sender that will move execution to a specific execution context is
, which does not take an input sender.
That means that there’s no way to construct sender chains that traverse different execution contexts. This is necessary to fulfill the promise of senders being able to replace two-way executors, which had this capability.
We propose that, for senders advertising their completion scheduler, all execution context transitions must be explicit; running user code anywhere but where they defined it to run must be considered a bug.
The
sender adaptor performs a transition from one execution context to another:
execution :: scheduler auto sch1 = ...; execution :: scheduler auto sch2 = ...; execution :: sender auto snd1 = execution :: schedule ( sch1 ); execution :: sender auto then1 = execution :: then ( snd1 , []{ std :: cout << "I am running on sch1! \n " ; }); execution :: sender auto snd2 = execution :: transfer ( then1 , sch2 ); execution :: sender auto then2 = execution :: then ( snd2 , []{ std :: cout << "I am running on sch2! \n " ; }); std :: this_thread :: sync_wait ( then2 );
4.7. Senders can be either multi-shot or single-shot
Some senders may only support launching their operation a single time, while others may be repeatable and support being launched multiple times. Executing the operation may consume resources owned by the sender.
For example, a sender may contain a
that it will be transferring ownership of to the
operation-state returned by a call to
so that the operation has access to
this resource. In such a sender, calling
consumes the sender such that after
the call the input sender is no longer valid. Such a sender will also typically be move-only so that
it can maintain unique ownership of that resource.
A single-shot sender can only be connected to a receiver at most once. Its implementation of
only has overloads for an rvalue-qualified sender. Callers must pass the sender
as an rvalue to the call to
, indicating that the call consumes the sender.
A multi-shot sender can be connected to multiple receivers and can be launched multiple
times. Mult-shot senders customise
to accept an lvalue reference to the
sender. Callers can indicate that they want the sender to remain valid after the call to
by passing an lvalue reference to the sender to call these overloads. Multi-shot senders should also define
overloads of
that accept rvalue-qualified enders to allow the sender to be also used in places
where only a single-shot sender is required.
If the user of a sender does not require the sender to remain valid after connecting it to a
receiver then it can pass an rvalue-reference to the sender to the call to
.
Such usages should be able to accept either single-shot or multi-shot senders.
If the caller does wish for the sender to remain valid after the call then it can pass an lvalue-qualified sender
to the call to
. Such usages will only accept multi-shot senders.
Algorithms that accept senders will typically either decay-copy an input sender and store it somewhere
for later usage (for example as a data-member of the returned sender) or will immediately call
on the input sender, such as in
or
.
Some multi-use sender algorithms may require that an input sender be copy-constructible but will only call
on an rvalue of each copy, which still results in effectively executing the operation multiple times.
Other multi-use sender algorithms may require that the sender is move-constructible but will invoke
on an lvalue reference to the sender.
For a sender to be usable in both multi-use scenarios, it will generally be required to be both copy-constructible and lvalue-connectable.
4.8. Senders are forkable
Any non-trivial program will eventually want to fork a chain of senders into independent streams of work, regardless of whether they are single-shot or multi-shot. For instance, an incoming event to a middleware system may be required to trigger events on more than one downstream system. This requires that we provide well defined mechanisms for making sure that connecting a sender multiple times is possible and correct.
The
sender adaptor facilitates connecting to a sender multiple times, regardless of whether it is single-shot or multi-shot:
auto some_algorithm ( execution :: sender auto && input ) { execution :: sender auto multi_shot = split ( input ); // "multi_shot" is guaranteed to be multi-shot, // regardless of whether "input" was multi-shot or not return when_all ( then ( multi_shot , [] { std :: cout << "First continuation \n " ; }), then ( multi_shot , [] { std :: cout << "Second continuation \n " ; }) ); }
4.9. Senders are joinable
Similarly to how it’s hard to write a complex program that will eventually want to fork sender chains into independent streams, it’s also hard to write a program that does not want to eventually create join nodes, where multiple independent streams of execution are merged into a single one in an asynchronous fashion.
is a sender adaptor that returns a sender that completes when the last of the input senders completes. It sends a pack of values, where the elements of said pack are the values sent by the input senders, in order.
returns a sender that also does not have an associated scheduler.
accepts an additional scheduler argument. It returns a sender whose value completion scheduler is the scheduler provided as an argument, but otherwise behaves the same as
. You can think of it as a composition of
, but one that allows for better efficiency through customization.
4.10. Most sender adaptors are pipeable
To facilitate an intuitive syntax for composition, most sender adaptors are pipeable; they can be composed (piped) together with
.
This mechanism is similar to the
composition that C++ range adaptors support and draws inspiration from piping in *nix shells.
Pipeable sender adaptors take a sender as their first parameter and have no other sender parameters.
will pass the sender
as the first argument to the pipeable sender adaptor
. Pipeable sender adaptors support partial application of the parameters after the first. For example, all of the following are equivalent:
execution :: bulk ( snd , N , [] ( std :: size_t i , auto d ) {}); execution :: bulk ( snd )( N , [] ( std :: size_t i , auto d ) {}); snd | execution :: bulk ( N , [] ( std :: size_t i , auto d ) {});
Piping enables you to compose together senders with a linear syntax. Without it, you’d have to use either nested function call syntax, which would cause a syntactic inversion of the direction of control flow, or you’d have to introduce a temporary variable for each stage of the pipeline. Consider the following example where we want to execute first on a CPU thread pool, then on a CUDA GPU, then back on the CPU thread pool:
Syntax Style | Example |
---|---|
Function call (nested) |
|
Function call (named temporaries) |
|
Pipe |
|
Certain sender adaptors are not be pipeable, because using the pipeline syntax can result in confusion of the semantics of the adaptors involved. Specifically, the following sender adaptors are not pipeable.
-
andexecution :: when_all
: Since this sender adaptor takes a variadic pack of senders, a partially applied form would be ambiguous with a non partially applied form with an arity of one less.execution :: when_all_with_variant -
andexecution :: on
: This sender adaptor changes how the sender passed to it is executed, not what happens to its result, but allowing it in a pipeline makes it read as if it performed a function more similar toexecution :: lazy_on
.transfer
Sender consumers could be made pipeable, but we have chosen to not do so. However, since these are terminal nodes in a pipeline and nothing can be piped after them, we believe a pipe syntax may be confusing as well as unnecessary, as consumers cannot be chained. We believe sender consumers read better with function call syntax.
4.11. User-facing sender factories
A sender factory is an algorithm that takes no senders as parameters and returns a sender.
4.11.1. execution :: schedule
execution :: sender auto schedule ( execution :: scheduler auto scheduler );
Returns a sender describing the start of a task graph on the provided scheduler. See § 4.2 Schedulers represent execution contexts.
execution :: scheduler auto sch1 = get_system_thread_pool (). scheduler (); execution :: sender auto snd1 = execution :: schedule ( sch1 ); // snd1 describes the creation of a new task on the system thread pool
4.11.2. execution :: just
execution :: sender auto just ( auto ... && values );
Returns a sender with no completion schedulers, which sends the provided values. If a provided value is an lvalue reference, a copy is made inside the returned sender and a non-const lvalue reference to the copy is sent. If the provided value is an rvalue reference, it is moved into the returned sender and an rvalue reference to it is sent.
execution :: sender auto snd1 = execution :: just ( 3.14 ); execution :: sender auto then1 = execution :: then ( snd1 , [] ( double d ) { std :: cout << d << " \n " ; }); execution :: sender auto snd2 = execution :: just ( 3.14 , 42 ); execution :: sender auto then2 = execution :: then ( snd1 , [] ( double d , int i ) { std :: cout << d << ", " << i << " \n " ; }); std :: vector v3 { 1 , 2 , 3 , 4 , 5 }; execution :: sender auto snd3 = execution :: just ( v3 ); execution :: sender auto then3 = execution :: then ( snd3 , [] ( std :: vector < int >& v3copy ) { for ( auto && e : v3copy ) { e *= 2 ; } return v3copy ; } auto && [ v3copy ] = std :: this_thread :: sync_wait ( then3 ). value (); // v3 contains {1, 2, 3, 4, 5}; v3copy will contain {2, 4, 6, 8, 10}. execution :: sender auto snd4 = execution :: just ( std :: vector { 1 , 2 , 3 , 4 , 5 }); execution :: sender auto then4 = execution :: then ( snd4 , [] ( std :: vector < int >&& v4 ) { for ( auto && e : v4 ) { e *= 2 ; } return std :: move ( v4 ); }); auto && [ v4 ] = std :: this_thread :: sync_wait ( then4 ). value (); // v4 contains {2, 4, 6, 8, 10}.
4.11.3. execution :: transfer_just
execution :: sender auto transfer_just ( execution :: scheduler auto scheduler , auto ... && values );
Returns a sender whose value completion scheduler is the provided scheduler, which sends the provided values in the same manner as
.
execution :: sender auto vals = execution :: transfer_just ( get_system_thread_pool (). scheduler (), 1 , 2 , 3 ); execution :: sender auto snd = execution :: then ( pred , []( auto ... args ) { std :: ( args ..); }); // when snd is executed, it will print "123"
This adaptor is included as it greatly simplifies lifting values into senders.
4.12. User-facing sender adaptors
A sender adaptor is an algorithm that takes one or more senders, which it may
, as parameters, and returns a sender, whose completion is related to the sender arguments it has received.
Many sender adaptors come in two versions: a strictly lazy one, which is never allowed to submit any work for execution prior to the returned sender being started later on, and a potentially eager one, which is allowed to submit work prior to the returned sender being started. Sender consumers such as § 4.12.12 execution::ensure_started, § 4.13.1 execution::start_detached, and § 4.13.2 std::this_thread::sync_wait start senders; the implementations of non-lazy versions of the sender adaptors are allowed, but not guaranteed, to start senders.
The strictly lazy versions of the adaptors below (that is, all the versions whose names start with
) are guaranteed to not start any input senders passed into them.
For more implementer-centric description of starting senders, see § 5.5 Laziness is defined by sender adaptors.
4.12.1. execution :: transfer
execution :: sender auto transfer ( execution :: sender auto input , execution :: scheduler auto scheduler ); execution :: sender auto lazy_transfer ( execution :: sender auto input , execution :: scheduler auto scheduler );
Returns a sender describing the transition from the execution agent of the input sender to the execution agent of the target scheduler. See § 4.6 Execution context transitions are explicit.
execution :: scheduler auto cpu_sched = get_system_thread_pool (). scheduler (); execution :: scheduler auto gpu_sched = cuda :: scheduler (); execution :: sender auto cpu_task = execution :: schedule ( cpu_sched ); // cpu_task describes the creation of a new task on the system thread pool execution :: sender auto gpu_task = execution :: transfer ( cpu_task , gpu_sched ); // gpu_task describes the transition of the task graph described by cpu_task to the gpu
4.12.2. execution :: then
execution :: sender auto then ( execution :: sender auto input , std :: invocable < values - sent - by ( input ) ... > function ); execution :: sender auto lazy_then ( execution :: sender auto input , std :: invocable < values - sent - by ( input ) ... > function );
returns a sender describing the task graph described by the input sender, with an added node of invoking the provided function with the values sent by the input sender as arguments.
is guaranteed to not begin executing
until the returned sender is started.
execution :: sender auto input = get_input (); execution :: sender auto snd = execution :: then ( input , []( auto ... args ) { std :: ( args ..); }); // snd describes the work described by pred // followed by printing all of the values sent by pred
This adaptor is included as it is necessary for writing any sender code that actually performs a useful function.
4.12.3. execution :: upon_ *
execution :: sender auto upon_error ( execution :: sender auto input , std :: invocable < errors - sent - by ( input ) ... > function ); execution :: sender auto lazy_upon_error ( execution :: sender auto input , std :: invocable < errors - sent - by ( input ) ... > function ); execution :: sender auto upon_error ( execution :: sender auto input , std :: invocable <> function ); execution :: sender auto lazy_upon_error ( execution :: sender auto input , std :: invocable <> function );
and
are similar to
, but where
works with values sent by the input sender,
works with errors, and
is invoked when the "done" signal is sent.
4.12.4. execution :: let_ *
execution :: sender auto let_value ( execution :: sender auto input , std :: invocable < values - sent - by ( input ) ... > function ); execution :: sender auto lazy_let_value ( execution :: sender auto input , std :: invocable < values - sent - by ( input ) ... > function ); execution :: sender auto let_error ( execution :: sender auto input , std :: invocable < errors - sent - by ( input ) ... > function ); execution :: sender auto lazy_let_error ( execution :: sender auto input , std :: invocable < errors - sent - by ( input ) ... > function ); execution :: sender auto let_error ( execution :: sender auto input , std :: invocable <> function ); execution :: sender auto lazy_let_error ( execution :: sender auto input , std :: invocable <> function );
is very similar to
: when it is started, it invokes the provided function with the values sent by the input sender as arguments. However, where the sender returned from
sends exactly what that function ends up returning -
requires that the function return a sender, and the sender returned by
sends the values sent by the sender returned from the callback. This is similar to the notion of "future unwrapping" in future/promise-based frameworks.
is guaranteed to not begin executing
until the returned sender is started.
and
are similar to
, but where
works with values sent by the input sender,
works with errors, and
is invoked when the "done" signal is sent.
4.12.5. execution :: on
execution :: sender auto on ( execution :: scheduler auto sched , execution :: sender auto snd ); execution :: sender auto lazy_on ( execution :: scheduler auto sched , execution :: sender auto snd );
Returns a sender which, when started, will start the provided sender on an execution agent belonging to the execution context associated with the provided scheduler. This returned sender has no completion schedulers.
4.12.6. execution :: into_variant
execution :: sender into_variant ( execution :: sender auto snd );
Returns a sender which sends a variant of tuples of all the possible sets of types sent by the input sender. Senders can send multiple sets of values depending on runtime conditions; this is a helper function that turns them into a single variant value.
4.12.7. execution :: unschedule
execution :: sender unschedule ( execution :: sender auto snd );
Returns a sender which sends values equivalent to values sent by the provided sender, but has no completion schedulers.
4.12.8. execution :: bulk
execution :: sender auto bulk ( execution :: sender auto input , std :: integral auto size , invocable < decltype ( size ), values - sent - by ( input ) ... > function ); execution :: sender auto lazy_bulk ( execution :: sender auto input , std :: integral auto size , invocable < decltype ( size ), values - sent - by ( input ) ... > function );
Returns a sender describing the task of invoking the provided function with the values sent by the input sender for every index in the provided shape.
In this paper, only integral types satisfy the concept of a shape, but future papers will explore bulk shapes of different kinds in more detail.
is guaranteed to not begin executing
until the returned sender is started.
4.12.9. execution :: split
execution :: sender auto split ( execution :: sender auto sender ); execution :: sender auto lazy_split ( execution :: sender auto sender );
If the provided sender is a multi-shot sender, returns that sender. Otherwise, returns a multi-shot sender which sends values equivalent to the values sent by the provided sender. See § 4.7 Senders can be either multi-shot or single-shot.
4.12.10. execution :: when_all
execution :: sender auto when_all ( execution :: sender auto ... inputs ); execution :: sender auto when_all_with_variant ( execution :: sender auto ... inputs );
returns a sender which completes once all of the input senders have completed. The values send by this sender are the values sent by each of the input, in order of the arguments passed to
.
does the same, but it adapts all the input senders using
.
The returned sender has no completion schedulers.
is a strictly lazy adaptor.
It is guaranteed to not start any of the input senders until the returned sender is started.
See § 4.9 Senders are joinable.
execution :: scheduler auto sched = get_thread_pool (). scheduler (); execution :: sender auto sends_1 = ...; execution :: sender auto sends_abc = ...; execution :: sender auto both = execution :: when_all ( sched , sends_1 , sends_abc ); execution :: sender auto final = execution :: then ( both , []( auto ... args ){ std :: cout << std :: format ( "the two args: {}, {}" , args ...); }); // when final executes, it will print "the two args: 1, abc"
4.12.11. execution :: transfer_when_all
execution :: sender auto transfer_when_all ( execution :: scheduler auto sched , execution :: sender auto ... inputs ); execution :: sender auto transfer_when_all_with_variant ( execution :: scheduler auto sched , execution :: sender auto ... inputs ); execution :: sender auto lazy_transfer_when_all ( execution :: scheduler auto sched , execution :: sender auto ... inputs ); execution :: sender auto lazy_transfer_when_all_with_variant ( execution :: scheduler auto sched , execution :: sender auto ... inputs );
Similar to § 4.12.10 execution::when_all, but returns a sender whose value completion scheduler is the provided scheduler.
See § 4.9 Senders are joinable.
4.12.12. execution :: ensure_started
execution :: sender auto ensure_started ( execution :: sender auto sender );
Once
returns, it is known that the provided sender has been connected and
has been called on the resulting operation state (see § 5.2 Operation states represent work); in other words, the work described by the provided sender has been submitted
for execution on the appropriate execution contexts. Returns a sender which completes when the provided sender completes and sends values equivalent to those of the provided sender.
4.13. User-facing sender consumers
A sender consumer is an algorithm that takes one or more senders, which it may
, as parameters, and does not return a sender.
4.13.1. execution :: start_detached
void auto start_detached ( execution :: sender auto sender );
Like
, but does not return a value; if the provided sender sends an error instead of a value,
is called.
4.13.2. std :: this_thread :: sync_wait
auto sync_wait ( execution :: sender auto sender ) requires ( always - sends - same - values ( sender )) -> std :: optional < std :: tuple < values - sent - by ( sender ) >> ;
is a sender consumer that submits the work described by the provided sender for execution, similarly to
, except that it blocks the current
or thread of
until the work is completed, and returns
an optional tuple of values that were sent by the provided sender on its completion of work. Where § 4.11.1 execution::schedule and § 4.11.3 execution::transfer_just are meant to enter the domain of senders,
is meant to exit the domain of
senders, retrieving the result of the task graph.
If the provided sender sends an error instead of values,
throws that error as an exception, or rethrows the original exception if the error is of type
.
If the provided sender sends the "done" signal instead of values,
returns an empty optional.
For an explanation of the
clause, see § 5.8 Most senders are typed. That clause also explains another sender consumer, built on top of
:
.
Note: Notice that this function is specified inside
, and not inside
. This is because
has to block the current execution agent, but determining what the current execution agent is is not reliable. Since the standard
does not specify any functions on the current execution agent other than those in
, this is the flavor of this function that is being proposed. If C++ ever obtains fibers, for instance, we expect that a variant of this function called
would be provided. We also expect that runtimes with execution agents that use different synchronization mechanisms than
's will provide their own flavors of
as well (assuming their execution agents have the means
to block in a non-deadlock manner).
4.14. execution :: execute
In addition to the three categories of functions presented above, we also propose to include a convenience function for fire-and-forget eager one-way submission of an invocable to a scheduler, to fulfil the role of one-way executors from P0443.
void execution :: execute ( execution :: schedule auto sched , std :: invocable auto fn );
Submits the provided function for execution on the provided scheduler, as-if by:
auto snd = execution :: schedule ( sched ); auto work = execution :: then ( snd , fn ); execution :: start_detached ( work );
5. Design - implementer side
5.1. Receivers serve as glue between senders
A receiver is a callback that supports more than one channel. In fact, it supports three of them:
-
, which is the moral equivalent of anset_value
or a function call, which signals successful completion of the operation its execution depends on;operator () -
, which signals that an error has happened during scheduling of the current work, executing the current work, or at some earlier point in the sender chain; andset_error -
, which signals that the operation completed without succeeding (set_done
) and without failing (set_value
). This result is often used to indicate that the operation stopped early, typically because it was asked to do so because the result is no longer needed.set_error
Exactly one of these channels must be successfully (i.e. without an exception being thrown) invoked on a receiver before it is destroyed; if a call to
failed with an exception, either
or
must be invoked on the same receiver. These
requirements are know as the receiver contract.
While the receiver interface may look novel, it is in fact very similar to the interface of
, which provides the first two signals as
and
, and it’s possible to emulate the third channel with lifetime management of the promise.
Receivers are not a part of the end-user-facing API of this proposal; they are necessary to allow unrelated senders communicate with each other, but the only users who will interact with receivers directly are authors of senders.
Receivers are what is passed as the second argument to § 5.3 execution::connect.
5.2. Operation states represent work
An operation state is an object that represents work. Unlike senders, it is not a chaining mechanism; instead, it is a concrete object that packages the work described by a full sender chain, ready to be executed. An operation state is neither movable nor
copyable, and its interface consists of a single algorithm:
, which serves as the submission point of the work represented by a given operation state.
Operation states are not a part of the user-facing API of this proposal; they are necessary for implementing sender consumers like
and
, and the knowledge of them is necessary to implement senders, so the only users who will
interact with operation states directly are authors of senders and authors of sender algorithms.
The return value of § 5.3 execution::connect must satisfy the operation state concept.
5.3. execution :: connect
is a customization point which connects senders with receivers, resulting in an operation state that will ensure that the receiver contract of the receiver passed to
will be fulfilled.
execution :: sender auto snd = some input sender ; execution :: receiver auto rcv = some receiver ; execution :: operation_state auto state = execution :: connect ( snd , rcv ); execution :: start ( state ); // at this point, it is guaranteed that the work represented by state has been submitted // to an execution context, and that execution context will eventually fulfill the // receiver contract of rcv // operation states are not movable, and therefore this operation state object must be // kept alive until the operation finishes
5.4. Sender algorithms are customizable
Senders being able to advertise what their completion schedulers are fulfills one of the promises of senders: that of being able to customize an implementation of a sender algorithm based on what scheduler any work it depends on will complete on.
The simple way to provide customizations for functions like
, that is for sender adaptors and sender consumers, is to follow the customization scheme that has been adopted for C++20 ranges library; to do that, we would define
the expression
to be equivalent to:
-
, if that expression is well formed; otherwisesender . then ( invocable ) -
, performed in a context where this call always performs ADL, if that expression is well formed; otherwisethen ( sender , invocable ) -
a default implementation of
, which returns a sender adaptor, and then define the exact semantics of said adaptor.then
However, this definition is problematic. Imagine another sender adaptor,
, which is a structured abstraction for a loop over an index space. Its default implementation is just a for loop. However, for accelerator runtimes like CUDA, we would like sender algorithms
like
to have specialized behavior, which invokes a kernel of more than one thread (with its size defined by the call to
); therefore, we would like to customize
for CUDA senders to achieve this. However, there’s no reason for CUDA kernels to
necessarily customize the
sender adaptor, as the generic implementation is perfectly sufficient. This creates a problem, though; consider the following snippet:
execution :: scheduler auto cuda_sch = cuda_scheduler {}; execution :: sender auto initial = execution :: schedule ( cuda_sch ); // the type of initial is a type defined by the cuda_scheduler // let’s call it cuda::schedule_sender<> execution :: sender auto next = execution :: then ( cuda_sch , []{ return 1 ; }); // the type of next is a standard-library implementation-defined sender adaptor // that wraps the cuda sender // let’s call it execution::then_sender_adaptor<cuda::schedule_sender<>> execution :: sender auto kernel_sender = execution :: bulk ( next , shape , []( int i ){ ... });
How can we specialize the
sender adaptor for our wrapped
? Well, here’s one possible approach, taking advantage of ADL (and the fact that the definition of "associated namespace" also recursively enumerates the associated namespaces of all template
parameters of a type):
namespace cuda :: for_adl_purposes { template < typename ... SentValues > class schedule_sender { execution :: operation_state auto connect ( execution :: receiver auto rcv ); execution :: scheduler auto get_completion_scheduler () const ; }; execution :: sender auto bulk ( execution :: sender auto && input , execution :: shape auto && shape , invocable < sender - values ( input ) > auto && fn ) { // return a cuda sender representing a bulk kernel launch } } // namespace cuda::for_adl_purposes
However, if the input sender is not just a
like in the example above, but another sender that overrides
by itself, as a member function, because its author believes they know an optimization for bulk - the specialization above will no
longer be selected, because a member function of the first argument is a better match than the ADL-found overload.
This means that well-meant specialization of sender algorithms that are entirely scheduler-agnostic can have negative consequences. The scheduler-specific specialization - which is essential for good performance on platforms providing specialized ways to launch certain sender algorithms - would not be selected in such cases. But it’s really the scheduler that should control the behavior of sender algorithms when a non-default implementation exists, not the sender. Senders merely describe work; schedulers, however, are the handle to the runtime that will eventually execute said work, and should thus have the final say in how the work is going to be executed.
Therefore, we are proposing the following customization scheme (also modified to take § 5.9 Ranges-style CPOs vs tag_invoke into account): the expression
, for any given sender algorithm that accepts a sender as its first argument, should be
equivalent to:
-
, if that expression is well-formed; otherwisetag_invoke ( < sender - algorithm > , get_completion_scheduler < Signal > ( sender ), sender , args ...) -
, if that expression is well-formed; otherwisetag_invoke ( < sender - algorithm > , sender , args ...) -
a default implementation, if there exists a default implementation of the given sender algorithm.
where
is one of
,
, or
; for most sender algorithms, the completion scheduler for
would be used, but for some (like
or
), one of the others would be used.
For sender algorithms which accept concepts other than
as their first argument, we propose that the customization scheme remains as it has been in [P0443R14] so far, except it should also use
.
5.5. Laziness is defined by sender adaptors
We distinguish two different guarantees about when work is submitted to an execution context:
-
strictly lazy submission, which means that there is a guarantee that no work is submitted to an execution context before a receiver is connected to a sender, and
is called on the resulting operation state;execution :: start -
potentially eager submission, which means that work may be submitted to an execution context as soon as all the information necessary to perform it is provided.
If a sender adaptor requires potentially eager submission, strictly lazy submission is acceptable as an implementation, because it does fulfill the potentially eager guarantee. This is why the default implementations for the non-strictly-lazy sender adaptors are specified to dispatch to the strictly lazy ones; for an author of a specific sender, it is sufficient to specialize the strictly lazy version, to also achieve a specialization of the potentially eager one.
As has been described in § 4.12 User-facing sender adaptors, whether a sender adaptor is guaranteed to perform strictly lazy submission or not is defined by the adaptor used to perform it; the adaptors whose names begin with
provide the strictly lazy guarantee.
5.6. Lazy senders provide optimization opportunities
Because lazy senders fundamentally describe work, instead of describing or representing the submission of said work to an execution context, and thanks to the flexibility of the customization of most sender algorithms, they provide an opportunity for fusing multiple algorithms in a sender chain together, into a single function that can later be submitted for execution by an execution context. There are two ways this can happen.
The first (and most common) way for such optimizations to happen is thanks to the structure of the implementation: because all the work is done within callbacks invoked on the completion of an earlier sender, recursively up to the original source of computation, the compiler is able to see a chain of work described using senders as a tree of tail calls, allowing for inlining and removal of most of the sender machinery. In fact, when work is not submitted to execution contexts outside of the current thread of execution, compilers are capable of removing the senders abstraction entirely, while still allowing for composition of functions across different parts of a program.
The second way for this to occur is when a sender algorithm is specialized for a specific set of arguments. For instance, we expect that, for senders which are known to have been started already, § 4.12.12 execution::ensure_started will be an identity transformation, because the sender algorithm will be specialized for such senders. Similarly, an implementation could recognize two subsequent lazy § 4.12.8 execution::bulks of compatible shapes, and merge them together into a single submission of a GPU kernel.
5.7. Execution context transitions are two-step
Because
takes a sender as its first argument, it is not actually directly customizable by the target scheduler. This is by design: the target scheduler may not know how to transition from a scheduler such as a CUDA scheduler;
transitioning away from a GPU in an efficient manner requires making runtime calls that are specific to the GPU in question, and the same is usually true for other kinds of accelerators too (or for scheduler running on remote systems). To avoid this problem,
specialized schedulers like the ones mentioned here can still hook into the transition mechanism, and inject a sender which will perform a transition to the regular CPU execution context, so that any sender can be attached to it.
This, however, is a problem: because customization of sender algorithms must be controlled by the scheduler they will run on (see § 5.4 Sender algorithms are customizable), the type of the sender returned from
must be controllable by the target scheduler. Besides, the target
scheduler may itself represent a specialized execution context, which requires additional work to be performed to transition to it. GPUs and remote node schedulers are once again good examples of such schedulers: executing code on their execution contexts
requires making runtime API calls for work submission, and quite possibly for the data movement of the values being sent by the input sender passed into
.
To allow for such customization from both ends, we propose the inclusion of a secondary transitioning sender adaptor, called
. This adaptor is a form of
, but takes an additional, second argument: the input sender. This adaptor is not
meant to be invoked manually by the end users; they are always supposed to invoke
, to ensure that both schedulers have a say in how the transitions are made. Any scheduler that specializes
shall ensure that the
return value of their customization is equivalent to
, where
is a successor of
that sends values equivalent to those sent by
.
The default implementation of
is
.
5.8. Most senders are typed
All senders should advertise the types they will send when they complete. This is necessary for a number of features, and writing code in a way that’s agnostic of whether an imput sender is typed or not in common sender adaptors such as
is
hard.
The mechanism for this advertisement is the same as in [P0443R14]; the way to query the types is through
.
is a template that takes two arguments: one is a tuple-like template, the other is a variant-like template. The tuple-like argument is required to represent senders sending more than one value (such as
). The variant-like
argument is required to represent senders that choose which specific values to send at runtime.
There’s a choice made in the specification of § 4.13.2 std::this_thread::sync_wait: it returns a tuple of values sent by the sender passed to it, wrapped in
to handle the
signal. However, this assumes that those values can be represented as a
tuple, like here:
execution :: sender auto sends_1 = ...; execution :: sender auto sends_2 = ...; execution :: sender auto sends_3 = ...; auto [ a , b , c ] = std :: this_thread :: sync_wait ( execution :: transfer_when_all ( execution :: get_completion_scheduler < execution :: set_value_t > ( sends_1 ), sends_1 , sends_2 , sends_3 )). value (); // a == 1 // b == 2 // c == 3
This works well for senders that always send the same set of arguments. If we ignore the possibility of having a sender that sends different sets of arguments into a receiver, we can specify the "canonical" (i.e. required to be followed by all senders) form of
of a sender which sends
to be as follows:
template < template < typename ... > typename TupleLike > using value_types = TupleLike ;
If senders could only ever send one specific set of values, this would probably need to be the required form of
for all senders; defining it otherwise would cause very weird results and should be considered a bug.
This matter is somewhat complicated by the fact that (1)
for receivers can be overloaded and accept different sets of arguments, and (2) senders are allowed to send multiple different sets of values, depending on runtime conditions, the data they
consumed, and so on. To accomodate this, [P0443R14] also includes a second template parameter to
, one that represents a variant-like type. If we permit such senders, we would almost certainly need to require that the canonical form of
for all senders (to ensure consistency in how they are handled, and to avoid accidentally interpreting a user-provided variant as a sender-provided one) sending the different sets of arguments
,
, ...,
to be as follows:
template < template < typename ... > typename TupleLike , template < typename ... > typename VariantLike > using value_types = VariantLike < TupleLike < Types1 ... > , TupleLike < Types2 ... > , ..., TupleLike < Types3 ... > > ;
This, however, introduces a couple of complications:
-
A
sender would also need to follow this structure, so the correct type for storing the value sent by it would bejust ( 1 )
or some such. This introduces a lot of compile time overhead for the simplest senders, and this overhead effectively exists in all places in the code wherestd :: variant < std :: tuple < int >>
is queried, regardless of the tuple-like and variant-like templates passed to it. Such overhead does exist if only the tuple-like parameter exists, but is made much worse by adding this second wrapping layer.value_types -
As a consequence of (1): because
needs to store the above type, it can no longer return just async_wait
forstd :: tuple < int >
; it has to returnjust ( 1 )
. C++ currently does not have an easy way to destructure this; it may get less awkward with pattern matching, but even then it seems extremely heavyweight to involve variants in this API, and for the purpose of generic code, the kind of the return type ofstd :: variant < std :: tuple < int >>
must be the same across all sender types.sync_wait
One possible solution to (2) above is to place a requirement on
that it can only accept senders which send only a single set of values, therefore removing the need for
to appear in its API; because of this, we propose to expose both
, which is a simple, user-friendly version of the sender consumer, but requires that
have only one possible variant, and
, which accepts any sender, but returns an optional whose value type is the variant of all the
possible tuples sent by the input sender:
auto sync_wait_with_variant ( execution :: sender auto sender ) -> std :: optional < std :: variant < std :: tuple < values 0 - sent - by ( sender ) > , std :: tuple < values 1 - sent - by ( sender ) > , ..., std :: tuple < values n - sent - by ( sender ) > >> ; auto sync_wait ( execution :: sender auto sender ) requires ( always - sends - same - values ( sender )) -> std :: optional < std :: tuple < values - sent - by ( sender ) >> ;
5.9. Ranges-style CPOs vs tag_invoke
The contemporary technique for customization in the Standard Library is customization point objects. A customization point object, will it look for member functions and then for nonmember functions with the same name as the customization point, and calls those if they match. This is the technique used by the C++20 ranges library, and previous executors proposals ([P0443R14] and [P1897R3]) intended to use it as well. However, it has several unfortunate consequences:
-
It does not allow for easy propagation of customization points unknown to the adaptor to a wrapped object, which makes writing universal adapter types much harder - and this proposal uses quite a lot of those.
-
It effectively reserves names globally. Because neither member names nor ADL-found functions can be qualified with a namespace, every customization point object that uses the ranges scheme reserves the name for all types in all namespaces. This is unfortunate due to the sheer number of customization points already in the paper, but also ones that we are envisioning in the future. It’s also a big problem for one of the operations being proposed already:
. We imagine that if, in the future, C++ was to gain fibers support, we would want to also havesync_wait
, in addition tostd :: this_fiber :: sync_wait
. However, because we would want the names to be the same in both cases, we would need to make the names of the customizations not match the names of the customization points. This is undesirable.std :: this_thread :: sync_wait
This paper proposes to instead use the mechanism described in [P1895R0]:
; the wording for
has been incorporated into the proposed specification in this paper.
In short, instead of using globally reserved names,
uses the type of the customization point object itself as the mechanism to find customizations. It globally reserves only a single name -
- which itself is used the same way that
ranges-style customization points are used. All other customization points are defined in terms of
. For example, the customization for
will call
, instead of attempting
to call
, and then
if the member call is not valid.
Using
has the following benefits:
-
It reserves only a single global name, instead of reserving a global name for every customization point object we define.
-
It is possible to propagate customizations to a subobject, because the information of which customization point is being resolved is in the type of an argument, and not in the name of the function:
// forward most customizations to a subobject template < typename Tag , typename ... Args > friend auto tag_invoke ( Tag && tag , wrapper & self , Args && ... args ) { return std :: forward < Tag > ( tag )( self . subobject , std :: forward < Args > ( args )...); } // but override one of them with a specific value friend auto tag_invoke ( specific_customization_point_t , wrapper & self ) { return self . some_value ; } -
It is possible to pass those as template arguments to types, because the information of which customization point is being resolved is in the type. Similarly to how [P0443R14] defines a polymorphic executor wrapper which accepts a list of properties it supports, we can imagine scheduler and sender wrappers that accept a list of queries and operations they support. That list can contain the types of the customization point objects, and the polymorphic wrappers can then specialize those customization points on themselves using
, dispatching to manually constructed vtables containing pointers to specialized implementations for the wrapped objects. For an example of such a polymorphic wrapper, seetag_invoke
(example).unifex :: any_unique
6. Specification
Much of this wording follows the wording of [P0443R14].
§ 7 General utilities library [utilities] is meant to be a diff relative to the wording of the [utilities] clause of [N4885]. This diff applies changes from [P1895R0].
§ 8 Thread support library [thread] is meant to be a diff relative to the wording of the [thread] clause of [N4885]. This diff applies changes from [P2175R0].
§ 9 Execution control library [execution] is meant to be added as a new library clause to the working draft of C++.
7. General utilities library [utilities]
7.1. Function objects [function.objects]
7.1.1. Header < functional >
synopsis [functional.syn]
At the end of this subclause, insert the following declarations into the synopsis within
:
// [func.tag_invoke], tag_invoke inline namespace unspecified { inline constexpr unspecified tag_invoke = unspecified ; } template < auto & Tag > using tag_t = decay_t < decltype ( Tag ) > ; template < class Tag , class ... Args > concept tag_invocable = invocable < decltype ( tag_invoke ), Tag , Args ... > ; template < class Tag , class ... Args > concept nothrow_tag_invocable = tag_invocable < Tag , Args ... > && is_nothrow_invocable_v < decltype ( tag_invoke ), Tag , Args ... > ; template < class Tag , class ... Args > using tag_invoke_result = invoke_result < decltype ( tag_invoke ), Tag , Args ... > ; template < class Tag , class ... Args > using tag_invoke_result_t = invoke_result_t < decltype ( tag_invoke ), Tag , Args ... > ;
7.1.2. Tag_invoke [func.tag_invoke]
Insert this section as a new subclause, between Searchers [func.search] and Class template
[unord.hash].
The name
denotes a customization point object. For some subexpressions
std :: tag_invoke and
tag ,
args ... is expression-equivalent to an unqualified call to
tag_invoke ( tag , args ...) with overload resolution performed in a context that includes the declaration:
tag_invoke ( decay - copy ( tag ), args ...) void tag_invoke (); and that does not include the the
name.
std :: tag_invoke
8. Thread support library [thread]
Note: The specification in this section is incomplete; it does not provide an API specification for the new types added into
. For a less formal specification of the missing pieces, see the "Proposed Changes" section of [P2175R0]. A future revision
of this paper will contain a full specification for the new types.
8.1. Stop tokens [thread.stoptoken]
8.1.1. Header < stop_token >
synopsis [thread.stoptoken.syn]
At the beginning of this subclause, insert the following declarations into the synopsis within
:
template < template < typename > class > struct < i > check - type - alias - exists </ i > ; // exposition-only template < typename T > concept stoppable_token = < i > see - below </ i > ; template < typename T , typename CB , typename Initializer = CB > concept stoppable_token_for = < i > see - below </ i > ; template < typename T > concept unstoppable_token = < i > see - below </ i > ;
At the end of this subclause, insert the following declarations into the synopsis of within
:
// [stoptoken.never], class never_stop_token class never_stop_token ; // [stoptoken.inplace], class in_place_stop_token class in_place_stop_token ; // [stopsource.inplace], class in_place_stop_source class in_place_stop_source ; // [stopcallback.inplace], class template in_place_stop_callback template < typename Callback > class in_place_stop_callback ;
8.1.2. Stop token concepts [thread.stoptoken.concepts]
Insert this section as a new subclause between Header
synopsis [thread.stoptoken.syn] and Class
[stoptoken].
The
concept checks for the basic interface of a “stop token” which is copyable and allows polling to see if stop has been requested and also whether a stop request is possible. It also requires an associated nested template-type-alias,
stoppable_token , that identifies the stop-callback type to use to register a callback to be executed if a stop-request is ever made on a stoppable_token of type,
T :: callback_type < CB > . The
T concept checks for a stop token type compatible with a given callback type. The
stoppable_token_for concept checks for a stop token type that does not allow stopping.
unstoppable_token template < typename T > concept stoppable_token = copy_constructible < T > && move_constructible < T > && is_nothrow_copy_constructible_v < T > && is_nothrow_move_constructible_v < T > && equality_comparable < T > && requires ( const T & token ) { { token . stop_requested () } noexcept -> boolean - testable ; { token . stop_possible () } noexcept -> boolean - testable ; typename __check_type_alias_exists < T :: template callback_type > ; }; template < typename T , typename CB , typename Initializer = CB > concept stoppable_token_for = stoppable_token < T > && invocable < CB > && requires { typename T :: template callback_type < CB > ; } && constructible_from < CB , Initializer > && constructible_from < typename T :: template callback_type < CB > , T , Initializer > && constructible_from < typename T :: template callback_type < CB > , T & , Initializer > && constructible_from < typename T :: template callback_type < CB > , const T , Initializer > && constructible_from < typename T :: template callback_type < CB > , const T & , Initializer > ; template < typename T > concept unstoppable_token = stoppable_token < T > && requires { { T :: stop_possible () } -> boolean - testable ; } && ( ! T :: stop_possible ());
Let
and
t be distinct object of type
u . The type
T models
T only if:
stoppable_token
All copies of a
reference the same logical shared stop state and shall report values consistent with each other.
stoppable_token If
evaluates to
t . stop_possible () false
then, if, references the same logical shared stop state,
u shall also subsequently evaluate to
u . stop_possible () false
andshall also subsequently evaluate to
u . stop_requested () false
.If
evaluates to
t . stop_requested () true
then, if, references the same logical shared stop state,
u shall also subsequently evaluate to
u . stop_requested () true
andshall also subsequently evaluate to
u . stop_possible () true
.Given a callback-type, CB, and a callback-initializer argument,
, of type
init then constructing an instance,
Initializer , of type
cb , passing
T :: callback_type < CB > as the first argument and
t as the second argument to the constructor, shall, if
init is
t . stop_possible () true
, construct an instance,, of type
callback , direct-initialized with
CB , and register callback with
init ’s shared stop state such that callback will be invoked with an empty argument list if a stop request is made on the shared stop state.
t
If
is
t . stop_requested () true
at the time callback is registered then callback may be invoked immediately inline inside the call to’s constructor.
cb If callback is invoked then, if
references the same shared stop state as
u , an evaluation of
t will be
u . stop_requested () true
if the beginning of the invocation of callback strongly-happens-before the evaluation of.
u . stop_requested () If
evaluates to
t . stop_possible () false
then the construction ofis not required to construct and initialize
cb .
callback Construction of a
instance shall only throw exceptions thrown by the initialization of the
T :: callback_type < CB > instance from the value of type
CB .
Initializer Destruction of the
object,
T :: callback_type < CB > , deregisters callback from the shared stop state such that
cb will not be invoked after the destructor returns.
callback
If
is currently being invoked on another thread then the destructor of
callback will block until the invocation of
cb returns such that the return from the invocation of
callback strongly-happens-before the destruction of
callback .
callback Destruction of a callback
shall not block on the completion of the invocation of some other callback registered with the same shared stop state.
cb
9. Execution control library [execution]
-
This Clause describes components supporting execution of function objects [function.objects].
-
The following subclauses describe the requirements, concepts, and components for execution control primitives as summarized in Table 1.
Subclause | Header | |
[execution.execute] | One-way execution |
9.1. Header < execution >
synopsis [execution.syn]
namespace std :: execution { // [execution.helpers], helper concepts template < class T > concept moveable - value = see - below ; // exposition only // [execution.scheduler], schedulers template < class S > concept scheduler = see - below ; // [execution.receiver], receivers template < class T , class E = exception_ptr > concept receiver = see - below ; template < class T , class ... An > concept receiver_of = see - below ; inline namespace unspecified { struct set_value_t ; inline constexpr set_value_t set_value {}; struct set_error_t ; inline constexpr set_error_t set_error {}; struct set_done_t ; inline constexpr set_done_t set_done {}; } // [execution.receiver.queries], receiver queries inline namespace unspecified { struct get_scheduler_t ; inline constexpr get_scheduler_t get_scheduler {}; struct get_allocator_t ; inline constexpr get_allocator_t get_allocator {}; struct get_stop_token_t ; inline constesxpr get_stop_token_t get_stop_token {}; } // [execution.op_state], operation states template < class O > concept operation_state = see - below ; inline namespace unspecified { struct start_t ; inline constexpr start_t start {}; } // [execution.sender], senders template < class S > concept sender = see - below ; template < class S , class R > concept sender_to = see - below ; template < class S > concept has - sender - types = see - below ; // exposition only template < class S > concept typed_sender = see - below ; // [execution.sender.traits], sender traits inline namespace unspecified { struct sender_base {}; } template < class S > struct sender_traits ; inline namespace unspecified { // [execution.sender.connect], the connect sender algorithm struct connect_t ; inline constexpr connect_t connect {}; // [execution.sender.queries], sender queries template < class CPO > struct get_completion_scheduler_t ; template < class CPO > inline constexpr get_completion_scheduler_t get_completion_scheduler {}; // [execution.sender.factories], sender factories struct schedule_t ; inline constexpr schedule_t schedule {}; template < class ... Ts > struct just - sender ; // exposition only template < moveable - value ... Ts > just - sender < remove_cvref_t < Ts > ... > just ( Ts && ...); struct transfer_just_t ; inline constexpr transfer_just_t transfer_just {}; // [execution.sender.adaptors], sender adaptors struct on_t ; inline constexpr on_t on {}; struct lazy_on_t ; inline constexpr lazy_on_t lazy_on {}; struct transfer_t ; inline constexpr transfer_t transfer {}; struct lazy_transfer_t ; inline constexpr lazy_transfer_t lazy_transfer {}; struct schedule_from_t ; inline constexpr schedule_from_t schedule_from {}; struct lazy_schedule_from_t ; inline constexpr lazy_schedule_from_t lazy_schedule_from {}; struct then_t ; inline constexpr then_t then {}; struct lazy_then_t ; inline constexpr lazy_then_t lazy_then {}; struct upon_error_t ; inline constexpr upon_error_t upon_error {}; struct lazy_upon_error_t ; inline constexpr lazy_upon_error_t lazy_upon_error {}; struct upon_done_t ; inline constexpr upon_done_t upon_done {}; struct lazy_upon_done_t ; inline constexpr lazy_upon_done_t lazy_upon_done {}; struct let_value_t ; inline constexpr let_value_t let_value {}; struct lazy_let_value_t ; inline constexpr lazy_let_value_t lazy_let_value {}; struct let_error_t ; inline constexpr let_error_t let_error {}; struct lazy_let_error_t ; inline constexpr lazy_let_error_t lazy_let_error {}; struct let_done_t ; inline constexpr let_done_t let_done {}; struct lazy_let_done_t ; inline constexpr lazy_let_done_t lazy_let_done {}; struct bulk_t ; inline constexpr bulk_t bulk {}; struct lazy_bulk_t ; inline constexpr lazy_bulk_t lazy_bulk {}; struct split_t ; inline constexpr split_t split {}; struct lazy_split_t ; inline constexpr lazy_split_t lazy_split {}; struct when_all_t ; inline constexpr when_all_t when_all {}; struct when_all_with_variant_t ; inline constexpr when_all_with_variant_t when_all_with_variant {}; struct transfer_when_all_t ; inline constexpr transfer_when_all_t transfer_when_all {}; struct lazy_transfer_when_all_t ; inline constexpr lazy_transfer_when_all_t lazy_transfer_when_all {}; struct transfer_when_all_with_variant_t ; inline constexpr transfer_when_all_with_variant_t transfer_when_all_with_variant {}; struct lazy_transfer_when_all_with_variant_t ; inline constexpr lazy_transfer_when_all_with_variant_t lazy_transfer_when_all_with_variant {}; template < typed_sender S > using into - variant - type = see - below ; // exposition-only template < typed_sender S > see - below into_variant ( S && ); template < sender S > see - below unschedule ( S && ); // [execution.sender.consumers], sender consumers struct ensure_started_t ; inline constexpr ensure_started_t ensure_started {}; struct start_detached_t ; inline constexpr start_detached_t start_detached {}; } } namespace std :: this_thread { inline namespace unspecified { template < typed_sender S > using sync - wait - type = see - below ; // exposition-only template < typed_sender S > using sync - wait - with - variant - type = see - below ; // exposition-only struct sync_wait_t ; inline constexpr sync_wait_t sync_wait {}; struct sync_wait_with_variant_t ; inline constexpr sync_wait_with_variant_t sync_wait_with_variant {}; } } namespace std :: execution { inline namespace unspecified { // [execution.execute], one-way execution struct execute_t ; inline constexpr execute_t execute {}; } }
9.2. Helper concepts [execution.helpers]
template < class T > concept moveable - value = // exposition only move_constructible < remove_cvref_t < T >> && constructible_from < remove_cvref_t < T > , T > ;
9.3. Schedulers [execution.scheduler]
-
The
concept defines the requirements of a type that allows for scheduling of work on its associated execution context.scheduler template < class S > concept scheduler = copy_constructible < remove_cvref_t < S >> && equality_comparable < remove_cvref_t < S >> && requires ( S && s ) { execution :: schedule (( S && ) s ); }; -
None of a scheduler’s copy constructor, destructor, equality comparison, or
member functions shall exit via an exception.swap -
None of these member functions, nor a scheduler type’s
function, shall introduce data races as a result of concurrent invocations of those functions from different threads.schedule -
For any two (possibly const) values
ands1
of some scheduler types2
,S
shall returns1 == s2 true
only if both
ands1
are handles to the same associated execution context.s2 -
A scheduler type’s destructor shall not block pending completion of any receivers connected to the sender objects returned from
. [Note: The ability to wait for completion of submitted function objects may be provided by the associated execution context of the scheduler. —end note]schedule
9.4. Receivers [execution.receiver]
-
A receiver represents the continuation of an asynchronous operation. An asynchronous operation may complete with a (possibly empty) set of values, an error, or it may be cancelled. A receiver has three principal operations corresponding to the three ways an asynchronous operation may complete:
,set_value
, andset_error
. These are collectively known as a receiver’s completion-signal operations.set_done -
The
concept defines the requirements for a receiver type with an unknown set of value types. Thereceiver
concept defines the requirements for a receiver type with a known set of value types, whose error type isreceiver_of
.std :: exception_ptr template < class T , class E = exception_ptr > concept receiver = move_constructible < remove_cvref_t < T >> && constructible_from < remove_cvref_t < T > , T > && requires ( remove_cvref_t < T >&& t , E && e ) { { execution :: set_done ( std :: move ( t )) } noexcept ; { execution :: set_error ( std :: move ( t ), ( E && ) e ) } noexcept ; }; template < class T , class ... An > concept receiver_of = receiver < T > && requires ( remove_cvref_t < T >&& t , An && ... an ) { execution :: set_value ( std :: move ( t ), ( An && ) an ...); }; -
The receiver’s completion-signal operations have semantic requirements that are collectively known as the receiver contract, described below:
-
None of a receiver’s completion-signal operations shall be invoked before
has been called on the operation state object that was returned byexecution :: start
to connect that receiver to a sender.execution :: connect -
Once
has been called on the operation state object, exactly one of the receiver’s completion-signal operations shall complete non-exceptionally before the receiver is destroyed.execution :: start -
If
exits with an exception, it is still valid to callexecution :: set_value
orexecution :: set_error
on the receiver, but it is no longer valid to callexecution :: set_done
on the receiver.execution :: set_value
-
-
Once one of a receiver’s completion-signal operations has completed non-exceptionally, the receiver contract has been satisfied.
9.4.1. Set value algorithm [execution.receiver.set_value]
-
is used to send a value completion signal to a receiver.execution :: set_value -
The name
denotes a customization point object. The expressionexecution :: set_value
for some subexpressionsexecution :: set_value ( R , Vs ...)
andR
is expression-equivalent to:Vs ... -
, if that expression is valid. If the function selected bytag_invoke ( execution :: set_value , R , Vs ...)
does not send the value(s)tag_invoke
to the receiverVs ...
’s value channel, the program is ill-formed with no diagnostic required.R -
Otherwise,
is ill-formed.execution :: set_value ( R , Vs ...)
-
9.4.2. Set error algorithm [execution.receiver.set_error]
-
is used to send a error signal to a receiver.execution :: set_error -
The name
denotes a customization point object. The expressionexecution :: set_error
for some subexpressionsexecution :: set_error ( R , E )
andR
is expression-equivalent to:E -
, if that expression is valid. If the function selected bytag_invoke ( execution :: set_error , R , E )
does not send the errortag_invoke
to the receiverE
’s error channel, the program is ill-formed with no diagnostic required.R -
Otherwise,
is ill-formed.execution :: set_error ( R , E )
-
9.4.3. Set done algorithm [execution.receiver.set_done]
-
is used to send a done signal to a receiver.execution :: set_done -
The name
denotes a customization point object. The expressionexecution :: set_done
for some subexpressionexecution :: set_done ( R )
is expression-equivalent to:R -
, if that expression is valid. If the function selected bytag_invoke ( execution :: set_done , R )
does not signal the receivertag_invoke
’s done channel, the program is ill-formed with no diagnostic required.R -
Otherwise,
is ill-formed.execution :: set_done ( R )
-
9.4.4. Receiver queries [execution.receiver.queries]
9.4.4.1. Scheduler receiver query [execution.receiver.queries.scheduler]
-
is used to ask a receiver object for a suggested scheduler to be used by a sender it is connected to when it needs to launch additional work. [Note: the presence of this query on a receiver does not bind a sender to use its result. --end note]execution :: get_scheduler -
The name
denotes a customization point object. For some subexpressionexecution :: get_scheduler
, letr
beR
. Ifdecltype (( r ))
does not satisfyR
,execution :: receiver
is ill-formed. Otherwise,execution :: get_scheduler
is expression equivalent to:execution :: get_scheduler ( r ) -
, if this expression is well formed and satisfiestag_invoke ( execution :: get_scheduler , as_const ( r ))
, and isexecution :: scheduler
.noexcept -
Otherwise,
is ill-formed.execution :: get_scheduler ( r )
-
9.4.4.2. Allocator receiver query [execution.receiver.queries.allocator]
-
is used to ask a receiver object for a suggested allocator to be used by a sender it is connected to when it needs to allocate memory. [Note: the presence of this query on a receiver does not bind a sender to use its result. --end note]execution :: get_allocator -
The name
denotes a customization point object. For some subexpressionexecution :: get_allocator
, letr
beR
. Ifdecltype (( r ))
does not satisfyR
,execution :: receiver
is ill-formed. Otherwise,execution :: get_allocator
is expression equivalent to:execution :: get_allocator ( r ) -
, if this expression is well formed and models Allocator, and istag_invoke ( execution :: get_allocator , as_const ( r ))
.noexcept -
Otherwise,
is ill-formed.execution :: get_allocator ( r )
-
9.4.4.3. Stop_token receiver query [execution.receiver.queries.stop_token]
-
is used to ask a receiver object for an associated stop token to be used by a sender it is connected to when it needs to launch additional work. [Note: the presence of this query on a receiver does not bind a sender to use its result. --end note]execution :: get_stop_token -
The name
denotes a customization point object. For some subexpressionexecution :: get_stop_token
, letr
beR
. Ifdecltype (( r ))
does not satisfyR
,execution :: receiver
is ill-formed. Otherwise,execution :: get_stop_token
is expression equivalent to:execution :: get_stop_token ( r ) -
, if this expression is well formed and satisfiestag_invoke ( execution :: get_stop_token , as_const ( r ))
, and isstoppable_token
.noexcept -
Otherwise,
.never_stop_token {}
-
9.5. Operation states [execution.op_state]
-
The
concept defines the requirements for an operation state type, which allows for starting the execution of work.operation_state template < class O > concept operation_state = destructible < O > && is_object_v < O > && requires ( O & o ) { { execution :: start ( o ) } noexcept ; };
9.5.1. Start algorithm [execution.op_state.start]
-
is used to start work represented by an operation state object.execution :: start -
The name
denotes a customization point object. The expressionexecution :: start
for some lvalue subexpressionexecution :: start ( O )
is expression-equivalent to:O -
, if that expression is valid. If the function selected bytag_invoke ( execution :: start , O )
does not start the work represented by the operation statetag_invoke
, the program is ill-formed with no diagnostic required.O -
Otherwise,
is ill-formed.execution :: start ( O )
-
-
The caller of
must guarantee that the lifetime of the operation state objectexecution :: start ( O )
extends at least until one of the receiver completion-signal functions of a receiverO
passed into theR
call that producedexecution :: connect
is ready to successfully return. [Note: this allows for the receiver to manage the lifetime of the operation state object, if destroying it is the last operation it performs in its completion-signal functions. --end note]O
9.6. Senders [execution.sender]
-
A sender describes a potentially asynchronous operation. A sender’s responsibility is to fulfill the receiver contract of a connected receiver by delivering one of the receiver completion-signals.
-
The
concept defines the requirements for a sender type. Thesender
concept defines the requirements for a sender type capable of being connected with a specific receiver type.sender_to template < class S > concept sender = move_constructible < remove_cvref_t < S >> && ! requires { typename sender_traits < remove_cvref_t < S >>:: __unspecialized ; // exposition only }; template < class S , class R > concept sender_to = sender < S > && receiver < R > && requires ( S && s , R && r ) { execution :: connect (( S && ) s , ( R && ) r ); }; -
A sender is typed if it declares what types it sends through a connected receiver’s channels.
-
The
concept defines the requirements for a typed sender type.typed_sender template < class S > concept has - sender - types = // exposition only requires { typename has - value - types < S :: template value_types > ; typename has - error - types < S :: template error_types > ; typename bool_constant < S :: sends_done > ; }; template < class S > concept typed_sender = sender < S > && has - sender - types < sender_traits < remove_cvref_t < S >>> ;
9.6.1. Sender traits [execution.sender.traits]
-
The class
is used as a base class to tag sender types which do not expose member templatessender_base
,value_types
, and a static member constant expressionerror_types
.sends_done -
The class template
is used to query a sender type for facts associated with the signal it sends.sender_traits -
The primary class template
is defined as if inheriting from an implementation-defined class templatesender_traits < S >
defined as follows:sender - traits - base < S > -
If
ishas - sender - types < S > true
, then
is equivalent to:sender - traits - base < S > template < class S > struct sender - traits - base { template < template < class ... > class Tuple , template < class ... > class Variant > using value_types = typename S :: template value_types < Tuple , Variant > ; template < template < class ... > class Variant > using error_types = typename S :: template error_types < Variant > ; static constexpr bool sends_done = S :: sends_done ; }; -
Otherwise, if
isderived_from < S , sender_base > true
, then
is equivalent tosender - traits - base < S > template < class S > struct sender - traits - base {}; -
Otherwise,
is equivalent tosender - traits - base < S > template < class S > struct sender - traits - base { using __unspecialized = void ; // exposition only };
-
-
If
for some sender typesender_traits < S >:: value_types < Tuple , Variant >
is well formed, it shall be a typeS
, where the type packsVariant < Tuple < Args0 ..., Args1 ..., ..., ArgsN ... >>
throughArgs0
are the packs of types the senderArgsN
passes as arguments toS
after a receiver object. If such senderexecution :: set_value
invokesS
for some receiverexecution :: set_value ( r , args ...)
, wherer
is not one of the type packsdecltype ( args )
throughArgs0
, the program is ill-formed with no diagnostic required.ArgsN -
If
for some sender typesender_traits < S >:: error_types < Variant >
is well formed, it shall be a typeS
, where the typesVariant < E0 , E1 , ..., EN >
throughE0
are the types the senderEN
passes as arguments toS
after a receiver object. If such senderexecution :: set_error
invokesS
for some receiverexecution :: set_error ( r , e )
, wherer
is not one of the typesdecltype ( e )
throughE0
, the program is ill-formed with no diagnostic required.EN -
If
is well formed andsender_traits < S >:: sends_done true
, and such sender
invokesS
for some receiverexecution :: set_done ( r )
, the program is ill-formed with no diagnostic required.r -
Users may specialize
on program-defined types.sender_traits
9.6.2. Connect sender algorithm [execution.sender.connect]
-
is used to connect a sender with a receiver, producing an operation state object that represents the work that needs to be performed to satisfy the receiver contract of the receiver with values that are the result of the operations described by the sender.execution :: connect -
The name
denotes a customization point object. For some subexpressionsexecution :: connect
ands
, letr
beS
anddecltype (( s ))
beR
. Ifdecltype (( r ))
does not satisfyR
orexecution :: receiver
does not satisfyS
,execution :: sender
is ill-formed. Otherwise, the expressionexecution :: connect ( s , r )
is expression-equivalent to:execution :: connect ( s , r ) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: connect , s , r )
. If the function selected byexecution :: operation_state
does not return an operation state for whichtag_invoke
starts work described byexecution :: start
, the program is ill-formed with no diagnostic required.s -
Otherwise,
is ill-formed.execution :: connect ( s , r )
-
-
Standard sender types shall always expose an rvalue-qualified overload of a customization of
. Standard sender types shall only expose an lvalue-qualified overload of a customization ofexecution :: connect
if they are copyable.execution :: connect
9.6.3. Sender queries [execution.sender.queries]
9.6.3.1. Scheduler sender query [execution.sender.queries.scheduler]
-
is used to ask a sender object for the completion scheduler for one of its signals.execution :: get_completion_scheduler -
The name
denotes a customization point object template. For some subexpressionexecution :: get_completion_scheduler
, lets
beS
. Ifdecltype (( s ))
does not satisfyS
,execution :: sender
is ill-formed. If the template argumentexecution :: get_completion_scheduler
inCPO
is not one ofexecution :: get_completion_scheduler < CPO >
,execution :: set_value_t
, orexecution :: set_error_t
,execution :: set_done_t
is ill-formed. Otherwise,execution :: get_completion_scheduler < CPO >
is expression-equivalent to:execution :: get_completion_scheduler < CPO > ( s ) -
, if this expression is well formed and satisfiestag_invoke ( execution :: get_completion_scheduler < CPO > , as_const ( s ))
, and isexecution :: scheduler
.noexcept -
Otherwise,
is ill-formed.execution :: get_completion_scheduler < CPO > ( s )
-
-
If, for some sender
and customization point objects
,CPO
is well-formed and results in a schedulerexecution :: get_completion_scheduler < decltype ( CPO ) > ( s )
, and the sendersch
invokess
, for some receiverCPO ( r , args ...)
which has been connected tor
, with additional argumentss
, on an execution agent which does not belong to the associated execution context ofargs ...
, the behavior is undefined.sch
9.6.4. Sender factories [execution.sender.factories]
9.6.4.1. General [execution.sender.factories.general]
-
Subclause [execution.sender.factories] defines sender factories, which are utilities that return senders without accepting senders as arguments.
9.6.4.2. Schedule sender factory [execution.sender.schedule]
-
is used to obtain a sender associated with a scheduler, which can be used to describe work to be started on that scheduler’s associated execution context.execution :: schedule -
The name
denotes a customization point object. For some subexpressionexecution :: schedule
, lets
beS
. Ifdecltype (( s ))
does not satisfyS
,execution :: scheduler
is ill-formed. Otherwise, the expressionexecution :: schedule
is expression-equivalent to:execution :: schedule ( s ) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: schedule , s )
. If the function selected byexecution :: sender
does not return a sender whosetag_invoke
completion scheduler is equivalent toset_value
, the program is ill-formed with no diagnostic required.s -
Otherwise,
is ill-formed.execution :: schedule ( s )
-
9.6.4.3. Just sender factory [execution.sender.just]
-
is used to create a sender that propagates a set of values to a connected receiver.execution :: just template < class ... Ts > struct just - sender // exposition only { std :: tuple < Ts ... > vs_ ; template < template < class ... > class Tuple , template < class ... > class Tuple > using value_types = Variant < Tuple < Ts ... >> ; template < template < class ... > class Variant > using error_types = Variant <> ; static const constexpr auto sends_done = false; template < class R > struct operation_state { std :: tuple < Ts ... > vs_ ; R r_ ; void tag_invoke ( execution :: start_t ) noexcept ( noexcept ( execution :: set_value ( declval < R > (), declval < Ts > ()...) )) { try { apply ([ & ]( Ts & ... values_ ) { execution :: set_value ( move ( r_ ), move ( values_ )...); }, vs_ ); } catch (...) { execution :: set_error ( move ( r_ ), current_exception ()); } } }; template < receiver R > requires receiver_of < R , Ts ... > && ( copyable < Ts > ... && ) auto tag_invoke ( execution :: connect_t , R && r ) const & { return operation_state < R > { vs_ , std :: forward < R > ( r ) }; } template < receiver R > requires receiver_of < R , Ts ... > auto tag_invoke ( execution :: connect_t , R && r ) && { return operation_state < R > { std :: move ( vs_ ), std :: forward < R > ( r ) }; } }; template < moveable - value ... Ts > just - sender < remove_cvref_t < Ts > ... > just ( Ts && ... ts ) noexcept ( see - below ); -
Effects: Initializes
withvs_
.make_tuple ( forward < Ts > ( ts )...) -
Remarks: The expression in the
is equivalent tonoexcept - specifier ( is_nothrow_constructible_v < remove_cvref_t < Ts > , Ts > && ...)
9.6.4.4. transfer_just sender factory [execution.sender.transfer_just]
-
is used to create a sender that propagates a set of values to a connected receiver on an execution agent belonging to the associated execution context of a specified scheduler.execution :: transfer_just -
The name
denotes a customization point object. For some subexpressionsexecution :: transfer_just
ands
, letvs ...
beS
anddecltype (( s ))
beVs ...
. Ifdecltype (( vs ))
does not satisfyS
, or any typeexecution :: scheduler
inV
does not satisfyVs
,< i > moveable - value </ i >
is ill-formed. Otherwise,execution :: transfer_just ( s , vs ...)
is expression-equivalent to:execution :: transfer_just ( s , vs ...) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: transfer_just , s , vs ...)
. If the function selected byexecution :: typed_sender
does not return a sender whosetag_invoke
completion scheduler is equivalent toset_value
and sends values equivalent tos
to a receiver connected to it, the program is ill-formed with no diagnostic required.vs ... -
Otherwise,
.execution :: transfer ( execution :: just ( vs ...), s )
-
9.6.5. Sender adaptors [execution.sender.adaptors]
9.6.5.1. General [execution.sender.adaptors.general]
-
Subclause [execution.sender.adaptors] defines sender adaptors, which are utilities that transform one or more senders into a sender with custom behaviors. When they accept a single sender argument, they can be chained to create sender chains.
-
The bitwise OR operator is overloaded for the purpose of creating sender chains. The adaptors also support function call syntax with equivalent semantics.
-
Most sender adaptors have two versions, an potentially eager version, and a strictly lazy version. For such sender adaptors,
is the potentially eager version, andadaptor
is the strictly lazy version.lazy_ adaptor -
A strictly lazy version of a sender adaptor is required to not begin executing any functions which would observe or modify any of the arguments of the adaptor before the returned sender is connected with a receiver using
, andexecution :: connect
is called on the resulting operation state. This requirement applies to any function that is selected by the implementation of the sender adaptor.execution :: start -
Unless otherwise specified, all sender adaptors which accept a single
argument return sender objects that propagate sender queries to that single sender argument. This requirement applies to any function that is selected by the implementation of the sender adaptor.sender -
Unless otherwise specified, whenever a strictly lazy sender adaptor constructs a receiver it passes to another sender’s connect, that receiver shall propagate receiver queries to a receiver accepted as an argument of
. This requirements applies to any sender returned from a function that is selected by the implementation of a strictly lazy sender adaptor.execution :: connect
9.6.5.2. Sender adaptor closure objects [execution.sender.adaptor.objects]
-
A pipeable sender adaptor closure object is a function object that accepts one or more
arguments and returns asender
. For a sender adaptor closure objectsender
and an expressionC
such thatS
modelsdecltype (( S ))
, the following expressions are equivalent and yield asender
:sender C ( S ) S | C Given an additional pipeable sender adaptor closure object
, the expressionD
is well-formed and produces another range adaptor closure object such that the following two expressions are equivalent:C | D S | C | D S | ( C | D ) -
A pipeable sender adaptor object is a customization point object that accepts a
as its first argument and returns asender
.sender -
If a pipeable sender adaptor object accepts only one argument, then it is a pipeable sender adaptor closure object.
-
If a pipeable sender adaptor object accepts more than one argument, then the following expressions are equivalent:
adaptor ( sender , args ...) adaptor ( args ...)( sender ) sender | adaptor ( args ...) In that case,
is a pipeable sender adaptor closure object.adaptor ( args ...)
9.6.5.3. On adaptor [execution.sender.adaptors.on]
-
andexecution :: on
are used to adapt a sender in a sender that will start the input sender on an execution agent belonging to a specific execution context.execution :: lazy_on -
The name
denotes a customization point object. For some subexpressionsexecution :: on
andsch
, lets
beSch
anddecltype (( sch ))
beS
. Ifdecltype (( s ))
does not satisfySch
, orexecution :: scheduler
does not satisfyS
,execution :: sender
is ill-formed. Otherwise, the expressionexecution :: on
is expression-equivalent to:execution :: on ( sch , s ) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: on , sch , s )
.execution :: sender -
Otherwise,
.lazy_on ( sch , s )
If the function selected above does not return a sender which starts
on an execution agent of the associated execution context ofs
, the program is ill-formed with no diagnostic required.sch -
-
The name
denotes a customization point object. For some subexpressionsexecution :: lazy_on
andsch
, lets
beSch
anddecltype (( sch ))
beS
. Ifdecltype (( s ))
does not satisfySch
, orexecution :: scheduler
does not satisfyS
,execution :: sender
is ill-formed. Otherwise, the expressionexecution :: lazy_on
is expression-equivalent to:execution :: lazy_on ( sch , s ) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: lazy_on , sch , s )
. If the function selected above does not return a sender which startsexecution :: sender
on an execution agent of the associated execution context ofs
when started, the program is ill-formed with no diagnostic required.sch -
Otherwise, constructs a sender
. Whens2
is connected with some receivers2
, it results in an operation stateout_r
. Whenop_state
is called onexecution :: start
, it:op_state -
Constructs a receiver
:r -
When
is called, it callsexecution :: set_value ( r )
, which results inexecution :: connect ( s , out_r )
. It callsop_state2
. If any of these throws an exception, it callsexecution :: start ( op_state2 )
onexecution :: set_error
, passingout_r
as the second argument.current_exception () -
When
is called, it callsexecution :: set_error ( r , e )
.execution :: set_error ( out_r , e ) -
When
is called, it callsexecution :: set_done ( r )
.execution :: set_done ( out_r )
-
-
Calls
, which results inexecution :: schedule ( sch )
. It then callss3
, resulting inexecution :: connect ( s3 , r )
, and then it callsop_state3
. If any of these throws an exception, it catches it and callsexecution :: start ( op_state3 )
.execution :: set_error ( out_r , current_exception ())
-
-
-
Any receiver
created by an implementation ofr
andon
shall implement thelazy_on
receiver query. The scheduler returned from the query for all such receivers should be equivalent to theget_scheduler
argument passed into thesch
oron
call.lazy_on
9.6.5.4. transfer adaptor [execution.sender.adaptors.transfer]
-
andexecution :: transfer
are used to adapt a sender into a sender with a different associatedexecution :: lazy_transfer
completion scheduler. [Note: it results in a transition between different execution contexts when executed. --end note]set_value -
The name
denotes a customization point object. For some subexpressionsexecution :: transfer
andsch
, lets
beSch
anddecltype (( sch ))
beS
. Ifdecltype (( s ))
does not satisfySch
, orexecution :: scheduler
does not satisfyS
,execution :: sender
is ill-formed. Otherwise, the expressionexecution :: transfer
is expression-equivalent to:execution :: transfer ( s , sch ) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: transfer , get_completion_scheduler < set_value_t > ( s ), s , sch )
.execution :: sender -
Otherwise,
, if that expression is valid and its type satisfiestag_invoke ( execution :: transfer , s , sch )
.execution :: sender -
Otherwise,
.schedule_from ( sch , s )
If the function selected above does not return a sender which is a result of a call to
, whereexecution :: schedule_from ( sch , s2 )
is a sender which sends equivalent to those sent bys2
, the program is ill-formed with no diagnostic required.s -
-
The name
denotes a customization point object. For some subexpressionsexecution :: lazy_transfer
andsch
, lets
beSch
anddecltype (( sch ))
beS
. Ifdecltype (( s ))
does not satisfySch
, orexecution :: scheduler
does not satisfyS
,execution :: sender
is ill-formed. Otherwise, the expressionexecution :: lazy_transfer
is expression-equivalent to:execution :: lazy_transfer ( s , sch ) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: lazy_transfer , get_completion_scheduler < set_value_t > ( s ), s , sch )
.execution :: sender -
Otherwise,
, if that expression is valid and its type satisfiestag_invoke ( execution :: lazy_transfer , s , sch )
.execution :: sender -
Otherwise,
.lazy_schedule_from ( sch , s )
If the function selected above does not return a sender which is a result of a call to
, whereexecution :: lazy_schedule_from ( sch , s2 )
is a sender which sends equivalent to those sent bys2
, the program is ill-formed with no diagnostic required.s -
-
Senders returned from
andexecution :: transfer
shall not propagate the sender queriesexecution :: lazy_transfer
to an input sender. They shall return a sender equivalent to theget_completion_scheduler < CPO >
argument from those queries.sch
9.6.5.5. Schedule_from adaptor [execution.sender.adaptors.schedule_from]
-
andexecution :: schedule_from
are used to schedule work dependent on the completion of a sender onto a scheduler’s associated execution context. [Note:execution :: lazy_schedule_from
andschedule_from
are not meant to be used in user code; they are used in the implementation oflazy_schedule_from
andtransfer
. -end note]lazy_transfer -
The name
denotes a customization point object. For some subexpressionsexecution :: schedule_from
andsch
, lets
beSch
anddecltype (( sch ))
beS
. Ifdecltype (( s ))
does not satisfySch
, orexecution :: scheduler
does not satisfyS
,execution :: typed_sender
is ill-formed. Otherwise, the expressionexecution :: schedule_from
is expression-equivalent to:execution :: schedule_from ( sch , s ) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: schedule_from , sch , s )
. If the function selected byexecution :: sender
does not return a sender which completes on an execution agent belonging to the associated execution context oftag_invoke
and sends signals equivalent to those sent bysch
, the program is ill-formed with no diagnostic required.s -
Otherwise,
.lazy_schedule_from ( sch , s )
-
-
The name
denotes a customization point object. For some subexpressionsexecution :: lazy_schedule_from
andsch
, lets
beSch
anddecltype (( sch ))
beS
. Ifdecltype (( s ))
does not satisfySch
, orexecution :: scheduler
does not satisfyS
,execution :: typed_sender
is ill-formed. Otherwise, the expressionexecution :: lazy_schedule_from
is expression-equivalent to:execution :: lazy_schedule_from ( sch , s ) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: lazy_schedule_from , sch , s )
. If the function selected byexecution :: sender
does not return a sender which completes on an execution agent belonging to the associated execution context oftag_invoke
and sends signals equivalent to those sent bysch
, the program is ill-formed with no diagnostic required.s -
Otherwise, constructs a sender
. Whens2
is connected with some receivers2
, it:out_r -
Constructs a receiver
.r -
Calls
, which results in an operation stateexecution :: connect ( s , r )
. If any of these throws an exception, callsop_state2
onexecution :: set_error
, passingout_r
as the second argument.current_exception () -
When a receiver completion-signal
is called, it constructs a receiverSignal ( r , args ...)
:r2 -
When
is called, it callsexecution :: set_value ( r2 )
.Signal ( out_r , args ...) -
When
is called, it callsexecution :: set_error ( r2 , e )
.execution :: set_error ( out_r , e ) -
When
is called, it callsexecution :: done ( r2 )
.execution :: set_done ( out_r )
It then calls
, resulting in a senderexecution :: schedule ( sch )
. It then callss3
, resulting in an operation stateexecution :: connect ( s3 , r2 )
. It then callsop_state3
. If any of these throws an exception, it catches it and callsexecution :: start ( op_state3 )
.execution :: set_error ( out_r , current_exception ()) -
-
Returns an operation state
that containsop_state
. Whenop_state2
is called, callsexecution :: start ( op_state )
.execution :: start ( op_state2 )
-
-
-
Senders returned from
andexecution :: transfer
shall not propagate the sender queriesexecution :: lazy_transfer
to an input sender. They shall return a scheduler equivalent to theget_completion_scheduler < CPO >
argument from those queries.sch
9.6.5.6. Then adaptor [execution.sender.adaptors.then]
-
andexecution :: then
are used to attach invocables as continuation for successful completion of the input sender.execution :: lazy_then -
The name
denotes a customization point object. For some subexpressionsexecution :: then
ands
, letf
beS
. Ifdecltype (( s ))
does not satisfyS
,execution :: sender
is ill-formed. Otherwise, the expressionexecution :: then
is expression-equivalent to:execution :: then ( s , f ) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: then , get_completion_scheduler < set_value_t > ( s ), s , f )
.execution :: sender -
Otherwise,
, if that expression is valid and its type satisfiestag_invoke ( execution :: then , s , f )
.execution :: sender -
Otherwise,
.lazy_then ( s , f )
If the function selected above does not return a sender which invokes
with the result of thef
signal ofset_value
, passing the return value as the value to any connected receivers, and propagates the other completion-signals sent bys
, the program is ill-formed with no diagnostic required.s -
-
The name
denotes a customization point object. For some subexpressionsexecution :: lazy_then
ands
, letf
beS
. Ifdecltype (( s ))
does not satisfyS
,execution :: sender
is ill-formed. Otherwise, the expressionexecution :: lazy_then
is expression-equivalent to:execution :: lazy_then ( s , f ) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: lazy_then , get_completion_scheduler < set_value_t > ( s ), s , f )
.execution :: sender -
Otherwise,
, if that expression is valid and its type satisfiestag_invoke ( execution :: lazy_then , s , f )
.execution :: sender -
Otherwise, constructs a sender
. Whens2
is connected with some receivers2
, it:out_r -
Constructs a receiver
:r -
When
is called, callsexecution :: set_value ( r , args ...)
and passes the resultinvoke ( f , args ...)
tov
. If any of these throws an exception, it catches it and callsexecution :: set_value ( out_r , v )
.execution :: set_error ( out_r , current_exception ()) -
When
is called, callsexecution :: set_error ( r , e )
.execution :: set_error ( out_r , e ) -
When
is called, callsexecution :: set_done ( r )
.execution :: set_done ( out_r )
-
-
Calls
, which results in an operation stateexecution :: connect ( s , r )
.op_state2 -
Returns an operation state
that containsop_state
. Whenop_state2
is called, callsexecution :: start ( op_state )
.execution :: start ( op_state2 )
-
If the function selected above does not return a sender which invokes
with the result of thef
signal ofset_value
, passing the return value as the value to any connected receivers, and propagates the other completion-signals sent bys
, the program is ill-formed with no diagnostic required.s -
9.6.5.7. Upon_error adaptor [execution.sender.adaptors.upon_error]
-
andexecution :: upon_error
are used to attach invocables as continuation for successful completion of the input sender.execution :: lazy_upon_error -
The name
denotes a customization point object. For some subexpressionsexecution :: upon_error
ands
, letf
beS
. Ifdecltype (( s ))
does not satisfyS
,execution :: sender
is ill-formed. Otherwise, the expressionexecution :: upon_error
is expression-equivalent to:execution :: upon_error ( s , f ) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: upon_error , get_completion_scheduler < set_error_t > ( s ), s , f )
.execution :: sender -
Otherwise,
, if that expression is valid and its type satisfiestag_invoke ( execution :: upon_error , s , f )
.execution :: sender -
Otherwise,
.lazy_upon_error ( s , f )
If the function selected above does not return a sender which invokes
with the result of thef
signal ofset_error
, passing the return value as the value to any connected receivers, and propagates the other completion-signals sent bys
, the program is ill-formed with no diagnostic required.s -
-
The name
denotes a customization point object. For some subexpressionsexecution :: lazy_upon_error
ands
, letf
beS
. Ifdecltype (( s ))
does not satisfyS
,execution :: sender
is ill-formed. Otherwise, the expressionexecution :: lazy_upon_error
is expression-equivalent to:execution :: lazy_upon_error ( s , f ) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: lazy_upon_error , get_completion_scheduler < set_error_t > ( s ), s , f )
.execution :: sender -
Otherwise,
, if that expression is valid and its type satisfiestag_invoke ( execution :: lazy_upon_error , s , f )
.execution :: sender -
Otherwise, constructs a sender
. Whens2
is connected with some receivers2
, it:out_r -
Constructs a receiver
:r -
When
is called, callsexecution :: set_value ( r , args ...)
.execution :: set_value ( out_r , args ...) -
When
is called, callsexecution :: set_error ( r , e )
and passes the resultinvoke ( f , e )
tov
. If any of these throws an exception, it catches it and callsexecution :: set_value ( out_r , v )
.execution :: set_error ( out_r , current_exception ()) -
When
is called, callsexecution :: set_done ( r )
.execution :: set_done ( out_r )
-
-
Calls
, which results in an operation stateexecution :: connect ( s , r )
.op_state2 -
Returns an operation state
that containsop_state
. Whenop_state2
is called, callsexecution :: start ( op_state )
.execution :: start ( op_state2 )
-
If the function selected above does not return a sender which invokes
with the result of thef
signal ofset_error
, passing the return value as the value to any connected receivers, and propagates the other completion-signals sent bys
, the program is ill-formed with no diagnostic required.s -
9.6.5.8. Upon_done adaptor [execution.sender.adaptors.upon_done]
-
andexecution :: upon_done
are used to attach invocables as continuation for successful completion of the input sender.execution :: lazy_upon_done -
The name
denotes a customization point object. For some subexpressionsexecution :: upon_done
ands
, letf
beS
. Ifdecltype (( s ))
does not satisfyS
,execution :: sender
is ill-formed. Otherwise, the expressionexecution :: upon_done
is expression-equivalent to:execution :: upon_done ( s , f ) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: upon_done , get_completion_scheduler < set_done_t > ( s ), s , f )
.execution :: sender -
Otherwise,
, if that expression is valid and its type satisfiestag_invoke ( execution :: upon_done , s , f )
.execution :: sender -
Otherwise,
.lazy_upon_done ( s , f )
If the function selected above does not return a sender which invokes
when thef
signal ofset_done
is called, passing the return value as the value to any connected receivers, and propagates the other completion-signals sent bys
, the program is ill-formed with no diagnostic required.s -
-
The name
denotes a customization point object. For some subexpressionsexecution :: lazy_upon_done
ands
, letf
beS
. Ifdecltype (( s ))
does not satisfyS
,execution :: sender
is ill-formed. Otherwise, the expressionexecution :: lazy_upon_done
is expression-equivalent to:execution :: lazy_upon_done ( s , f ) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: lazy_upon_done , get_completion_scheduler < set_done_t > ( s ), s , f )
.execution :: sender -
Otherwise,
, if that expression is valid and its type satisfiestag_invoke ( execution :: lazy_upon_done , s , f )
.execution :: sender -
Otherwise, constructs a sender
. Whens2
is connected with some receivers2
, it:out_r -
Constructs a receiver
:r -
When
is called, callsexecution :: set_value ( r , args ...)
.execution :: set_value ( out_r , args ...) -
When
is called, callsexecution :: set_error ( r , e )
.execution :: set_error ( out_r , e ) -
When
is called, callsexecution :: set_done ( r )
and passes the resultinvoke ( f )
tov
. If any of these throws an exception, it catches it and callsexecution :: set_value ( out_r , v )
.execution :: set_error ( out_r , current_exception ())
-
-
Calls
, which results in an operation stateexecution :: connect ( s , r )
.op_state2 -
Returns an operation state
that containsop_state
. Whenop_state2
is called, callsexecution :: start ( op_state )
.execution :: start ( op_state2 )
-
If the function selected above does not return a sender which invokes
when thef
signal ofset_done
is called, passing the return value as the value to any connected receivers, and propagates the other completion-signals sent bys
, the program is ill-formed with no diagnostic required.s -
9.6.5.9. Let_value adaptor [execution.sender.adaptors.let_value]
-
andexecution :: let_value
are used to insert continuations creating more work dependent on the results of their input senders into a sender chain.execution :: lazy_let_value -
The name
denotes a customization point object. For some subexpressionsexecution :: let_value
ands
, letf
beS
. Ifdecltype (( s ))
does not satisfyS
,execution :: sender
is ill-formed. Otherwise, the expressionexecution :: let_value
is expression-equivalent to:execution :: let_value ( s , f ) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: let_value , get_completion_scheduler < set_value_t > ( s ), s , f )
.execution :: sender -
Otherwise,
, if that expression is valid and its type satisfiestag_invoke ( execution :: let_value , s , f )
.execution :: sender -
Otherwise,
.lazy_let_value ( s , f )
If the function selected above does not return a sender which invokes
whenf
is called, and making its completion dependent on the completion of a sender returned byset_value
, and propagates the other completion-signals sent byf
, the program is ill-formed with no diagnostic required.s -
-
The name
denotes a customization point object. For some subexpressionsexecution :: lazy_let_value
ands
, letf
beS
. Ifdecltype (( s ))
does not satisfyS
,execution :: sender
is ill-formed. Otherwise, the expressionexecution :: lazy_let_value
is expression-equivalent to:execution :: lazy_let_value ( s , f ) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: lazy_let_value , get_completion_scheduler < set_value_t > ( s ), s , f )
.execution :: sender -
Otherwise,
, if that expression is valid and its type satisfiestag_invoke ( execution :: lazy_let_value , s , f )
.execution :: sender -
Otherwise, constructs a sender
. Whens2
is connected with some receivers2
, it:out_r -
Constructs a receiver
.r -
When
is called, copiesexecution :: set_value ( r , args ...)
intoargs ...
asop_state2
, then callsargs2 ...
, resulting in a senderinvoke ( f , args2 ...)
. It then callss3
, resulting in an operation stateexecution :: connect ( s3 , out_r )
.op_state3
is saved as a part ofop_state3
. It then callsop_state2
. If any of these throws an exception, it catches it and callsexecution :: start ( op_state3 )
.execution :: set_error ( out_r , current_exception ()) -
When
is called, callsexecution :: set_error ( r , e )
.execution :: set_error ( out_r , e ) -
When
is called, callsexecution :: set_done ( r , e )
.execution :: set_done ( out_r )
-
-
Calls
, which results in an operation stateexecution :: connect ( s , r )
.op_state2 -
Returns an operation state
that containsop_state
. Whenop_state2
is called, callsexecution :: start ( op_state )
.execution :: start ( op_state2 )
-
If the function selected above does not return a sender which invokes
whenf
is called, and making its completion dependent on the completion of a sender returned byset_value
, and propagates the other completion-signals sent byf
, the program is ill-formed with no diagnostic required.s -
9.6.5.10. Let_error adaptor [execution.sender.adaptors.let_error]
-
andexecution :: let_error
are used to insert continuations creating more work dependent on the results of their input senders into a sender chain.execution :: lazy_let_error -
The name
denotes a customization point object. For some subexpressionsexecution :: let_error
ands
, letf
beS
. Ifdecltype (( s ))
does not satisfyS
,execution :: sender
is ill-formed. Otherwise, the expressionexecution :: let_error
is expression-equivalent to:execution :: let_error ( s , f ) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: let_error , get_completion_scheduler < set_error_t > ( s ), s , f )
.execution :: sender -
Otherwise,
, if that expression is valid and its type satisfiestag_invoke ( execution :: let_error , s , f )
.execution :: sender -
Otherwise,
.lazy_let_error ( s , f )
If the function selected above does not return a sender which invokes
whenf
is called, and making its completion dependent on the completion of a sender returned byset_error
, and propagates the other completion-signals sent byf
, the program is ill-formed with no diagnostic required.s -
-
The name
denotes a customization point object. For some subexpressionsexecution :: lazy_let_error
ands
, letf
beS
. Ifdecltype (( s ))
does not satisfyS
,execution :: sender
is ill-formed. Otherwise, the expressionexecution :: lazy_let_error
is expression-equivalent to:execution :: lazy_let_error ( s , f ) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: lazy_let_error , get_completion_scheduler < set_error_t > ( s ), s , f )
.execution :: sender -
Otherwise,
, if that expression is valid and its type satisfiestag_invoke ( execution :: lazy_let_error , s , f )
.execution :: sender -
Otherwise, constructs a sender
. Whens2
is connected with some receivers2
, it:out_r -
Constructs a receiver
.r -
When
is called, callsexecution :: set_value ( r , args ...)
.execution :: set_value ( out_r , args ...) -
When
is called, copiesexecution :: set_error ( r , e )
intoe
asop_statee2
, then callse
, resulting in a senderinvoke ( f , e )
. It then callss3
, resulting in an operation stateexecution :: connect ( s3 , out_r )
.op_state3
is saved as a part ofop_state3
. It then callsop_state2
. If any of these throws an exception, it catches it and callsexecution :: start ( op_state3 )
.execution :: set_error ( out_r , current_exception ()) -
When
is called, callsexecution :: set_done ( r , e )
.execution :: set_done ( out_r )
-
-
Calls
, which results in an operation stateexecution :: connect ( s , r )
.op_state2 -
Returns an operation state
that containsop_state
. Whenop_state2
is called, callsexecution :: start ( op_state )
.execution :: start ( op_state2 )
-
If the function selected above does not return a sender which invokes
whenf
is called, and making its completion dependent on the completion of a sender returned byset_error
, and propagates the other completion-signals sent byf
, the program is ill-formed with no diagnostic required.s -
9.6.5.11. Let_done adaptor [execution.sender.adaptors.let_done]
-
andexecution :: let_done
are used to insert continuations creating more work dependent on the results of their input senders into a sender chain.execution :: lazy_let_done -
The name
denotes a customization point object. For some subexpressionsexecution :: let_done
ands
, letf
beS
. Ifdecltype (( s ))
does not satisfyS
,execution :: sender
is ill-formed. Otherwise, the expressionexecution :: let_done
is expression-equivalent to:execution :: let_done ( s , f ) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: let_done , get_completion_scheduler < set_done_t > ( s ), s , f )
.execution :: sender -
Otherwise,
, if that expression is valid and its type satisfiestag_invoke ( execution :: let_done , s , f )
.execution :: sender -
Otherwise,
.lazy_let_done ( s , f )
If the function selected above does not return a sender which invokes
whenf
is called, and making its completion dependent on the completion of a sender returned byset_done
, and propagates the other completion-signals sent byf
, the program is ill-formed with no diagnostic required.s -
-
The name
denotes a customization point object. For some subexpressionsexecution :: lazy_let_done
ands
, letf
beS
. Ifdecltype (( s ))
does not satisfyS
,execution :: sender
is ill-formed. Otherwise, the expressionexecution :: lazy_let_done
is expression-equivalent to:execution :: lazy_let_done ( s , f ) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: lazy_let_done , get_completion_scheduler < set_done_t > ( s ), s , f )
.execution :: sender -
Otherwise,
, if that expression is valid and its type satisfiestag_invoke ( execution :: lazy_let_done , s , f )
.execution :: sender -
Otherwise, constructs a sender
. Whens2
is connected with some receivers2
, it:out_r -
Constructs a receiver
.r -
When
is called, callsexecution :: set_value ( r , args ...)
.execution :: set_value ( out_r , args ...) -
When
is called, callsexecution :: set_error ( r , e )
.execution :: set_error ( out_r , e ) -
When
is called, callsexecution :: set_done ( r )
, resulting in a senderinvoke ( f )
. It then callss3
, resulting in an operation stateexecution :: connect ( s3 , out_r )
.op_state3
is saved as a part ofop_state3
. It then callsop_state2
. If any of these throws an exception, it catches it and callsexecution :: start ( op_state3 )
.execution :: set_error ( out_r , current_exception ())
-
-
Calls
. which results in an operation stateexecution :: connect ( s , r )
.op_state2 -
Returns an operation state
that containsop_state
. Whenop_state2
is called, callsexecution :: start ( op_state )
.execution :: start ( op_state2 )
-
If the function selected above does not return a sender which invokes
whenf
is called, and making its completion dependent on the completion of a sender returned byset_done
, and propagates the other completion-signals sent byf
, the program is ill-formed with no diagnostic required.s -
9.6.5.12. Bulk adaptor [execution.sender.adaptors.bulk]
-
andexecution :: bulk
are used to run a task repeatedly for every index in an index space.execution :: lazy_bulk -
The name
denotes a customization point object. For some subexpressionsexecution :: bulk
,s
, andshape
, letf
beS
,decltype (( s ))
beShape
, anddecltype (( shape ))
beF
. Ifdecltype (( f ))
does not satisfyS
orexecution :: sender
does not satisfyShape
,integral
is ill-formed. Otherwise, the expressionexecution :: bulk
is expression-equivalent to:execution :: bulk ( s , shape , f ) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: bulk , get_completion_scheduler < set_value_t > ( s ), s , shape , f )
.execution :: sender -
Otherwise,
, if that expression is valid and its type satisfiestag_invoke ( execution :: bulk , s , shape , f )
.execution :: sender -
Otherwise,
.lazy_bulk ( s , shape , f )
-
-
The name
denotes a customization point object. For some subexpressionsexecution :: lazy_bulk
,s
, andshape
, letf
beS
,decltype (( s ))
beShape
, anddecltype (( shape ))
beF
. Ifdecltype (( f ))
does not satisfyS
orexecution :: sender
does not satisfyShape
,integral
is ill-formed. Otherwise, the expressionexecution :: bulk
is expression-equivalent to:execution :: bulk ( s , shape , f ) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: bulk , get_completion_scheduler < set_value_t > ( s ), s , shape , f )
.execution :: sender -
Otherwise,
, if that expression is valid and its type satisfiestag_invoke ( execution :: bulk , s , shape , f )
.execution :: sender -
Otherwise, constructs a sender
. Whens2
is connected with some receivers2
, it:out_r -
Constructs a receiver
:r -
When
is called, callsexecution :: set_value ( r , args ...)
for eachf ( i , args ...)
of typei
fromShape
to0
, then callsshape
. If any of these throws an exception, it catches it and callsexecution :: set_value ( out_r , args ...)
.execution :: set_error ( out_r , current_exception ()) -
When
is called, callsexecution :: set_error ( r , e )
.execution :: set_error ( out_r , e ) -
When
is called, callsexecution :: set_done ( r , e )
.execution :: set_done ( out_r , e )
-
-
Calls
, which results in an operation stateexecution :: connect ( s , r )
.op_state2 -
Returns an operation state
that containsop_state
. Whenop_state2
is called, callsexecution :: start ( op_state )
.execution :: start ( op_state2 )
-
If the function selected above does not return a sender which invokes
for eachf ( i , args ...)
of typei
fromShape
to0
when the input sender sends valuesshape
, or does not propagate the values of the signals sent by the input sender to a connected receiver, the program is ill-formed with no diagnostic required.args ... -
9.6.5.13. Split adaptor [execution.sender.adaptors.split]
-
andexecution :: split
are used to adapt an arbitrary sender into a sender that can be connected multiple times.execution :: lazy_split -
The name
denotes a customization point object. For some subexpressionexecution :: split
, lets
beS
. Ifdecltype (( s ))
does not satisfyS
,execution :: typed_sender
is ill-formed. Otherwise, the expressionexecution :: split
is expression-equivalent to:execution :: split ( s ) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: split , get_completion_scheduler < set_value_t > ( s ), s )
.execution :: sender -
Otherwise,
, if that expression is valid and its type satisfiestag_invoke ( execution :: split , s )
.execution :: sender -
Otherwise,
.lazy_split ( s )
If the function selected above does not return a sender which sends references to values sent by
, propagating the other channels, the program is ill-formed with no diagnostic required.s -
-
The name
denotes a customization point object. For some subexpressionexecution :: lazy_split
, lets
beS
. Ifdecltype (( s ))
does not satisfyS
,execution :: typed_sender
is ill-formed. Otherwise, the expressionexecution :: lazy_split
is expression-equivalent to:execution :: lazy_split ( s ) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: lazy_split , get_completion_scheduler < set_value_t > ( s ), s )
.execution :: sender -
Otherwise,
, if that expression is valid and its type satisfiestag_invoke ( execution :: lazy_split , s )
.execution :: sender -
Otherwise, constructs a sender
, which:s2 -
Creates an object
. The lifetime ofsh_state
shall last for at least as long as the lifetime of the last operation state object returned fromsh_state
for some receiverexecution :: connect ( s , some_r )
.some_r -
Constructs a receiver
:r -
When
is called, saves the expressionsexecution :: set_value ( r , args ...)
as subobjects ofargs ...
.sh_state -
When
is called, saves the expressionexecution :: set_error ( r , e )
as a subobject ofe
.sh_state -
When
is called, saves this fact inexecution :: set_done ( r )
.sh_state
-
-
Calls
, resulting in an operation stateexecution :: connect ( s , r )
.op_state2
is saved as a subobject ofop_state2
.sh_state -
When
is connected with a receivers2
, it returns an operation state objectout_r
. Whenop_state
is called, it callsexecution :: start ( op_state )
, if this is the first time this expression would be evaluated. When bothexecution :: start ( op_state2 )
andexecution :: start ( op_state )
have been called, callsSignal ( r , args ...)
, whereSignal ( out_r , args2 ...)
is a pack of lvalues referencing the subobjects ofargs2 ...
that have been saved by the original call tosh_state
.Signal ( r , args ...)
-
If the function selected above does not return a sender which sends references to values sent by
, propagating the other channels, the program is ill-formed with no diagnostic required.s -
9.6.5.14. When_all adaptor [execution.sender.adaptors.when_all]
-
is used to join multiple sender chains and create a sender whose execution is dependent on all of the input senders that only send a single set of values.execution :: when_all
is used to join multiple sender chains and create a sender whose execution is dependent on all of the input senders, which may have one or more sets of sent values.execution :: when_all_with_variant -
The name
denotes a customization point object. For some subexpressionsexecution :: when_all
, lets ...
beS
. If any typedecltype (( s ))
inS i
does not satisfyS ...
, or the number of the argumentsexecution :: typed_sender
passes into thesender_traits < S i >:: value_types
template parameter is not 1,Variant
is ill-formed. Otherwise, the expressionexecution :: when_all
is expression-equivalent to:execution :: when_all ( s ...) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: when_all , s ...)
. If the function selected byexecution :: sender
does not return a sender which sends a concatenation of values sent bytag_invoke
when they all complete withs ...
, the program is ill-formed with no diagnostic required.set_value -
Otherwise, constructs a sender
. Whens
is connected with some receivers
, it:out_r -
For each sender
ins i
, constructs a receivers ...
:r i -
If
is called for everyexecution :: set_value ( r i , t i ...)
,r i
is called, whereexecution :: set_value ( out_r , t 0 ..., t 1 ..., ..., t n ...)
isn
.sizeof ...( s ) - 1 -
Otherwise, if
is called for anyexecution :: set_error ( r i , e )
,r i
is called.execution :: set_error ( out_r , e ) -
Otherwise, if
is called for anyexecution :: set_done ( r i )
,r i
is called.execution :: set_done ( out_r )
-
-
For each sender
ins i
, callss ...
, resulting in operation statesexecution :: connect ( s i , r i )
.op_state i -
Returns an operation state
that contains each operation stateop_state
. Whenop_state i
is called, callsexecution :: start ( op_state )
for eachexecution :: start ( op_state i )
.op_state i
-
-
-
The name
denotes a customization point object. For some subexpressionsexecution :: when_all_with_variant
, lets ...
beS
. If any typedecltype (( s ))
inS i
does not satisfyS ...
,execution :: typed_sender
is ill-formed. Otherwise, the expressionexecution :: when_all_with_variant
is expression-equivalent to:execution :: when_all_with_variant ( s ...) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: when_all_with_variant , s ...)
. If the function selected byexecution :: sender
does not return a sender which sends the typestag_invoke
when they all complete withinto - variant - type < S > ...
, the program is ill-formed with no diagnostic required.set_value -
Otherwise,
.execution :: when_all ( execution :: into_variant ( s )...)
-
-
Adaptors defined in this subclause are strictly lazy.
-
Senders returned from adaptors defined in this subclause shall not expose the sender queries
.get_completion_scheduler < CPO > -
expressions used in the definitions of the sender adaptors in this subclause shall not consider member functions of their first non-tag arguments.tag_invoke
9.6.5.15. Transfer_when_all adaptor [execution.sender.adaptors.transfer_when_all]
-
andexecution :: transfer_when_all
are used to join multiple sender chains and create a sender whose execution is dependent on all of the input senders that only send a single set of values each, while also making sure that they complete on the specified scheduler.execution :: lazy_transfer_when_all
andexecution :: transfer_when_all_with_variant
are used to join multiple sender chains and create a sender whose execution is dependent on all of the input senders, which may have one or more sets of sent values. [Note: this can allow for better customization of the adaptor. --end note]execution :: lazy_transfer_when_all_with_variant -
The name
denotes a customization point object. For some subexpressionsexecution :: transfer_when_all
andsch
, lets ...
beSch
anddecltype ( sch )
beS
. Ifdecltype (( s ))
does not satisfySch
, or any typescheduler
inS i
does not satisfyS ...
, or the number of the argumentsexecution :: typed_sender
passes into thesender_traits < S i >:: value_types
template parameter is not 1Variant
is ill-formed. Otherwise, the expressionexecution :: transfer_when_all
is expression-equivalent to:execution :: transfer_when_all ( sch , s ...) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: transfer_when_all , sch , s ...)
. If the function selected byexecution :: sender
does not return a sender which sends a concatenation of values sent bytag_invoke
when they all complete withs ...
, or does not send its completion signals, other than ones resulting from a scheduling error, on an execution agent belonging to the associated execution context ofset_value
, the program is ill-formed with no diagnostic required.sch -
Otherwise,
.transfer ( when_all ( s ...), sch )
-
-
The name
denotes a customization point object. For some subexpressionsexecution :: lazy_transfer_when_all
andsch
, lets ...
beSch
anddecltype ( sch )
beS
. Ifdecltype (( s ))
does not satisfySch
, or any typescheduler
inS i
does not satisfyS ...
, or the number of the argumentsexecution :: typed_sender
passes into thesender_traits < S i >:: value_types
template parameter is not 1,Variant
is ill-formed. Otherwise, the expressionexecution :: lazy_transfer_when_all
is expression-equivalent to:execution :: lazy_transfer_when_all ( sch , s ...) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: lazy_transfer_when_all , sch , s ...)
. If the function selected byexecution :: sender
does not return a sender which sends a concatenation of values sent bytag_invoke
when they all complete withs ...
, or does not send its completion signals, other than ones resulting from a scheduling error, on an execution agent belonging to the associated execution context ofset_value
, the program is ill-formed with no diagnostic required.sch -
Otherwise,
.lazy_transfer ( when_all ( s ...), sch )
-
-
The name
denotes a customization point object. For some subexpressionsexecution :: transfer_when_all_with_variant
, lets ...
beS
. If any typedecltype (( s ))
inS i
does not satisfyS ...
,execution :: typed_sender
is ill-formed. Otherwise, the expressionexecution :: transfer_when_all_with_variant
is expression-equivalent to:execution :: transfer_when_all_with_variant ( s ...) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: transfer_when_all_with_variant , s ...)
. If the function selected byexecution :: sender
does not return a sender which sends the typestag_invoke
when they all complete withinto - variant - type < S > ...
, the program is ill-formed with no diagnostic required.set_value -
Otherwise,
.execution :: transfer_when_all ( sch , execution :: into_variant ( s )...)
-
-
The name
denotes a customization point object. For some subexpressionsexecution :: lazy_transfer_when_all_with_variant
, lets ...
beS
. If any typedecltype (( s ))
inS i
does not satisfyS ...
,execution :: typed_sender
is ill-formed. Otherwise, the expressionexecution :: lazy_transfer_when_all_with_variant
is expression-equivalent to:execution :: lazy_transfer_when_all_with_variant ( s ...) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: lazy_transfer_when_all_with_variant , s ...)
. If the function selected byexecution :: sender
does not return a sender which sends the typestag_invoke
when they all complete withinto - variant - type < S > ...
, the program is ill-formed with no diagnostic required.set_value -
Otherwise,
.execution :: lazy_transfer_when_all ( sch , execution :: into_variant ( s )...)
-
-
Senders returned from
andexecution :: transfer_when_all
shall not propagate the sender queriesexecution :: lazy_transfer_when_all
to input senders. They shall return a scheduler equivalent to theget_completion_scheduler < CPO >
argument from those queries.sch
9.6.5.16. Into_variant adaptor [execution.sender.adaptors.into_variant]
-
can be used to turn a typed sender which sends multiple sets of values into a sender which sends a variant of all of those sets of values.execution :: into_variant -
The template
is used to compute the type sent by a sender returned frominto - variant - type
.execution :: into_variant template < typed_sender S > using into - with - variant - type = typename execution :: sender_traits < remove_cvref_t < S >> :: template value_types < tuple , variant > ; template < typed_sender S > see - below into_variant ( S && s ); -
Effects: Returns a sender
. Whens2
is connected with some receivers2
, it:out_r -
Constructs a receiver
:r -
If
is called, callsexecution :: set_value ( r , ts ...)
.execution :: set_value ( out_r , into - variant - type < S > ( make_tuple ( ts ...))) -
If
is called, callsexecution :: set_error ( r , e )
.execution :: set_error ( out_r , e ) -
If
is called, callsexecution :: set_done ( r )
.execution :: set_done ( out_r )
-
-
Calls
, resulting in an operation stateexecution :: connect ( s , r )
.op_state2 -
Returns an operation state
that containsop_state
. Whenop_state2
is called, callsexecution :: start ( op_state )
.execution :: start ( op_state2 )
-
9.6.5.17. Unschedule adaptor [execution.sender.adaptors.unschedule]
-
can be used to remove the information about completion schedulers from a sender, in effect removing any scheduler-specific customizations of sender algorithms from that sender.execution :: unschedule template < sender S > see - below unschedule ( S && s ) noexcept ( see - below ); -
Effects: If
provides none of theS
sender queries, returnsget_completion_scheduler < CPO >
. Otherwise, returns a sender adaptorstd :: forward < S > ( s )
containing a subobject of types2
, initialized withremove_cvref_t < S >
.std :: forward < S > ( s )
propagates all customizations, except fors2
, toget_completion_scheduler < CPO >
.s -
Remarks: The expression in the
is equivalent tonoexcept - specifier is_nothrow_constructible_v < remove_cvref_t < S > , S >
9.6.5.18. Ensure_started adaptor [execution.sender.adaptors.ensure_started]
-
is used to eagerly start the execution of a sender, while also providing a way to attach further work to execute once it has completed.execution :: ensure_started -
The name
denotes a customization point object. For some subexpressionexecution :: ensure_started
, lets
beS
. Ifdecltype (( s ))
does not satisfyS
,execution :: typed_sender
is ill-formed. Otherwise, the expressionexecution :: ensure_started
is expression-equivalent to:execution :: ensure_started ( s ) -
, if that expression is valid and its type satisfiestag_invoke ( execution :: ensure_started , get_completion_scheduler < set_value_t > ( s ), s )
.execution :: sender -
Otherwise,
, if that expression is valid and its type satisfiestag_invoke ( execution :: ensure_started , s )
.execution :: sender -
Otherwise:
-
Constructs a receiver
.r -
Calls
, resulting in operation stateexecution :: connect ( s , r )
, and then callsop_state
. If any of these throws an exception, it catches it and callsexecution :: start ( op_state )
.execution :: set_error ( r , current_exception ()) -
Constructs a sender
. Whens2
is connected with some receivers2
, it results in an operation stateout_r
. Once bothop_state2
and one of the receiver completion-signals has been called onexecution :: start ( op_state2 )
:r -
If
has been called, callsexecution :: set_value ( r , ts ...)
.execution :: set_value ( out_r , ts ...) -
If
has been called, callsexecution :: set_error ( r , e )
.execution :: set_error ( out_r , e ) -
If
has been called, callsexecution :: set_done ( r )
.execution :: set_done ( out_r )
-
-
If the function selected above does not eagerly start the sender
and return a sender which propagates the signals sent bys
once started, the program is ill-formed with no diagnostic required.s -
9.6.6. Sender consumers [execution.sender.consumers]
9.6.6.1. Start_detached sender consumer [execution.sender.consumer.start_detached]
-
is used to eagerly start a sender without the caller needing to manage the lifetimes of any objects.execution :: start_detached -
The name
denotes a customization point object. For some subexpressionexecution :: start_detached
, lets
beS
. Ifdecltype (( s ))
does not satisfyS
,execution :: sender
is ill-formed. Otherwise, the expressionexecution :: start_detached
is expression-equivalent to:execution :: start_detached ( s ) -
, if that expression is valid and its type istag_invoke ( execution :: start_detached , execution :: get_completion_scheduler < execution :: set_value_t > ( s ), s )
.void -
Otherwise,
, if that expression is valid and its type istag_invoke ( execution :: start_detached , s )
.void -
Otherwise:
-
Constructs a receiver
:r -
When
is called, it does nothing.set_value ( r , ts ...) -
When
is called, it callsset_error ( r , e )
.std :: terminate () -
When
is called, it does nothing.set_done ( r )
-
-
Calls
, resulting in an operation stateexecution :: connect ( s , r )
, then callsop_state
.execution :: start ( op_state )
-
If the function selected above does not eagerly start the sender
after connecting it with a receiver which ignores thes
andset_value
signals and callsset_done
on thestd :: terminate ()
signal, the program is ill-formed with no diagnostic required.set_error -
9.6.6.2. Sync_wait sender consumer [execution.sender.consumers.sync_wait]
-
andthis_thread :: sync_wait
are used to block a current thread until a sender passed into it as an argument has completed, and to obtain the values (if any) it completed with.this_thread :: sync_wait_with_variant -
The templates
andsync - wait - type
are used to determine the return types ofsync - wait - with - variant - type
andthis_thread :: sync_wait
.this_thread :: sync_wait_with_variant template < typed_sender S > using sync - wait - type = optional < typename execution :: sender_traits < remove_cvref_t < S >> :: template value_types < tuple , type_identity >> ; template < typed_sender S > using sync - wait - with - variant - type = optional < into - variant - type < S >> ; -
The name
denotes a customization point object. For some subexpressionthis_thread :: sync_wait
, lets
beS
. Ifdecltype (( s ))
does not satisfyS
, or the number of the argumentsexecution :: typed_sender
passes into thesender_traits < S >:: value_types
template parameter is not 1,Variant
is ill-formed. Otherwise,this_thread :: sync_wait
is expression-equivalent to:this_thread :: sync_wait -
, if this expression is valid and its type istag_invoke ( this_thread :: sync_wait , execution :: get_completion_scheduler < execution :: set_value_t > ( s ), s )
.sync - wait - type < S > -
Otherwise,
, if this expression is valid and its type istag_invoke ( this_thread :: sync_wait , s )
.sync - wait - type < S > -
Otherwise:
-
Constructs a receiver
.r -
Calls
, resulting in an operation stateexecution :: connect ( s , r )
, then callsop_state
.execution :: start ( op_state ) -
Blocks the current thread until a receiver completion-signal of
is called. When it is:r -
If
has been called, returnsexecution :: set_value ( r , ts ...)
.sync - wait - type < S > ( make_tuple ( ts ...)) > -
If
has been called, ifexecution :: set_error ( r , e ...)
isremove_cvref_t ( decltype ( e ))
, callsexception_ptr
. Otherwise, throwsstd :: rethrow_exception ( e )
.e -
If
has been called, returnsexecution :: set_done ( r )
.sync - wait - type < S ( nullopt ) >
-
-
-
-
The name
denotes a customization point object. For some subexpressionthis_thread :: sync_wait_with_variant
, lets
beS
. Ifdecltype (( s ))
does not satisfyS
,execution :: typed_sender
is ill-formed. Otherwise,this_thread :: sync_wait_with_variant
is expression-equivalent to:this_thread :: sync_wait_with_variant -
, if this expression is valid and its type istag_invoke ( this_thread :: sync_wait_with_variant , execution :: get_completion_scheduler < execution :: set_value_t > ( s ), s )
.sync - wait - with - variant - type < S > -
Otherwise,
, if this expression is valid and its type istag_invoke ( this_thread :: sync_wait_with_variant , s )
.sync - wait - with - variant - type < S > -
Otherwise,
.this_thread :: sync_wait ( execution :: into_variant ( s ))
-
-
Any receiver
created by an implementation ofr
andsync_wait
shall implement thesync_wait_with_variant
receiver query. The scheduler returned from the query for the receiver created by the default implementation shall return an implementation-defined scheduler that is driven by the waiting thread, such that scheduled tasks run on the thread of the caller.get_scheduler
9.7. One-way execution [execution.execute]
-
is used to create fire-and-forget tasks on a specified scheduler.execution :: execute -
The name
denotes a customization point object. For some subexpressionsexecution :: execute
andsch
, letf
beSch
anddecltype (( sch ))
beF
. Ifdecltype (( f ))
does not satisfySch
orexecution :: scheduler
does not satisfyF
,invocable <>
is ill-formed. Otherwise,execution :: execute
is expression-equivalent to:execution :: execute -
, if that expression is valid and its type istag_invoke ( execution :: execute , sch , f )
. If the function selected byvoid
does not invoke the functiontag_invoke
on an execution agent belonging to the associated execution context off
, or if it does not callsch
if an error occurs after control is returned to the caller, the program is ill-formed with no diagnostic required.std :: terminate () -
Otherwise,
.execution :: start_detached ( execution :: then ( execution :: schedule ( sch ), f ))
-