Difference between revisions of "cpp/execution"

Revision as of 05:37, 13 October 2024

The Execution library provides a framework for managing asynchronous execution on generic execution resources.

The library aims to provide vocabulary types for asynchronous 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 passed to the std::execution::connect function.
• 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

Concepts

Schedulers

Senders

Receivers

Operation states

Utility components

Execution contexts

Execution domains

Forward progress guarantee

Environments

Queries

Completion signatures

Coroutine utility

Core operations

Operation state

Completion functions

These functions are called by senders to announce the completion of the work to their receivers.

Sender algorithms

Sender factories

A sender factory is a function that returns a sender and whose parameters have types for which the sender concept is false.

The following are sender factories:

Pipeable sender adaptors

Sender adaptors

A sender adaptor is a function returning a sender whose parameters include at least one whose type satisfies the sender concept, and for which the returned sender is a parent sender of the adaptor function's sender arguments.

The following are sender adaptors:

Sender consumers

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

Example

#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)
        {
            return std::puts(msg.c_str());
        });
 
    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;
}

hello world

See also