Difference between revisions of "cpp/execution"

Latest revision as of 19:26, 11 November 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.

[edit] 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.

[edit] Library utilities

[edit] Concepts

[edit] Schedulers

[edit] Senders

[edit] Receivers

[edit] Operation states

[edit] Utility components

[edit] Execution contexts

[edit] Execution domains

[edit] Forward progress guarantee

[edit] Environments

[edit] Queries

[edit] Completion signatures

[edit] Coroutine utility

[edit] Core operations

[edit] Operation state

[edit] Completion functions

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

[edit] Sender algorithms

[edit] 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:

[edit] Pipeable sender adaptors

[edit] 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:

[edit] Sender consumers

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

[edit] 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

[edit] See also