<html>
<head>
<meta charset="UTF-8">
<title>DxxxxR0: Naming improvements for std::execution</title>

<style type="text/css">
  ins { text-decoration:none; font-weight:bold; background-color:#A0FFA0 }
  .new { text-decoration:none; background-color:#D0FFD0 }
  del { text-decoration:line-through; background-color:#FFA0A0 }  
  strong { font-weight: inherit; color: #2020ff }
  table, td, th { border: 1px solid black; border-collapse:collapse; padding: 5px }
</style>
</head>

<body>
ISO/IEC JTC1 SC22 WG21 DxxxxR0<br/>
Author: Jens Maurer<br/>
Target audience: LEWG<br/>
2022-02-14<br/>

<h1>DxxxxR0: Naming improvements for std::execution</h1>

<h2>1 Abstract</h2>

This paper proposes naming improvements for the sender factories and
sender adaptors presented in P2300R4 std::execution.


<h2>2 Paper history</h2>

<h3>R0: initial revision</h3>


<h2>3 List of names with suggeted changes</h2>

<table>
  <tr>
    <th>P2300R4 name</th> <th>suggested name</th> <th>alternative name</th>
  </tr>

  <tr> <td>schedule</td> </tr>
  <tr> <td>just</td> <td>set_value</td> <td>value</td> </tr>
  <tr> <td>transfer_just</td> <td>transfer_set_value</td> <td><em>remove</em></td></tr>
  <tr> <td>just_error</td> <td>set_error</td><td>error</td></tr>
  <tr> <td>just_stopped</td> <td>set_stopped</td><td>stopped</td></tr>
  <tr> <td>read</td> </tr>

  <tr> <td>transfer</td> </tr>
  <tr> <td>then</td> <td></td><td>transform</td></tr>
  <tr> <td>upon_error/stopped</td> <td>then_error/then_stopped</td> <td>transform_error/transform_stopped</td></tr>
  <tr> <td>let_value/error/stopped</td> <td>?</td></tr>
  <tr> <td>on</td> </tr>
  <tr> <td>into_variant</td> </tr>
  <tr> <td>stopped_as_optional</td> </tr>
  <tr> <td>stopped_as_error</td> </tr>
  <tr> <td>bulk</td> </tr>
  <tr> <td>split</td> </tr>
  <tr> <td>when_all</td> </tr>
  <tr> <td>transfer_when_all</td> <td></td> <td><em>remove</em></td> </tr>
  <tr> <td>ensure_started</td> </tr>

  <tr> <td>start_detached</td></tr>
  <tr> <td>this_thread::sync_wait</td></tr>
  <tr> <td>execute</td> </tr>
</table>

<h2>4 Discussion</h2>

Senders/receivers employ three channels:

<ul>
  <li>value channel</li>
  <li>error channel</li>
  <li>stopped channel</li>
</ul>

Operations that are available for all three channels should call out
the specific channel they operate on, in a consistent manner.  If,
instead, the value channel is considered sufficiently default that it
need not be named explicitly, it should never be namend.  Existing
practice in P2300R4 appears to gravitate towards always naming the
channel.
<p>
Compare <code>let_value</code> / <code>let_error</code> / <code>let_stopped</code> with <code>just</code> / <code>just_error</code> /
<code>just_stopped</code> for an obvious inconsistency in this regard.
<p>
Looking at the existing names, there seems to be little consistency in
the kinds of words being used: verbs
(<code>schedule</code>, <code>transfer</code>, <code>execute</code>),
verb-based phrases (<code>stopped_as_optional</code>), and adverbs
(<code>just</code>, <code>then</code>, <code>when_all</code>) are
intermixed.
<p>
For me, particularly and negatively outstanding is the rather
unsophisticated <code>just</code> to indicate the injection of values in the
sender chain.  The proposal here is to use either <code>set_value</code> /
<code>set_error</code> / <code>set_stopped</code> or
plain <code>value</code> / <code>error</code> / <code>stopped</code>
as the consistent triplet, with the author's slight preference towards
the <code>set_*</code> names for consistency with <code>let_*</code>.
<p>
The counterparts for <code>then</code> are <code>upon_error</code>
and <code>upon_stopped</code>, which is inconsistent.  Also, the name
<code>transform</code> is used in other areas of the standard to
describe the application of a functor on some input value(s),
e.g. <code>std::transform</code>
or <code>std::ranges::view::transform</code>.  For <code>then</code> in
particular, such cross-domain consistency may not carry its weight
compared to the idiomatic <code>then</code> in the local domain.
<p>
The rationale for <code>let_value</code> is the similarity to a
LISP-style "let" operation that introduces a local variable. However,
examples seem to favor a <code>fork</code> or <code>spawn</code>
reading.  I do not have sufficient experience with the actual usage of
senders/receivers to form an opinion whether such examples warrant a
rename of the <code>let_*</code> adaptors.
<p>
Finally, if at all possible, compound operations such
as <code>transfer_just</code> or <code>transfer_when_all</code> should
be left as an implementation optimization (possibly specified in the
standard); however, the user should not need to learn whether a
certain combination of sender adaptors has a compound spelling or not.

<h2>5 Proposal</h2>

<ul>
<li>Rename <code>just</code> / <code>just_error</code>
  / <code>just_stopped</code> to <code>set_value</code>
  / <code>set_error</code> / <code>set_stopped</code>.</li>
<li>Consider renaming <code>upon_error</code>
  and <code>upon_stopped</code> to <code>then_error</code>
  and <code>then_stopped</code>.
</ul>

</body>
</html>
