nvidia/stdexec

The stdexec::on adaptor is used for round-trip scheduling. It runs work on a target scheduler and then transfers execution back to the original scheduler that started the operation.

There are two forms:

1. on(sched, sndr): Runs the entire sndr on sched and then returns to the starting scheduler. Use this when downstream code needs to run on the caller's scheduler again. This differs from starts_on, which stays on the new scheduler.

2. on(sndr, sched, closure) (or the pipe form sndr | on(sched, closure))**: This is the "side trip" pattern. The predecessor runs on its own scheduler, the execution hops to sched for the closure, and then hops back when the closure completes. Use this for small, well-defined chunks of work (like a GPU kernel or a blocking syscall) that need a different scheduler while the rest of the pipeline remains unchanged.

// Form 1: Run entirety of sndr on sched and return
auto sched = stdexec::get_parallel_scheduler();
auto sndr  = stdexec::on(sched, stdexec::just(21)
                                  | stdexec::then([](int x){ return x*2; }));

// Form 2: Side trip pattern
auto gpu = stdexec::get_parallel_scheduler();  // pretend: GPU
auto sndr = stdexec::just(21)
      | stdexec::on(gpu, stdexec::then([](int x) { return x * 2; }));
// The then() inside runs on `gpu`, but sync_wait() sees the result on its own context.

In stdexec, domains are used to allow schedulers or algorithms to rewrite sender expressions in a pipeline during the connect phase. This is essential for specialized execution contexts, such as GPU schedulers that need to transform standard algorithms (like stdexec::then) into CUDA kernel launches, or tracing schedulers that inject span-recording code.

A domain is a tag type that implements a transform_sender static method. The framework consults this method at connect time, allowing it to replace the original sender with a rewritten version.

There are two primary customization paths:

1. Tag-type customization: Used by sender adaptor authors. You define a static transform_sender on the adaptor's tag type (e.g., foo_t). This makes the rewrite universal regardless of the active domain.
2. Domain-level customization: Used by scheduler authors. You define a custom domain type and publish it through the scheduler's environment. The framework then routes every sender in the pipeline through your domain's transform_sender first.

struct my_domain {
      template <class OpTag, class Sndr, class Env>
      static auto transform_sender(OpTag, Sndr&& sndr, Env const&)
        /* -> some-new-sender-or-the-same-sender */;
    };

These adaptors allow you to handle errors in the error channel of a sender.

stdexec::upon_error (Synchronous Recovery)

Use this when your recovery logic returns a value. It consumes the error channel; the resulting sender will no longer complete via set_error (unless the recovery callable itself throws).

stdexec::let_error (Asynchronous Recovery)

Use this when your recovery logic (e.g., a retry or fallback fetch) returns a sender. This allows the recovery step to be an asynchronous operation.

Note: If the predecessor succeeds or is cancelled, these adaptors are no-ops and the completion is forwarded unchanged.

// upon_error example (returns a value)
auto sndr = stdexec::just_error(std::error_code{ENOENT, std::system_category()})
              | stdexec::upon_error([](std::error_code) { return -1; });

// let_error example (returns a sender)
auto retry_async = [](std::error_code) { return stdexec::just(7); };
auto sndr = stdexec::just_error(std::error_code{ENOENT, std::system_category()})
              | stdexec::let_error(retry_async);

Consumers are the mechanism that actually executes a pipeline. A sender is merely a description of work; it does nothing until it is connected to a consumer.

When choosing a consumer, consider two axes:

1. Does the caller need to wait for the result?
2. Who owns the lifetime of the operation state?

Lifetime Ownership:

• sync_wait / sync_wait_with_variant: The caller's stack frame owns the state.
• start_detached: The operation owns itself (heap-allocated).
• spawn / spawn_future: The async_scope owns the operation.

A scheduler in stdexec is a value-typed handle to an execution context. To satisfy the stdexec::scheduler concept, you must implement three structural pieces in a bottom-up fashion:

1. Operation State: A type that holds the receiver and implements start(). It must opt into the operation state concept using using operation_state_concept = stdexec::operation_state_tag;. The start() method must be noexcept and return void.
2. Schedule-Sender: The type returned by the scheduler's schedule() method. It must implement connect(R rcvr) which returns the operation state. It must also define completion_signatures (e.g., stdexec::completion_signatures<stdexec::set_value_t()>).
3. Scheduler: A handle type that provides a schedule() member function returning the schedule-sender. It must be equality-comparable, copy-constructible, and nothrow-move-constructible.

An 'inline scheduler' is the simplest implementation where start() calls stdexec::set_value directly on the calling thread, completing synchronously.

// 1. Operation state
template <stdexec::receiver R>
struct simple_inline_opstate {
  using operation_state_concept = stdexec::operation_state_tag;
  R rcvr_;
  explicit simple_inline_opstate(R rcvr) noexcept : rcvr_(std::move(rcvr)) {}
  simple_inline_opstate(simple_inline_opstate&&) = delete;
  void start() noexcept {
    stdexec::set_value(std::move(rcvr_));
  }
};

// 2. Schedule-sender
struct simple_inline_schedule_sender {
  using sender_concept = stdexec::sender_tag;
  using completion_signatures = stdexec::completion_signatures<stdexec::set_value_t()>;

  template <stdexec::receiver R>
  auto connect(R rcvr) const noexcept {
    return simple_inline_opstate<R>{std::move(rcvr)};
  }
};

// 3. Scheduler
struct simple_inline_scheduler {
  auto schedule() const noexcept {
    return simple_inline_schedule_sender{};
  }
  bool operator==(simple_inline_scheduler const&) const noexcept = default;
};