<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <title>User-defined erroneous behaviour</title>
    <style type="text/css">
      html { margin: 0; padding: 0; color: black; background-color: white; }
      body { margin: 0 auto; padding: 2em; font-size: medium; font-family: "DejaVu Serif", serif; line-height: 150%; max-width: 60em; }
      code { font-family: "DejaVu Sans Mono", monospace; color: #006; }

      h1, h2, h3 { margin: 1.5em 0 .75em 0; line-height: 125%; }
      h1 { clear: both; }

      div.code { white-space: pre-line; font-family: "DejaVu Sans Mono", monospace;
                 border: thin solid #E0E0E0; background-color: #F8F8F8; padding: 1em;
                 border-radius: 4px; }

      div.strictpre { white-space: pre; }

      sub, sup { margin: 0; padding: 0; line-height: 100%; }

      table { border-collapse: collapse; margin: 2em auto; }
      table caption { margin: 2ex 0 0 0; caption-side: bottom; font-family: "DejaVu Sans", sans-serif; font-size: small; }

      th, td { text-align: left; padding: .5ex 1em; margin: 0; }
      th {  vertical-align: middle; }
      td {  vertical-align: top; }

      td.new { background-color: #EFE; }
      td.new:after { content: "new!"; font-family: "DejaVu Sans", sans-serif; font-weight: bold; font-size: xx-small;
                     vertical-align: top; top: -1em; right: -1em; position: relative; float: right; color: #090; }

      thead th { border-top: 2px solid #333; border-bottom: 2px solid #333; }
      tbody.lined td, tr.line td { border-bottom: 1px solid #333; }
      tr.final td { border-bottom: 2px solid #333; }

      .code .note { font-family: "DejaVu Sans", sans-serif; font-size: small; padding: 0; margin: 0; color: #333; }

      .docinfo { float: right }
      .docinfo p { margin: 0; text-align:right; }
      .docinfo address { font-style: normal; margin-bottom: 2em; }

      .quote { display: inline-block; clear: both; margin-left: 1ex;
                 border: thin solid #E0E0E0; background-color: #F8F8F8; padding: 1ex; }

      .modify { border-left: thick solid #999; border-right: thick solid #999; padding: 0 1em; }
      .insert { border-left: thick solid #0A0; border-right: thick solid #0A0; padding: 0 1em; }
      .insert h3, .insert h4, .insert p { text-decoration: underline; color: #0A0; }
      .comment { color: #456; }
      .inclassit { font-family: "DejaVu Serif", serif; font-style: italic; }
      .insinline { border-bottom: 2px solid #0A0; }

      ins { color: #090; }
      del { color: #A00; }
      ins code, del code, .insert code { color: inherit; }

      ul.wide li { margin-bottom: 1em; }
      ul.wide li div.code { padding: 0.25ex 1ex; margin: 1ex 0; }
    </style>
  </head>
  <body>
    <div class="docinfo">
      <p>ISO/IEC JTC1 SC22 WG21 P3232R0</p>
      <p>Date: 2024-04-16</p>
      <p>To: SG12, SG23, EWG, LWG, CWG</p>
      <address>
        Thomas K&ouml;ppe &lt;<a href="mailto:tkoeppe@google.com">tkoeppe@google.com</a>&gt;
      </address>
    </div>

    <h1>User-defined erroneous behaviour</h1>

    <h2>Contents</h2>
    <!-- fgrep -e "<h2 id=" user_def_erroneous.html | sed -e 's/.*id="\(.*\)">\(.*\)<\/h2>/<li><a href="#\1">\2<\/a><\/li>/g' -->
    <ol>
      <li><a href="#history">Revision history</a></li>
      <li><a href="#summary">Summary</a></li>
      <li><a href="#motivation">Motivation</a></li>
      <li><a href="#proposal">Proposal: <code>std::erroneous</code></a></li>
      <li><a href="#impact">Impact and implementability</a></li>
      <li><a href="#wording">Proposed wording</a></li>
      <li><a href="#ack">Acknowledgements</a></li>
      <li><a href="#references">References</a></li>
    </ol>

    <h2 id="history">Revision history</h2>
    <ul>
      <li>P3232R0: Initial revision.</li>
    </ul>

    <h2 id="summary">Summary</h2>

    <p>
      We propose a language-support library function that has no effect other than
      to cause erroneous behaviour. This allows user-defined APIs to include erroneous behaviour.
    </p>

    <h2 id="motivation">Motivation</h2>

    <p>
      The purpose of erroneous behaviour, introduced in
      <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2024/p2795r5.html">P2795R5</a>,
      is to provide well-defined behaviour in the presence of certain programming errors,
      thereby mitigating the safety and security implications of said errors: Erroneous behaviour
      is part of the observable behaviour of a program, and the compiler must not assume that it
      does not happen (unlike undefined behaviour).
    </p>
    <p>
      Whereas P2795R5 only prescribed erroneous behaviour for a particular operation (namely
      reading an uninitialized variable with automatic storage duration), being able to declare
      parts of an API erroneous is also useful for user-defined APIs that have preconditions
      (i.e. a &ldquo;narrow contract&rdquo;). It is a programming error to invoke such an API
      when preconditions are not met, but currently, attempts to make this API &ldquo;safe&rdquo;,
      that is, to limit the damage caused by calling it out of contract, suffer various shortcomings:
    </p>
    <ul>
      <li>We can leave the behaviour out of contract undefined. This is easy to specify and
        follows the Standard Library convention, but has poor safety implications (as bascially
        anything could happen).</li>
      <li>
        We can fully specify the behaviour out of contract (e.g. terminating or throwing an
        exception). This makes the API technically have a wide contract (as there are no
        technical preconditions), and the intended preconditions have to be communicated
        out-of-band, e.g. just in natural language.</li>
      <li>
        We can check the preconditions in a subset of cases (e.g. with <code>assert</code>
        when <code>NDEBUG</code> is not defined. This retains the narrow contract, but leaves
        the safety implications somewhat opaque.</li>
      <li>A hypothetical "contracts" facility in the language (e.g. see
        <a href="https://wg21.link/P2900R6">P2900R6</a>
        for a recent iteration) would allow a programmatic statement of the precondition, but there
        is not yet an agreed-upon definition of the precise semantics.</li>
    </ul>
    <p>
      To illustrate this on a simple example, let us consider a small function that computes the
      quotient of two floating point numbers and has the precondition that the denominator not
      be zero:
    </p>
    <table>
      <col><col>
      <tbody>
        <tr>
          <th>Undefined behaviour</th>
          <td><div class="code"><span class="comment">// Precondition: `den` must not be zero</span>
              float quotient(float num, float den) {
              &nbsp; return num / den;
              }</div></td>
        </tr>
        <tr>
          <th>Checked with <code>assert</code></th>
          <td><div class="code"><span class="comment">// Precondition: `den` must not be zero</span>
              float quotient(float num, float den) {
              &nbsp; <span style="color: #00B;">assert(den != 0);</span>
              &nbsp; return num / den;
              }</div></td>
        </tr>
        <tr>
          <th>Well-defined violation</th>
          <td><div class="code"><span class="comment">// Precondition: `den` must not be zero,</span>
              <span class="comment">// terminates otherwise</span>
              float quotient(float num, float den) {
              &nbsp; <span style="color: #00B;">if (den == 0) { std::abort(); }</span>
              &nbsp; return num / den;
              }</div></td>
        </tr>
        <tr>
          <th>With a &ldquo;contracts&rdquo; facility,<br>precondition:</th>
          <td><div class="code"><span class="comment">// Precondition and contract: `den` must not be zero.</span>
              float quotient(float num, float den) <span style="color: #00B;">pre(den != 0)</span> {
              &nbsp; <span class="comment">// Option #1: undefined behaviour on violation</span>
              &nbsp; /* <span class="comment">nothing</span> */

              &nbsp; <span class="comment">// Option #2: well-defined behaviour on violation</span>
              &nbsp; <span style="color: #00B;">if (den == 0) { return -2; }</span>

              &nbsp; return num / den;
              }</div></td>
        </tr>
        <tr>
          <th>With a &ldquo;contracts&rdquo; facility,<br><code>contract_assert</code>:</th>
          <td><div class="code"><span class="comment">// Precondition: `den` must not be zero.</span>
              float quotient(float num, float den) {
              &nbsp; <span style="color: #00B;">contract_assert(den != 0);</span> 

              &nbsp; <span class="comment">// Option #1: undefined behaviour on violation</span>
              &nbsp; /* <span class="comment">nothing</span> */

              &nbsp; <span class="comment">// Option #2: well-defined behaviour on violation</span>
              &nbsp; <span style="color: #00B;">if (den == 0) { return -2; }</span>

              &nbsp; return num / den;
              }</div></td>
        </tr>
        <tr>
          <th><span style="color: #090;">Proposal: violation is erroneous</span></th>
          <td><div class="code"><span class="comment">// Returns the quotient `num`/`den`;</span>
              <span class="comment">// if `den` is zero, returns -2 erroneously.</span>
              float quotient(float num, float den) {
              &nbsp; if (den == 0) { <span style="color: #090;">std::erroneous()</span>; return -2; }
              &nbsp; return quotient(unsafe_unchecked, num, den);
              }

              <span class="comment">// As above, but precondition violation is undefined</span>
              float quotient(unsafe_unchecked_t, float num, float den) {
              &nbsp; return num / den;
              }</div></td>
        </tr>
      </tbody>
    </table>
    <p>
      The final row demonstrates the proposed feature: by allowing user-defined code to be
      erroneous, we can offer a safe-by-default API that has just the same preconditions as an
      unsafe API would have had, but with well-defined behaviour (or termination; see P2795R5)
      in case the user makes a mistake. The original, unchecked API can be provided as a
      separate, explicitly annotated overload.
    </p>

    <h2 id="proposal">Proposal: <code>std::erroneous</code></h2>

    <p>
      We propose a language-support function <code>std::erroneous</code> that has no effect
      other than to have erroneous behaviour.
    </p>

    <p>
      The proposed function is to <code>std::unreachable</code> as
      erroneous behaviour is to undefined behaviour:
    </p>

    <table>
      <thead>
        <tr><th>Function</th><th>Behaviour if invoked</th></tr>
      </thead>
      <tbody>
        <tr>
          <td><code>std::unreachable</code></td>
          <td>undefined behaviour</td>
        </tr>
        <tr class="final">
          <td><code>std::erroneous</code></td>
          <td>erroneous behaviour; no effect</td>
        </tr>
      </tbody>
    </table>
    
    <h2 id="impact">Impact and implementability</h2>

    <p>
      Platforms that diagnose erroneous behaviour will presumably provide some builtin hook with which the feature can be implemented. Otherwise, it is always conforming to implement this feature as a no-op.
    </p>

    <h2 id="alternatives">Alternatives</h2>

    <p>An <code>[[erroneous]]</code> attribute was suggested during informal discussions, but it
      does not seem compelling: For example, it does not seem useful to annotate an entire
      function as always having erroneous behaviour. Instead, it is more composable to express
      this concern separately and once and for all, namely in the proposed
      function <code>std::erroneous</code>.</p>

    <h2 id="wording">Proposed wording</h2>

    <p>In either [support] or [diagnostics], in a header to be determined, add a new function:</p>
    <div class="insert">
      <div class="code"><ins>// User-defined erroneous behavior</ins>
        <ins>void erroneous();</ins></div>
    </div>
    <p>Add the specification:</p>
    <div class="insert">
      <p><strong>User-defined erroneous behavior</strong></p>
      <div class="code"><ins>void erroneous();</ins></div>
      <p><ins><em>Effects</em>: The behavior is erroneous; calling this function has no effect otherwise.</ins></p>
    </div>
    
    <h2 id="ack">Acknowledgements</h2>

    <p>Many thanks to Barry Revzin for helpful questions and discussion, and to members of SG21 for feedback on the connection to contracts.</p>

    <h2 id="references">References</h2>
    <ul>
      <li>
        Thomas K&ouml;ppe,
        <em><a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2024/p2795r5.html">P2795R5</a>:
        Erroneous behaviour for uninitialized reads</em>.
      </li>
      <li>
        Thomas K&ouml;ppe,
        <em><a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2024/n4981.html">N4981</a>:
        Working Draft, Programming Languages &mdash; C++</em>.
      </li>
      <li>
        <span title="who is being watched">Joshua Berne</span> et al.,
        <em><a href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2024/p2900r6.pdf">P2900R6</a>:
          Contracts for C++</em>.
      </li>
    </ul>

  </body>
</html>
