Execution control library (since C++26)

The Execution control 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.
• A sender has an associated queryable object (below) known as sender attributes that describes various characteristics of the sender and of the asynchronous operation(s) it produces.

• 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 queryable object (below) 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 states lifetime cannot end before the async operation is complete, and its address must be stable.

• Execution Agent: An entity such as a thread that may perform work in parallel with other execution agents

• Implementations or users can introduce other kinds of agents such as processes or thread-pool tasks.

• Execution Resource: Also known as execution context, a program entity that manages a (possibly dynamic) set of execution agents.

• The currently active thread, a system-provided thread pool, and uses of an API associated with an external hardware accelerator are all examples of execution resources.

• Scheduler: A lightweight handle to an execution resource for scheduling work onto that resource.

• A scheduler is a factory for a sender that completes its receiver from an execution agent owned by the execution resource.

• Queryable Object: A read-only collection of key/value pair where each key is a customization point object known as a query object.

• A query is an invocation of a query object with a queryable object as its first argument and a (possibly empty) set of additional arguments. A query imposes syntactic and semantic requirements on its invocations.

Library utilities

Concepts

Schedulers

Senders

Receivers

Operation states

Asynchronous scopes

Utility components

Execution contexts

Execution domains

Forward progress guarantee

Environments

Queries

Completion signatures

Coroutine utility

Asynchronous scopes

Parallel scheduler

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.

Notes

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

External links