C++26: dispatcher factories, adapters and consumers of std::execution

Structure of transmitters as well as explanation for executing inclusive scans asynchronously std::execution I have already covered this in my previous posts. Now I will focus my attention on three types of channels std::execution Offers: Factories, Adapters and Consumers.

Advertisement

The following information about the channels comes mainly from the proposal P2300R10I will try to summarize the material here a little more.

sender factory

Sender Factory is an algorithm, Which does not take senders as parameters and returns the sender.

execution::schedule

 execution::sender auto schedule(
    execution::scheduler auto scheduler
);

Returns a dispatcher that starts with the given scheduler.

execution::just

execution::sender auto just(
    auto ...&& values
);

Returns a sender that sends the provided value.

execution::just_error

execution::sender auto just_error(
    auto && error
);

Functional Programming and more: BOB conference program available

Returns a send that ends with a specific error.

execution::just_stopped

execution::sender auto just_stopped();

Returns a dispatcher that can be invoked immediately by calling set_stopped The recipient’s work is complete.

execution::read_env

execution::sender auto read_env(auto tag);

Returns a transmitter that reads the receiver’s environment and the current value associated with it tag-Environmental value attached. It then sends the read value back to the receiver through the value channel. read_env(get_scheduler) For example, a sender who asks the recipient about the current offered scheduler and sends set_value-A completion signal is sent from the receiver.

This can be useful when planning nested, dependent tasks. The following dispatcher pulls the current scheduler into the value channel and then plans further work on it.

transmitter adapter

A sender adapter is an algorithm that takes one or more senders as parameters and returns a sender.

transmitter adapters are lazy. Sender consumers like this_thread::sync_wait Start the transmitter.

execution::continues_on

execution::sender auto continues_on(
    execution::sender auto input,
    execution::scheduler auto scheduler
);

Returns a dispatcher that describes the transition from the input dispatcher’s execution agent to the target scheduler’s execution agent.

execution::then

Returns a sender that describes the task diagram described by the input sender. In doing so, it adds a node to call the given function with the values ​​sent by the input sender as arguments.

execution::upon_*

upon_error And upon_stopped Are then Same, but during then Values ​​sent by input sender work upon_error with errors, and upon_stopped A call is made when a “paused” signal is sent.

A illustrative example For then, upon_error And upon_stopped prototype library stdexec,

The following example shows an HTTP request handler.

/*
 * Copyright (c) 2022 Lucian Radu Teodorescu
 *
 * Licensed under the Apache License Version 2.0 with LLVM Exceptions
 * (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 *
 *   https://llvm.org/LICENSE.txt
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
 // Handler for the "classify" request type
ex::sender auto handle_classify_request(const http_request& req) {
  return
    // start with the input buffer
    ex::just(req)
    // extract the image from the input request
    | ex::then(extract_image)
    // analyze the content of the image and classify it
    // we are doing the processing on the same thread
    | ex::then(do_classify)
    // handle errors
    | ex::upon_error(on_classification_error)
    // handle cancellation
    | ex::upon_stopped(on_classification_cancelled)
    // transform this into a response
    | ex::then(to_response)
    // done
    ;
}

Function extracts images and input ex::senderObject that represents an asynchronous operation that can contain other operations.

function takes a constant reference to a http_request reqThe processing pipeline starts from ex::just(req)-Function that creates a sender starting from the input buffer of an HTTP request.

The pipeline then uses ex::then– The act of serializing a series of operations. first process extract_imageExtracts an image from the input request. The next process classifies the content of the extracted image. This processing takes place in a single thread.

Error handling is done using the function ex::upon_error Is integrated into the pipeline providing function on_classification_error To handle errors that may occur during the classification process.

the same thing will happen ex::upon_stopped Used to handle the termination of the operation, where the function on_classification_cancelled is specified.

function at the end to_response Used to convert the classification result into an HTTP response. This conversion also happens with ex::then-Celebration.

This code demonstrates a composable and asynchronous processing pipeline for handling HTTP requests, classifying images, and handling errors and aborts.

execution::starts_one

execution::sender auto starts_on(
    execution::scheduler auto sched,
    execution::sender auto snd
);

This dispatcher adapter modifies the execution resource on which the dispatcher runs. It does not adjust the channel.

What will happen next?

std::execution There are also other transmitter adapters available, which I will introduce in my next post: execution::let_*, execution::into_variant, execution::stopped_as_optional, execution::stopped_as_error, execution::bulk, execution::split And execution::when_all.

(map)