fixup: add upto 34.9.11.7

Author: jensmaurer

source/exec.tex

@@ -3006,6 +3006,286 @@
 an error completion on \tcode{out_rcvr} shall be executed
 on an unspecified execution agent.
 
+\rSec3[exec.on]{\tcode{execution::on}}
+
+\pnum
+The \tcode{on} sender adaptor has two forms:
+\begin{itemize}
+\item
+\tcode{on(sch, sndr)},
+which starts a sender \tcode{sndr} on an execution agent
+belonging to a scheduler \tcode{sch}'s associated execution resource and
+that, upon \tcode{sndr}'s completion,
+transfers execution back to the execution resource
+on which the \tcode{on} sender was started.
+\item
+\tcode{on(sndr, sch, closure)},
+which upon completion of a sender \tcode{sndr},
+transfers execution to an execution agent
+belonging to a scheduler \tcode{sch}'s associated execution resource,
+then executes a sender adaptor closure \tcode{closure}
+with the async results of the sender, and
+that then transfers execution back to the execution resource
+on which \tcode{sndr} completed.
+\end{itemize}
+
+\pnum
+The name \tcode{on} denotes a pipeable sender adaptor object.
+For subexpressions \tcode{sch} and \tcode{sndr},
+\tcode{on(sch, sndr)} is ill-formed if any of the following is true:
+\begin{itemize}
+\item
+\tcode{decltype((sch))} does not satisfy \libconcept{scheduler}, or
+\item
+\tcode{decltype((sndr))} does not satisfy \libconcept{sender} and
+\tcode{sndr} is not
+a pipeable sender adaptor closure object\iref{exec.adapt.objects}, or
+\item
+\tcode{decltype((sndr))} satisfies \libconcept{sender} and
+\tcode{sndr }is also a pipeable sender adaptor closure object.
+\end{itemize}
+
+\pnum
+Otherwise, if \tcode{decltype((sndr))} satisfies \libconcept{sender},
+the expression \tcode{on(sch, sndr)} is expression-equivalent to:
+\begin{codeblock}
+transform_sender(
+  @\exposid{query-or-default}@(get_domain, sch, default_domain()),
+  @\exposid{make-sender}@(on, sch, sndr))
+\end{codeblock}
+except that \tcode{sch} is evaluated only once.
+
+\pnum
+For subexpressions \tcode{sndr}, \tcode{sch}, and \tcode{closure}, if
+\begin{itemize}
+\item
+\tcode{decltype((sch))} does not satisfy \libconcept{scheduler}, or
+\item
+\tcode{decltype((sndr))} does not satisfy \libconcept{sender}, or
+\item
+\tcode{closure} is not a pipeable sender adaptor closure object\iref{exec.adapt.objects},
+\end{itemize}
+the expression \tcode{on(sndr, sch, closure)} is ill-formed;
+otherwise, it is expression-equivalent to:
+\begin{codeblock}
+transform_sender(
+  @\exposid{get-domain-early}@(sndr),
+  @\exposid{make-sender}@(on, @\exposid{product-type}@{sch, closure}, sndr))
+\end{codeblock}
+except that \tcode{sndr} is evaluated only once.
+
+\pnum
+Let \tcode{out_sndr} and \tcode{env} be subexpressions,
+let \tcode{OutSndr} be \tcode{decltype((out_sndr))}, and
+let \tcode{Env} be \tcode{decltype((env))}.
+If \tcode{\exposconcept{sender-for}<OutSndr, on_t>} is \tcode{false},
+then the expressions \tcode{on.transform_env(out_sndr, env)} and
+\tcode{on.transform_sender(out_sndr, env)} are ill-formed.
+
+\pnum
+Otherwise:
+Let \exposid{not-a-scheduler} be an unspecified empty class type, and
+let \exposid{not-a-sender} be the exposition-only type:
+\begin{codeblock}
+struct @\exposid{not-a-sender}@ {
+  using sender_concept = sender_t;
+
+  auto get_completion_signatures(auto&&) const {
+    return @\seebelow@;
+  }
+};
+\end{codeblock}
+where the member function \tcode{get_completion_signatures} returns
+an object of a type that is not
+a specialization of the \tcode{completion_signatures} class template.
+
+\pnum
+The expression \tcode{on.transform_env(out_sndr, env)}
+has effects equivalent to:
+\begin{codeblock}
+auto&& [_, data, _] = out_sndr;
+if constexpr (@\libconcept{scheduler}@<decltype(data)>) {
+  return @\exposid{JOIN-ENV}@(@\exposid{SCHED-ENV}@(std::forward_like<OutSndr>(data)), @\exposid{FWD-ENV}@(std::forward<Env>(env)));
+} else {
+  return std::forward<Env>(env);
+}
+\end{codeblock}
+
+\pnum
+The expression \tcode{on.transform_sender(out_sndr, env)}
+has effects equivalent to:
+\begin{codeblock}
+auto&& [_, data, child] = out_sndr;
+if constexpr (@\libconcept{scheduler}@<decltype(data)>) {
+  auto orig_sch =
+    @\exposid{query-with-default}@(get_scheduler, env, @\exposid{not-a-scheduler}@());
+
+  if constexpr (@\libconcept{same_as}@<decltype(orig_sch), @\exposid{not-a-scheduler}@>) {
+    return @\exposid{not-a-sender}@{};
+  } else {
+    return continues_on(
+      starts_on(std::forward_like<OutSndr>(data), std::forward_like<OutSndr>(child)),
+      std::move(orig_sch));
+  }
+} else {
+  auto& [sch, closure] = data;
+  auto orig_sch = @\exposid{query-with-default}@(
+    get_completion_scheduler<set_value_t>,
+    get_env(child),
+    @\exposid{query-with-default}@(get_scheduler, env, @\exposid{not-a-scheduler}@()));
+
+  if constexpr (@\libconcept{same_as}@<decltype(orig_sch), @\exposid{not-a-scheduler}@>) {
+    return @\exposid{not-a-sender}@{};
+  } else {
+    return @\exposid{write-env}@(
+      continues_on(
+        std::forward_like<OutSndr>(closure)(
+          continues_on(
+            @\exposid{write-env}@(std::forward_like<OutSndr>(child), @\exposid{SCHED-ENV}@(orig_sch)),
+            sch)),
+        orig_sch),
+      @\exposid{SCHED-ENV}@(sch));
+  }
+}
+\end{codeblock}
+
+\pnum
+\recommended
+Implementations should use
+the return type of \tcode{\exposid{not-a-sender}::get_completion_signatures}
+to inform users that their usage of \tcode{on} is incorrect
+because there is no available scheduler onto which to restore execution.
+
+\pnum
+Let \tcode{out_sndr} be a subexpression denoting
+a sender returned from \tcode{on(sch, sndr)} or one equal to such, and
+let \tcode{OutSndr} be the type \tcode{decltype((out_sndr))}.
+Let \tcode{out_rcvr} be a subexpression denoting a receiver
+that has an environment of type \tcode{Env}
+such that \tcode{\libconcept{sender_in}<OutSndr, Env>} is \tcode{true}.
+Let \tcode{op} be an lvalue referring to the operation state
+that results from connecting \tcode{out_sndr} with \tcode{out_rcvr}.
+Calling \tcode{start(op)} shall
+\begin{itemize}
+\item
+remember the current scheduler, \tcode{get_scheduler(get_env(rcvr))};
+\item
+start \tcode{sndr} on an execution agent belonging to
+sch's associated execution resource;
+\item
+upon \tcode{sndr}'s completion,
+transfer execution back to the execution resource
+associated with the scheduler remembered in step 1; and
+\item
+forward \tcode{sndr}'s async result to \tcode{out_rcvr}.
+\end{itemize}
+If any scheduling operation fails,
+an error completion on \tcode{out_rcvr} shall be executed
+on an unspecified execution agent.
+
+\pnum
+Let \tcode{out_sndr} be a subexpression denoting
+a sender returned from \tcode{on(sndr, sch, closure)} or one equal to such, and
+let \tcode{OutSndr} be the type \tcode{decltype((out_sndr))}.
+Let \tcode{out_rcvr} be a subexpression denoting a receiver
+that has an environment of type \tcode{Env}
+such that \tcode{\libconcept{sender_in}<OutSndr, Env>} is \tcode{true}.
+Let \tcode{op} be an lvalue referring to the operation state
+that results from connecting \tcode{out_sndr} with \tcode{out_rcvr}.
+Calling \tcode{start(op)} shall
+\begin{itemize}
+\item
+remember the current scheduler,
+which is the first of the following expressions that is well-formed:
+\begin{itemize}
+\item \tcode{get_completion_scheduler<set_value_t>(get_env(sndr))}
+\item \tcode{get_scheduler(get_env(rcvr))};
+\end{itemize}
+\item
+start \tcode{sndr} on the current execution agent;
+\item
+upon \tcode{sndr}'s completion,
+transfer execution to an agent
+owned by sch's associated execution resource;
+\item
+forward \tcode{sndr}'s async result as if by
+connecting and starting a sender \tcode{closure(S)},
+where \tcode{S} is a sender
+that completes synchronously with \tcode{sndr}'s async result; and
+\item
+upon completion of the operation started in the previous step,
+transfer execution back to the execution resource
+associated with the scheduler remembered in step 1 and
+forward the operation's async result to \tcode{out_rcvr}.
+\end{itemize}
+If any scheduling operation fails,
+an error completion on \tcode{out_rcvr} shall be executed on
+an unspecified execution agent.
+
+\rSec3[exec.then]{\tcode{execution::then}, \tcode{execution::upon_error}, \tcode{execution::upon_stopped}}
+
+\pnum
+\tcode{then} attaches an invocable as a continuation
+for an input sender's value completion operation.
+\tcode{upon_error} and \tcode{upon_stopped} do the same
+for the error and stopped completion operations, respectively,
+sending the result of the invocable as a value completion.
+
+\pnum
+The names \tcode{then}, \tcode{upon_error}, and \tcode{upon_stopped}
+denote pipeable sender adaptor objects.
+Let the expression \exposid{then-cpo} be one of
+\tcode{then}, \tcode{upon_error}, or \tcode{upon_stopped}.
+For subexpressions \tcode{sndr} and \tcode{f},
+if \tcode{decltype((sndr))} does not satisfy \libconcept{sender}, or
+\tcode{decltype((f))} does not satisfy \exposid{movable-value},
+\tcode{\exposid{then-cpo}(sndr, f) }is ill-formed.
+
+\pnum
+Otherwise,
+the expression \tcode{\exposid{then-cpo}(sndr, f)} is expression-equivalent to:
+\begin{codeblock}
+transform_sender(@\exposid{get-domain-early}@(sndr), @\exposid{make-sender}@(@\exposid{then-cpo}@, f, sndr))
+\end{codeblock}
+except that \tcode{sndr} is evaluated only once.
+
+\pnum
+For \tcode{then}, \tcode{upon_error}, and \tcode{upon_stopped},
+let \exposid{set-cpo} be
+\tcode{set_value}, \tcode{set_error}, and \tcode{set_stopped}, respectively.
+The exposition-only class template \exposid{impls-for}\iref{exec.snd.general}
+is specialized for \exposid{then-cpo} as follows:
+\begin{codeblock}
+namespace std::execution {
+  template<>
+  struct @\exposid{impls-for}@<@\exposid{decayed-typeof}@<@\exposid{then-cpo}@>> : @\exposid{default-impls}@ {
+    static constexpr auto @\exposid{complete}@ =
+      []<class Tag, class... Args>
+        (auto, auto& fn, auto& rcvr, Tag, Args&&... args) noexcept -> void {
+          if constexpr (@\libconcept{same_as}@<Tag, @\exposid{decayed-typeof}@<set-cpo>>) {
+            @\exposid{TRY-SET-VALUE}@(rcvr,
+                          invoke(std::move(fn), std::forward<Args>(args)...));
+          } else {
+            Tag()(std::move(rcvr), std::forward<Args>(args)...);
+          }
+        };
+  };
+}
+\end{codeblock}
+
+\pnum
+The expression \tcode{\exposid{then-cpo}(sndr, f)} has undefined behavior
+unless it returns a sender\tcode{out_sndr} that
+\begin{itemize}
+\item
+invokes \tcode{f} or a copy of such
+with the value, error, or stopped result datums of \tcode{sndr}
+for \tcode{then}, \tcode{upon_error}, and \tcode{upon_stopped}, respectively,
+using the result value of \tcode{f} as \tcode{out_sndr}'s value completion, and
+\item
+forwards all other completion operations unchanged.
+\end{itemize}
+
 \rSec1[exec.util]{Sender/receiver utilities}