Execution control library (since C++26) (original) (raw)

Execution control library

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.

Contents

• 1 Library-wide definitions
• 2 Library utilities
  • 2.1 Concepts
    * 2.1.1 Schedulers
    * 2.1.2 Senders
    * 2.1.3 Receivers
    * 2.1.4 Operation states
  • 2.2 Utility components
    * 2.2.1 Execution contexts
    * 2.2.2 Execution domains
    * 2.2.3 Forward progress guarantee
    * 2.2.4 Environments
    * 2.2.5 Queries
    * 2.2.6 Completion signatures
    * 2.2.7 Coroutine utility
  • 2.3 Core operations
    * 2.3.1 Operation state
    * 2.3.2 Completion functions
  • 2.4 Sender algorithms
    * 2.4.1 Sender factories
    * 2.4.2 Pipeable sender adaptors
    * 2.4.3 Sender adaptors
    * 2.4.4 Sender consumers
  • 2.5 Example
  • 2.6 See also

[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

A version of this example is available on godbolt.org, where it uses stdexec, an experimental reference implementation of std::execution.

#include #include #include #include #include using namespace std::literals;   int main() { std::execution::run_loop loop;   std::jthread worker(& 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( 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; }

Output:

[edit] See also

| | runs a function asynchronously (potentially in a new thread) and returns a std::future that will hold the result (function template) [edit] | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |