Difference between revisions of "cpp/execution"

Revision as of 22:05, 11 February 2024

Note This is a planned extension to the <execution> (C++17), see <experimental/execution>.

Draft The functionality described on this page is a draft, based on the latest revision of P2300, targeting C++26.

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 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 they are passed to the std::execution::connect customization point.
• The result of connecting a sender and a receiver is an operation state.
• Work is not enqueued for execution until “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

Senders

Sender factories

A sender factory takes a non-sender (function/data) and returns a sender.

A sender with no completion schedulers is an “open-ended” operation, that can be used in the pipe. All the following senders are created without a completion scheduler.

Sender adaptors

A sender adaptor takes a sender and returns a sender.

The returned sender represents the task graph described by the input sender, with an additional node containing the functionality added by the adaptor.

Adaptors for single-shot and multi-shot senders

Adaptors for multi-shot senders

Sender consumers

A sender consumer is an algorithm that takes one or more senders as parameters and connects them. It does not return a sender.

Eager execution

Allows a fire-and-forget eager one-way submission of an invocable to a scheduler.

Example

#include <iostream>
#include <stdexec/execution.hpp>
#include <thread>
 
stdexec::run_loop loop;
std::thread worker([]{ loop.run(); });
 
int main()
{
    using namespace std::literals;
 
    auto hello = stdexec::just("hello work"s);
    auto work = hello | stdexec::then([](auto msg)
    {
        std::cout << msg << '\n';
        return 0;
    });
 
    const auto [result] =
        stdexec::sync_wait(stdexec::on(loop.get_scheduler(), std::move(work))).value();
    loop.finish();
    worker.join();
    return result;
}

hello work

See also