1 Introduction

This paper proposes to add three new sender adaptor algorithms to the std::execution namespace, targetting C++26: finally, write_env, and unstoppable. These adaptors were originally proposed as part of [P3175R0] but have been split out into their own paper so that the higher priority items in P3175 can advance more quickly.

2 Executive Summary

Below are the specific changes this paper proposes:

1. Add a new uncustomizable adaptor write_env for writing values into the receiver’s execution environment, and rename read to read_env (“read” being too vague and something of a land-grab). write_env is used in the implementation of the new on algorithm ([P3175R1]) and can simplify the specification of the let_ algorithms.

2. Add an uncustomizable unstoppable adaptor that is a trivial application of write_env: it sets the current stop token in the receiver’s environment to a never_stop_token. unstoppable is used in the re-specification of the schedule_from algorithm.

3. Generalize the specification for schedule_from to take two senders instead of a sender and a scheduler, name it finally, and make it uncustomizable. Specify the default implementation of schedule_from(sch, snd) as finally(snd, unstoppable(schedule(sch))).

3 Description

[P3175R0] proposes some changes to the std::execution::on algorithm, the specification of which was made simpler by the addition of some additional adaptors. Those adaptors were general and useful in their own right, so P3175R0 suggested they be added to std::execution proper. The conservative approach is to keep them exposition-only, and [P3175R1] proposes just that.

The author still feels like those adaptors, which were removed from P3175, are worthy of standardization. This paper proposes adding them.

The adaptors in question are as follows:

3.1 write_env

A receiver has an associated “execution environment”, which is an unstructured, queryable key/value store. It is used to pass implicit parameters from parent operations to their children. It is occasionally useful for a sender adaptor to explicitly mutate the key/value store so that child operations see different values for environment queries. The write_env sender adaptor is used for that purpose.

write_env is a customization point object, although it is not actually customizable. It accepts a sender sndr and an execution environment env, and it returns a new sender that stores sndr and env. When that sender is connected to a receiver rcvr, it returns the result of connecting sndr with a receiver that adapts rcvr. The environment of that adapted receiver is the result of joining env with rcvr’s environment. The two environments are joined such that, when the joined environment is queried, env is queried first, and if env doesn’t have a value for that query, the result of get_env(rcvr) is queried.

3.1.1 Example: write_env

One example of where write_env might be useful is to specify an allocator to be used by child operations. The code might look like this:

// Turn a query object and a value into a queryable environment:
template <class Query, class Value>
struct with : Query {
  Value value;
  auto query(Query) const { return value; }
};

// Adapts a sender so that it can use the given allocator:
struct with_allocator_t {
  template <std::execution::sender Sndr, class Alloc>
  auto operator()(Sndr sndr, Alloc alloc) const {
    return std::execution::write_env(sndr, with{std::get_allocator, alloc});
  }
};

constexpr with_allocator_t with_allocator{};

The with_allocator adaptor might be used to parameterize senders produced by a third-party library as follows:

namespace ex = std::execution;

// This returns a sender that does some piece of asynchronous work
// created by a third-party library, but parameterized with a custom
// allocator.
ex::sender auto make_async_work_with_alloc() {
  ex::sender auto work = third_party::make_async_work();

  return with_allocator(std::move(work), custom_allocator());
}

The sender returned by third_party::make_async_work might query for the allocator and use it to do allocations:

namespace third_party {
  namespace ex = std::execution;

  // A function that returns a sender that generates data on a special
  // execution context, populate a std::vector with it, and then completes
  // by sending the vector.
  constexpr auto _populate_data_vector = 
    []<class Allocator>(Allocator alloc) {
      // Create an empty vector of ints that uses a specified allocator.
      using IntAlloc = std::allocator_traits<Allocator>::template rebind_alloc<int>;
      auto data = std::vector<int, IntAlloc>{IntAlloc{std::move(alloc)}};

      // Create some work that generates data and fills in the vector.
      auto work = ex::just(std::move(data))
        | ex::then([](auto data) {
            // Generate the data and fill in the vector:
            data.append_range(third_party::make_data())
            return data;
          });

      // Execute the work on a special third_party execution context:
      // (This uses the `on` as specified in P3175.)
      return ex::on(third_party_scheduler(), std::move(work));
    };

  // A function that returns the sender produced by `_populate_data_vector`,
  // parameterized by an allocator read out of the receiver's environment.
  ex::sender auto make_async_work() {
    return ex::let_value(
      // This reads the allocator out of the receiver's execution environment.
      ex::read_env(std::get_allocator),
      _populate_data_vector
    );
  }
}

3.2 unstoppable

The unstoppable sender adaptor is a trivial application of write_env that modifies a sender so that it no longer responds to external stop requests. That can be of critical importance when the successful completion of a sender is necessary to ensure program correctness, e.g., to restore an invariant.

The unstoppable adaptor might be implemented as follows:

inline constexpr struct unstoppable-t {
  template <sender Sndr>
  auto operator()(Sndr sndr) const {
    return write_env(std::move(sndr), never_stop_token());
  }

  auto operator()() const {
    return write_env(never_stop_token());
  }
} unstoppable {};

The section describing the finally adaptor will give a motivating example that makes use of unstoppable.

3.3 finally

The C++ language lacks direct support for asynchronous destruction; that is, there is no way to say, “After this asynchronous operation, unconditionally run another asynchronous operation, regardless of how the first one completes.” Without this capability, there is no native way to have “async RAII”: the pairing the asynchronous acquisition of a resource with its asynchronous reclaimation.

The finally sender adaptor captures the “async RAII” pattern in the sender domain. finally takes two senders. When connected and started, the finally sender connects and starts the first sender. When that sender completes, it saves the asynchronous result and then connects and starts the second sender. If the second sender completes successfully, the results from the first sender are propagated. Otherwise, the results from the second sender are propagated.

There is a sender in [P2300R9] very much like finally as described above: schedule_from. The only meaningful difference is that in schedule_from, the “second sender” is always the result of calling schedule on a scheduler. With finally, the default implementation of schedule_from is trivial:

template <sender Sndr, scheduler Sched>
auto default-schedule-from-impl(Sndr sndr, Sched sched) {
  return finally(std::move(sndr), unstoppable(schedule(sched)));
}

This paper proposes repurposing the wording of schedule_from to specify finally, and then specifying schedule_from in terms of finally and unstoppable.

3.3.1 Example: finally

In the following example, some asynchronous work must temporarily break a program invariant. It uses unstoppable and finally to restore the invariant.

  namespace ex = std::execution;

  ex::sender auto break_invariants(auto&... values);
  ex::sender auto restore_invariants(auto&... values);

  // This function returns a sender adaptor closure object. When applied to
  // a sender, it returns a new sender that breaks program invariants,
  // munges the data, and restores the invariants.
  auto safely_munge_data( ) {
    return ex::let_value( [](auto&... values) {
        return break_invariants(values...)
          | ex::then(do_munge) // the invariants will be restored even if `do_munge` throws
          | ex::finally(ex::unstoppable(restore_invariants(values...)));
    } );
  }

  auto sndr = ...;
  scope.spawn( sndr | safely_munge_data() ); // See `counting_scope` from P3149R2

4 Discussion

There are a number of design considerations for the finally algorithm. The following questions have been brought up during LEWG design review:

4.1 Should finally apply unstoppable by default to its second argument?

The observation was made that, since finally will often be used to do some cleanup operation or to restore an invariant, that operation should not respond to external stop requests, so unstoppable should be the default. It’s a reasonable suggestion. Of course, there would need to be a way to override the default and allow the cleanup action to be canceled, and it isn’t clear what the syntax for that would be. Another adaptor called stoppable_finally?

It is worth nothing that unstoppable has uses besides finally, so it arguably should exist regardless of what the default behavior of finally is. Given that unstoppable should exist anyway, and that its behavior is pleasantly orthogonal to finally, the authors decided to keep them separate and let users combine them how they like.

4.2 Is there a different design that better captures the “async RAII” intent?

Undoubtedly, the answer is “yes.” There are probably several such designs. One design that has been explored by Kirk Shoop is the so-called “async resource”.

In Kirk’s design, an async resource has three basis operations: open, run, and close, each of which is asynchronous; that is, they all return senders. When open completes, it does so with a handle to the resource. The handle lets you interact with the resource. Calling close on the handle ends the lifetime of the async resource.

Some resources, like a resource-ified run_loop, need to be driven in order to function. That is what the run operation is for. run and open can be started simultaneously. In the case of a run_loop resource, run drives the loop, open returns a run_loop scheduler that also implements close, and close would call finish on the run_loop. The run sender will complete when all the work queued on the run_loop has finished.

Similarly, an async scope a la [P3149R2]’s counting_scope can be given the async resource treatment. Multiple such async resources can be used in tandem, as in the following example:

// In this example, run_loop and counting_scope implement the async
// resource concept.
run_loop loop;
counting_scope scope;

auto use = ex::when_all(ex::open(loop), ex::open(scope))
         | ex::let_value([](auto h_loop, auto h_scope) {
             // The lifetimes of the async resources have begun when
             // `open` completes.

             // spawn 1000 tasks on the run_loop in the counting_scope.
             for (int i = 0; i < 1000; ++i) {
               auto work = ex::just() | ex::then([=]{ do_work(i);});
               h_scope.spawn(ex::on(h_loop, std::move(work)));
             }

             // The lifetime of the resources end when their close senders
             // start executing.
             return ex::when_all(ex::close(h_loop), ex::close(h_scope));
           });

// Drive the resources while using them. (The run_loop is driven from
// a separate worker thread.)
auto work = ex::when_all(
              use,
              ex::on(worker, ex::run(loop)),
              ex::run(scope)
            );

// Launch it all and wait for it to complete
ex::sync_wait(std::move(work));

This design nicely captures the “async RAII” pattern. A type modeling the async resource concept is like an async class with an async constructor and an async destructor. Instead of using finally, a user can implement a type that satisfies the async resource concept.

Although there are times when it is appropriate to model the async resource concept, doing so is certainly more work than just using finally. One can think of finally as an ad hoc form of async RAII. To draw an analogy, finally is to async resource what scope_guard is to custom RAII wrappers like unique_ptr. That is no diss on scope_guard; it has its place!

So too does finally in the authors’ opinion. It captures a common pattern quite simply, and is not a far departure from what is in P2300 already. An async resource abstraction is a much heavier lift from a standardization point of view. Pursuing that design instead of finally risks missing the C++26 boat, leaving users without a standard way to reliably clean up asynchronous resources.

In the end, the authors expect that we will have both, just as many codebases make use of both scope_guard and unique_ptr.

5 Proposed Wording

[ Editor's note: The wording in this section is based on [P2300R9] with the additions of [P2855R1] and [P3175R1]. ]

[ Editor's note: Change [exec.syn] as follows: ]

  inline constexpr unspecified read_env{};
...

  struct start_on_t;
  struct transfer_tcontinue_on_t;
  struct on_t;
  struct schedule_from_t;
...

  inline constexpr unspecified write_env{};
  inline constexpr unspecified unstoppable{};
  inline constexpr start_on_t start_on{};
  inline constexpr transfer_t transfercontinue_on_t continue_on{};
  inline constexpr on_t on{};
  inline constexpr unspecified finally{};
  inline constexpr schedule_from_t schedule_from{};

[ Editor's note: Change subsection “execution::read [exec.read]” to “execution::read_env [exec.read.env]”, and within that subsection, replace every instance of “read” with “read_env”. ]

[ Editor's note: Replace all instances of “write-env” with “write_env”. After [exec.adapt.objects], add a new subsection “execution::write_env [exec.write.env]” and move the specification of the exposition-only write-env from [exec.snd.general]/p3.15 into it with the following modifications: ]

(34.9.11.?) execution::write_env [exec.write.env]

1. write-envwrite_env is an exposition-onlya sender adaptor that accepts a sender and a queryable object, and that returns a sender that, when connected with a receiver rcvr, connects the adapted sender with a receiver whose execution environment is the result of joining the queryable argument envobject to the result of get_env(rcvr).

3. Remarks: The exposition-only class template impls-for ([exec.snd.general]) is specialized for write-env-twrite_env as follows:

   template<>
   struct impls-for<write-env-tdecayed-typeof<write_env>> : default-impls {
     static constexpr auto get-env =
       [](auto, const auto& state, const auto& rcvr) noexcept {
         return JOIN-ENV(state, get_env(rcvr));
       };
   };

[ Editor's note: After [exec.write.env], add a new subsection “execution::unstoppable [exec.unstoppable]” as follows: ]