P3325R5 A Utility for Creating Execution Environments

source/exec.tex

@@ -466,13 +466,20 @@
   template<class CPO>
     constexpr get_completion_scheduler_t<CPO> @\libglobal{get_completion_scheduler}@{};
 
-  struct @\libglobal{empty_env}@ {};
   struct @\libglobal{get_env_t}@ { @\unspec@ };
   inline constexpr get_env_t @\libglobal{get_env}@{};
 
   template<class T>
     using @\libglobal{env_of_t}@ = decltype(get_env(declval<T>()));
 
+  // \ref{exec.prop}, class template \tcode{prop}
+  template<class QueryTag, class ValueType>
+    struct prop;
+
+  // \ref{exec.env}, class template \tcode{env}
+  template<@\exposconcept{queryable}@... Envs>
+    struct env;
+
   // \ref{exec.domain.default}, execution domains
   struct default_domain;
 
@@ -514,7 +521,7 @@
   template<class Sndr>
     concept @\libconcept{sender}@ = @\seebelow@;
 
-  template<class Sndr, class Env = empty_env>
+  template<class Sndr, class Env = env<>>
     concept @\libconcept{sender_in}@ = @\seebelow@;
 
   template<class Sndr, class Rcvr>
@@ -527,7 +534,7 @@
   struct get_completion_signatures_t;
   inline constexpr get_completion_signatures_t get_completion_signatures {};
 
-  template<class Sndr, class Env = empty_env>
+  template<class Sndr, class Env = env<>>
       requires @\libconcept{sender_in}@<Sndr, Env>
     using completion_signatures_of_t = @\exposid{call-result-t}@<get_completion_signatures_t, Sndr, Env>;
 
@@ -537,18 +544,18 @@
   template<class... Ts>
     using @\exposidnc{variant-or-empty}@ = @\seebelownc@;                         // \expos
 
-  template<class Sndr, class Env = empty_env,
+  template<class Sndr, class Env = env<>,
            template<class...> class Tuple = @\exposid{decayed-tuple}@,
            template<class...> class Variant = @\exposid{variant-or-empty}@>
       requires @\libconcept{sender_in}@<Sndr, Env>
     using value_types_of_t = @\seebelow@;
 
-  template<class Sndr, class Env = empty_env,
+  template<class Sndr, class Env = env<>,
            template<class...> class Variant = @\exposid{variant-or-empty}@>
       requires @\libconcept{sender_in}@<Sndr, Env>
     using error_types_of_t = @\seebelow@;
 
-  template<class Sndr, class Env = empty_env>
+  template<class Sndr, class Env = env<>>
       requires @\libconcept{sender_in}@<Sndr, Env>
     constexpr bool sends_stopped = @\seebelow@;
 
@@ -662,7 +669,7 @@
 
   template<
     @\libconcept{sender}@ Sndr,
-    class Env = empty_env,
+    class Env = env<>,
     @\exposconcept{valid-completion-signatures}@ AdditionalSignatures = completion_signatures<>,
     template<class...> class SetValue = @\seebelow@,
     template<class> class SetError = @\seebelow@,
@@ -834,7 +841,7 @@
 The type of the expression above satisfies
 \exposconcept{queryable}\iref{exec.queryable}.
 \item
-Otherwise, \tcode{empty_env\{\}}.
+Otherwise, \tcode{env<>\{\}}.
 \end{itemize}
 
 \pnum
@@ -1782,7 +1789,7 @@
   if constexpr (sizeof...(child) == 1)
     return (@\exposid{FWD-ENV}@(get_env(child)), ...);
   else
-    return empty_env();
+    return env<>();
 }
 \end{codeblock}
 
@@ -1913,7 +1920,7 @@
   template<class Sndr>
     concept @\defexposconcept{enable-sender}@ =                                     // \expos
       @\exposconcept{is-sender}@<Sndr> ||
-      @\exposconcept{is-awaitable}@<Sndr, @\exposid{env-promise}@<empty_env>>;               // \ref{exec.awaitable}
+      @\exposconcept{is-awaitable}@<Sndr, @\exposid{env-promise}@<env<>>>;                 // \ref{exec.awaitable}
 
   template<class Sndr>
     concept @\deflibconcept{sender}@ =
@@ -1924,7 +1931,7 @@
       @\libconcept{move_constructible}@<remove_cvref_t<Sndr>> &&
       @\libconcept{constructible_from}@<remove_cvref_t<Sndr>, Sndr>;
 
-  template<class Sndr, class Env = empty_env>
+  template<class Sndr, class Env = env<>>
     concept @\deflibconcept{sender_in}@ =
       @\libconcept{sender}@<Sndr> &&
       @\exposconcept{queryable}@<Env> &&
@@ -1982,7 +1989,7 @@
         value_types_of_t<Sndr, Env, @\exposid{value-signature}@, type_identity_t>);
 
   template<class Sndr, class... Values>
-    concept @\defexposconcept{sender-of}@ = @\exposconcept{sender-in-of}@<Sndr, empty_env, Values...>;
+    concept @\defexposconcept{sender-of}@ = @\exposconcept{sender-in-of}@<Sndr, env<>, Values...>;
 }
 \end{codeblock}
 
@@ -2665,7 +2672,7 @@
 \tcode{\exposid{FWD-ENV}(get_env(sndr))}\iref{exec.fwd.env}.
 \item
 A parent sender with more than one child sender has
-an associated attributes object equal to \tcode{empty_env\{\}}.
+an associated attributes object equal to \tcode{env<>\{\}}.
 \item
 When a parent sender is connected to a receiver \tcode{rcvr},
 any receiver used to connect a child sender has
@@ -3387,7 +3394,7 @@
 \item
 \tcode{\exposid{MAKE-ENV}(get_domain, get_domain(get_env(sndr)))}
 \item
-\tcode{(void(sndr), empty_env\{\})}
+\tcode{(void(sndr), env<>\{\})}
 \end{itemize}
 
 \pnum
@@ -4088,7 +4095,7 @@
 \begin{codeblock}
 [](auto&&, auto&&... child) noexcept {
   if constexpr (@\libconcept{same_as}@<CD, default_domain>) {
-    return empty_env();
+    return env<>();
   } else {
     return @\exposid{MAKE-ENV}@(get_domain, CD());
   }
@@ -4816,23 +4823,21 @@
   template<@\exposconcept{completion-signature}@... Fns>
     struct completion_signatures {};
 
-  template<class Sndr,
-           class Env = empty_env,
+  template<class Sndr, class Env = env<>,
            template<class...> class Tuple = @\exposid{decayed-tuple}@,
            template<class...> class Variant = @\exposid{variant-or-empty}@>
       requires @\libconcept{sender_in}@<Sndr, Env>
     using value_types_of_t =
       @\exposid{gather-signatures}@<set_value_t, completion_signatures_of_t<Sndr, Env>, Tuple, Variant>;
 
-  template<class Sndr,
-           class Env = empty_env,
+  template<class Sndr, class Env = env<>,
            template<class...> class Variant = @\exposid{variant-or-empty}@>
       requires @\libconcept{sender_in}@<Sndr, Env>
     using error_types_of_t =
       @\exposid{gather-signatures}@<set_error_t, completion_signatures_of_t<Sndr, Env>,
                         type_identity_t, Variant>;
 
-  template<class Sndr, class Env = empty_env>
+  template<class Sndr, class Env = env<>>
       requires @\libconcept{sender_in}@<Sndr, Env>
     constexpr bool sends_stopped =
       !@\libconcept{same_as}@<@\exposid{type-list}@<>,
@@ -4941,6 +4946,149 @@
 of all the \tcode{completion_signatures} specializations in the set
 \tcode{AdditionalSignatures}, \tcode{Vs...}, \tcode{Es...}, \tcode{Ss}.
 
+\rSec1[exec.envs]{Queryable uilities}
+
+\rSec2[exec.prop]{Class template \tcode{prop}}
+
+\begin{codeblock}
+namespace std::execution {
+  template<class QueryTag, class ValueType>
+  struct @\libglobal{prop}@ {
+    QueryTag @\exposid{query_}@;            // \expos
+    ValueType @\exposid{value_}@;           // \expos
+
+    constexpr const ValueType& query(QueryTag) const noexcept {
+      return @\exposid{value_}@;
+    }
+  };
+
+  template<class QueryTag, class ValueType>
+    prop(QueryTag, ValueType) -> prop<QueryTag, unwrap_reference_t<ValueType>>;
+}
+\end{codeblock}
+
+\pnum
+Class template \tcode{prop} is for building a queryable object
+from a query object and a value.
+
+\pnum
+\mandates
+\tcode{\exposconcept{callable}<QueryTag, \exposid{prop-like}<ValueType>>}
+is modeled,
+where \exposid{prop-like} is the following exposition-only class template:
+\begin{codeblock}
+template<class ValueType>
+struct @\exposid{prop-like}@ {              // \expos
+  const ValueType& query(auto) const noexcept;
+};
+\end{codeblock}
+
+\pnum
+\begin{example}
+\begin{codeblock}
+template<sender Sndr>
+sender auto parameterize_work(Sndr sndr) {
+  // Make an environment such that \tcode{get_allocator(env)} returns a reference to a copy of \tcode{my_alloc\{\}}.
+  auto e = prop(get_allocator, my_alloc{});
+
+  // Parameterize the input sender so that it will use our custom execution environment.
+  return write_env(sndr, e);
+}
+\end{codeblock}
+\end{example}
+
+\pnum
+Specializations of \tcode{prop} are not assignable.
+
+\rSec2[exec.env]{Class template \tcode{env}}
+
+\begin{codeblock}
+namespace std::execution {
+  template<@\exposconcept{queryable}@... Envs>
+  struct @\libglobal{env}@ {
+    Envs@$_0$@ @$\exposid{envs}_0$@;               // \expos
+    Envs@$_1$@ @$\exposid{envs}_1$@;               // \expos
+      @\vdots@
+    Envs@$_{n-1}$@ @$\exposid{envs}_{n-1}$@;           // \expos
+
+    template<class QueryTag>
+      constexpr decltype(auto) query(QueryTag q) const noexcept(@\seebelow@);
+  };
+
+  template<class... Envs>
+    env(Envs...) -> env<unwrap_reference_t<Envs>...>;
+}
+\end{codeblock}
+
+\pnum
+The class template \tcode{env} is used to construct a queryable object
+from several queryable objects.
+Query invocations on the resulting object are resolved
+by attempting to query each subobject in lexical order.
+
+\pnum
+Specializations of \tcode{env} are not assignable.
+
+\pnum
+It is unspecified
+whether \tcode{env} supports initialization
+using a parenthesized \grammarterm{expression-list}\iref{dcl.init},
+unless the \grammarterm{expression-list} consist of
+a single element of type (possibly const) \tcode{env}.
+
+\pnum
+\begin{example}
+\begin{codeblock}
+template<sender Sndr>
+sender auto parameterize_work(Sndr sndr) {
+  // Make an environment such that:
+  //   \tcode{get_allocator(env)} returns a reference to a copy of \tcode{my_alloc\{\}}
+  //   \tcode{get_scheduler(env)} returns a reference to a copy of \tcode{my_sched\{\}}
+  auto e = env{prop(get_allocator, my_alloc{}),
+               prop(get_scheduler, my_sched{})};
+
+  // Parameterize the input sender so that it will use our custom execution environment.
+  return write_env(sndr, e);
+}
+\end{codeblock}
+\end{example}
+
+\indexlibrarymember{query}{env}%
+\begin{itemdecl}
+template<class QueryTag>
+constexpr decltype(auto) query(QueryTag q) const noexcept(@\seebelow@);
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+Let \exposconcept{has-query} be the following exposition-only concept:
+\begin{codeblock}
+template<class Env, class QueryTag>
+  concept @\defexposconcept{has-query}@ =                   // \expos
+    requires (const Env& env) {
+      env.query(QueryTag());
+    };
+\end{codeblock}
+
+\pnum
+Let \exposid{fe} be the first element of
+$\exposid{envs}_0$, $\exposid{envs}_1$, $\dotsc$, $\exposid{envs}_{n-1}$
+such that the expression \tcode{\exposid{fe}.query(q)} is well-formed.
+
+\pnum
+\constraints
+\tcode{(\exposconcept{has-query}<Envs, QueryTag> || ...)} is \tcode{true}.
+
+\pnum
+\effects
+Equivalent to: \tcode{return \exposid{fe}.query(q);}
+
+\pnum
+\remarks
+The expression in the \tcode{noexcept} clause is equivalent
+to \tcode{noexcept(\exposid{fe}.query(q))}.
+\end{itemdescr}
+
 \rSec1[exec.ctx]{Execution contexts}
 
 \rSec2[exec.run.loop]{\tcode{execution::run_loop}}