View source for cpp/execution

{{title|Execution library}}
{{cpp/execution/navbar}}

The Execution library provides a framework for managing asynchronous execution on generic execution resources, targeting the standard C++ library.

The library aims to provide vocabulary types for async operations and to allow the construction of task execution graphs in a simple, composable way.

==Library-wide definitions==

* '''Sender''': A description of asynchronous work to be sent for execution. Produces an operation state (below).
:* Senders asynchronously “send” their results to listeners called “receivers” (below).
:* Senders can be composed into '''task graphs''' using generic algorithms.
:* '''Sender factories and adaptors''' are generic algorithms that capture common async patterns in objects satisfying the {{lc|sender}}<!--{{lconcept|sender}}--> concept.
* '''Receiver''': A generalized callback that consumes or “receives” the asynchronous results produced by a sender.
:* Receivers have three different “channels” through which a sender may propagate results: success, failure, and canceled, so-named “value”, “error”, and “stopped”.
:* Receivers provide an extensible execution environment: a set of key/value pairs that the consumer can use to parameterize the asynchronous operation.
* '''Operation State''': An object that contains the state needed by the asynchronous operation. 
:* A sender and receiver are connected when passed to the {{lc|std::execution::connect}} function.
:* The result of connecting a sender and a receiver is an operation state. 
:* Work is not enqueued for execution until “{{tt|start}}” is called on an operation state.
:* Once started, the operation state’s lifetime cannot end before the async operation is complete, and its address must be stable.
* '''Scheduler''': A lightweight handle to an execution context. 
:* An execution context is a source of asynchronous execution such as a thread pool or a GPU stream. 
:* A scheduler is a factory for a sender that completes its receiver from a thread of execution owned by the execution context.

==Library utilities==

===Schedulers===
{{dsc begin}}
{{dsc header|execution}}
{{dsc inc|cpp/execution/dsc scheduler}}
{{dsc end}}

===Execution Contexts===
{{dsc begin}}
{{dsc header|execution}}
{{dsc inc|cpp/execution/dsc run_loop}}
{{dsc end}}

===Senders===

====Sender factories====
A sender factory is a function that returns a sender and whose parameters have types for which the {{lc|sender}}<!--{{lconcept|sender}}--> concept is {{lc|false}}.

The following are sender factories:

{{dsc begin}}
{{dsc header|execution}}
{{dsc namespace|std::execution}}
{{dsc inc|cpp/execution/dsc just}}
{{dsc inc|cpp/execution/dsc just_error}}
{{dsc inc|cpp/execution/dsc just_stopped}}
{{dsc inc|cpp/execution/dsc read}}
{{dsc inc|cpp/execution/dsc schedule}}
{{dsc end}}

====Sender adaptors====
A sender adaptor is a function returning a sender whose parameters include at least one whose type satisfies the {{lc|sender}}<!--{{lconcept|sender}}--> concept, and for which the returned sender is a parent sender of the adaptor function's sender arguments.

The following are sender adaptors:

{{dsc begin}}
{{dsc header|execution}}
{{dsc namespace|std::execution}}
{{dsc inc|cpp/execution/dsc bulk}}
{{dsc inc|cpp/execution/dsc ensure_started}}
{{dsc inc|cpp/execution/dsc into_variant}}
{{dsc inc|cpp/execution/dsc let_error}}
{{dsc inc|cpp/execution/dsc let_value}}
{{dsc inc|cpp/execution/dsc let_stopped}}
{{dsc inc|cpp/execution/dsc on}}
{{dsc inc|cpp/execution/dsc split}}
{{dsc inc|cpp/execution/dsc stopped_as_error}}
{{dsc inc|cpp/execution/dsc stopped_as_optional}}
{{dsc inc|cpp/execution/dsc then}}
{{dsc inc|cpp/execution/dsc transfer}}
{{dsc inc|cpp/execution/dsc upon_error}}
{{dsc inc|cpp/execution/dsc upon_stopped}}
{{dsc inc|cpp/execution/dsc when_all}}
{{dsc end}}

===Sender consumers===
A sender consumer is an algorithm that takes one or more senders as parameters and that does not return a sender.

The following are sender consumers:

{{dsc begin}}
{{dsc header|execution}}
{{dsc namespace|std::execution}}
{{dsc inc|cpp/execution/dsc start_detached}}
{{dsc h2|Functions managing the current thread}}
{{dsc header|execution}}
{{dsc namespace|std::this_thread}}
{{dsc inc|cpp/thread/dsc sync_wait}}
{{dsc end}}

===Eager execution===
Allows a fire-and-forget eager submission of an invocable to a scheduler.

{{dsc begin}}
{{dsc header|execution}}
{{dsc namespace|std::execution}}
{{dsc inc|cpp/execution/dsc execute}}
{{dsc end}}

===Example===
{{example
|A version of this example is available on [https://godbolt.org/z/vdxGsxsKd godbolt.org],  where it uses [https://github.com/NVIDIA/stdexec stdexec], an experimental reference implementation of {{lc|std::execution}}.
|code=
#include <cstdio>
#include <execution>
#include <string>
#include <thread>
#include <utility>
using namespace std::literals;

int main()
{
    std::execution::run_loop loop;

    std::jthread worker([&](std::stop_token st)
    {
        std::stop_callback cb{ st, [&]{ loop.finish(); }<!---->};
        loop.run();
    });
    
    std::execution::sender auto hello = std::execution::just("hello world"s);
    std::execution::sender auto print
        = std::move(hello)
        {{!}} std::execution::then([](std::string msg)
        {
            std::puts(msg.c_str());
            return 0;
        });
    
    std::execution::scheduler auto io_thread = loop.get_scheduler();
    std::execution::sender auto work = std::execution::on(io_thread, std::move(print));
    
    auto [result] = std::this_thread::sync_wait(std::move(work)).value();
    
    return result;
}
|output=
hello world
}}

===See also===
{{dsc begin}}
{{dsc inc|cpp/thread/dsc async}}
{{dsc end}}

{{langlinks|zh}}