{"id":10444,"date":"2024-12-16T11:25:19","date_gmt":"2024-12-16T11:25:19","guid":{"rendered":"https:\/\/www.modernescpp.com\/?p=10444"},"modified":"2025-07-04T16:06:05","modified_gmt":"2025-07-04T16:06:05","slug":"stdexecution-sender","status":"publish","type":"post","link":"https:\/\/www.modernescpp.com\/index.php\/stdexecution-sender\/","title":{"rendered":"std::execution: Sender"},"content":{"rendered":"\n

std::execution <\/code>offers three types of senders: factories, adapters, and consumers. I’ll take a closer look at these today.<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

Most of the following content is from proposal P2300R10<\/a>. I will try to represent it more concisely.<\/p>\n\n\n\n

<\/span>Sender Factory<\/span><\/h2>\n\n\n\n

A sender factory is an algorithm <\/em>that takes no senders as parameters and returns a sender.<\/p>\n\n\n\n

<\/span>execution::schedule <\/code><\/span><\/h3>\n\n\n\n
execution::<\/span>sender auto<\/span> schedule(\n    execution::<\/span>scheduler auto<\/span> scheduler\n);\n<\/pre><\/div>\n\n\n\n
Returns a sender, which starts on the provided scheduler.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
<\/span>execution::just<\/code><\/span><\/h3>\n\n\n\n
execution::<\/span>sender auto<\/span> just(\n    auto<\/span> ...&&<\/span> values\n);\n<\/pre><\/div>\n\n\n\n
Returns a sender, which sends the provided values.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
<\/span>execution::just_error <\/code> <\/span><\/h3>\n\n\n\n
execution::<\/span>sender auto<\/span> just_error(\n    auto<\/span> &&<\/span> error\n);\n<\/pre><\/div>\n\n\n\n
Returns a sender, which completes with the specific error.<\/p>\n\n\n\n
<\/span>execution::just_stopped<\/code><\/span><\/h3>\n\n\n\n
execution::<\/span>sender auto<\/span> just_stopped();\n<\/pre><\/div>\n\n\n\n

Returns a sender, which completes immediately by calling the receiver\u2019s set_stopped<\/code>. <\/p>\n\n\n\n
<\/span>execution::read_env<\/code><\/span><\/h3>\n\n\n\n
execution::<\/span>sender auto<\/span> read_env(auto<\/span> tag);\n<\/pre><\/div>\n\n\n\n

Returns a sender that reaches into a receiver\u2019s environment and pulls out the current value associated with the environment value tag<\/code>. It then sends the value read back to the receiver through the value channel. For instance, read_env(get_scheduler)<\/code> is a sender that asks the receiver for the currently suggested scheduler<\/code> and passes it to the receiver\u2019s set_value<\/code> completion-signal.<\/p>\n\n\n\n
This can be useful when scheduling nested dependent work. The following sender pulls the current scheduler into the value channel and then schedules more work onto it.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
<\/span>Sender Adaptor <\/span><\/h2>\n\n\n\n
A sender adaptor is an algorithm that takes one or more senders as parameters and returns a sender.<\/p>\n\n\n\n
Sender adaptors are lazy. Sender consumers such as this_thread::sync_wait <\/code>start senders.<\/p>\n\n\n\n
<\/span>execution::continues_on<\/code><\/span><\/h3>\n\n\n\n
execution::<\/span>sender auto<\/span> continues_on(\n    execution::<\/span>sender auto<\/span> input,\n    execution::<\/span>scheduler auto<\/span> scheduler\n);\n<\/pre><\/div>\n\n\n\n
Returns a sender describing the transition from the execution agent of the input sender to the execution agent of the target scheduler.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
<\/span>execution::then<\/code><\/span><\/h3>\n\n\n\n
execution::<\/span>sender auto<\/span> then(\n    execution::<\/span>sender auto<\/span> input,\n    std::<\/span>invocable<<\/span>values-<\/span>sent-<\/span>by(input)...><\/span> function\n);\n<\/pre><\/div>\n\n\n\n
then<\/code> returns a sender describing the task graph described by the input sender, with an added node of invoking the provided function with the values sent by the input sender as arguments.<\/p>\n\n\n\n
\"\"<\/figure>\n\n\n\n
<\/span>execution::upon_*<\/code><\/span><\/h3>\n\n\n\n
execution::<\/span>sender auto<\/span> upon_error(\n    execution::<\/span>sender auto<\/span> input,\n    std::<\/span>invocable<<\/span>errors-<\/span>sent-<\/span>by(input)...><\/span> function\n);\n\nexecution::<\/span>sender auto<\/span> upon_stopped(\n    execution::<\/span>sender auto<\/span> input,\n    std::<\/span>invocable auto<\/span> function\n);\n<\/pre><\/div>\n\n\n\n
upon_error<\/code> and upon_stopped<\/code> are similar to then<\/code>, but where then<\/code> works with values sent by the input sender, upon_error<\/code> works with errors, and upon_stopped<\/code> is invoked when the “stopped” signal is sent.<\/p>\n\n\n\n
A nice example about then,upon_error<\/code>, and upon_stopped<\/code> has the prototype library stdexec<\/a>.<\/p>\n\n\n\n
The following example shows an HTTP request handler.(https:\/\/github.com\/NVIDIA\/stdexec\/blob\/main\/examples\/server_theme\/then_upon.cpp#L151)<\/a><\/p>\n\n\n\n
\/*<\/span>\n * Copyright (c) 2022 Lucian Radu Teodorescu<\/span>\n *<\/span>\n * Licensed under the Apache License Version 2.0 with LLVM Exceptions<\/span>\n * (the "License"); you may not use this file except in compliance with<\/span>\n * the License. You may obtain a copy of the License at<\/span>\n *<\/span>\n *   https:\/\/llvm.org\/LICENSE.txt<\/span>\n *<\/span>\n * Unless required by applicable law or agreed to in writing, software<\/span>\n * distributed under the License is distributed on an "AS IS" BASIS,<\/span>\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.<\/span>\n * See the License for the specific language governing permissions and<\/span>\n * limitations under the License.<\/span>\n *\/<\/span>\n \/\/ Handler for the "classify" request type<\/span>\n\nex::<\/span>sender auto<\/span> handle_classify_request(const<\/span> http_request&<\/span> req) {\n  return<\/span>\n    \/\/ start with the input buffer<\/span>\n    ex::<\/span>just(req)\n    \/\/ extract the image from the input request<\/span>\n    |<\/span> ex::<\/span>then(extract_image)\n    \/\/ analyze the content of the image and classify it<\/span>\n    \/\/ we are doing the processing on the same thread<\/span>\n    |<\/span> ex::<\/span>then(do_classify)\n    \/\/ handle errors<\/span>\n    |<\/span> ex::<\/span>upon_error(on_classification_error)\n    \/\/ handle cancellation<\/span>\n    |<\/span> ex::<\/span>upon_stopped(on_classification_cancelled)\n    \/\/ transform this into a response<\/span>\n    |<\/span> ex::<\/span>then(to_response)\n    \/\/ done<\/span>\n    ;\n}\n<\/pre><\/div>\n\n\n\n
The function extracts images and returns an ex::sender<\/code> object, representing an asynchronous operation that can be composed of other operations.<\/p>\n\n\n\n
The function takes a constant reference to an http_request req<\/code>. The processing pipeline begins with the ex::just(req)<\/code> function, creating a sender that starts with the HTTP request’s input buffer.<\/p>\n\n\n\n
Error handling is incorporated into the pipeline using the ex::upon_error <\/code>function, which specifies the on_classification_error<\/code> function to handle any errors that occur during the classification process. <\/p>\n\n\n\n
The pipeline then uses the ex::then <\/code>function to chain a series of operations. The first operation, extract_image,<\/code> extracts the image from the input request. The next operation,  do_classify<\/code>, classifies the extracted image’s content. This processing is done on the same thread.<\/p>\n\n\n\n
Similarly, the ex::upon_stopped<\/code> function is used to handle the cancellation of the operation, specifying the on_classification_cancelled <\/code>function.<\/p>\n\n\n\n
Finally, the to_response function is used to transform the classification result into an HTTP response. This transformation is also done using the ex::then<\/code> function.<\/p>\n\n\n\n
This sender adaptor changes the execution resource on which the sender runs. It does not adapt the sender. <\/p>\n\n\n\n
This code demonstrates a composable and asynchronous processing pipeline for gracefully handling HTTP requests, classifying images, and errors and cancellations.<\/p>\n\n\n\n
<\/span>execution::starts_on<\/code><\/span><\/h3>\n\n\n\n
execution::<\/span>sender auto<\/span> starts_on(\n    execution::<\/span>scheduler auto<\/span> sched,\n    execution::<\/span>sender auto<\/span> snd\n);\n<\/pre><\/div>\n\n\n\n
<\/span>What’s Next?<\/span><\/h2>\n\n\n\n
std::execution<\/code> has more sender adaptors to offer: execution::let_*,<\/code> execution::into_variant, execution::stopped_as_optional<\/code>,  execution::stopped_as_error<\/code>, execution::bulk<\/code>,  execution::split<\/code>, and execution::when_all<\/code>.<\/p>\n\n\n\n
<\/p>\n","protected":false},"excerpt":{"rendered":"
std::execution offers three types of senders: factories, adapters, and consumers. I’ll take a closer look at these today. Most of the following content is from proposal P2300R10. I will try to represent it more concisely. Sender Factory A sender factory is an algorithm that takes no senders as parameters and returns a sender. execution::schedule execution::sender […]<\/p>\n","protected":false},"author":21,"featured_media":10445,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[559],"tags":[561],"class_list":["post-10444","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-c26-blog","tag-execution"],"_links":{"self":[{"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/posts\/10444","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/users\/21"}],"replies":[{"embeddable":true,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/comments?post=10444"}],"version-history":[{"count":28,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/posts\/10444\/revisions"}],"predecessor-version":[{"id":10514,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/posts\/10444\/revisions\/10514"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/media\/10445"}],"wp:attachment":[{"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/media?parent=10444"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/categories?post=10444"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.modernescpp.com\/index.php\/wp-json\/wp\/v2\/tags?post=10444"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}