1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html><meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 3<title>Major differences - Boost.Outcome documentation</title> 4<link rel="stylesheet" href="../css/boost.css" type="text/css"> 5<meta name="generator" content="Hugo 0.52 with Boostdoc theme"> 6<meta name="viewport" content="width=device-width,initial-scale=1.0"/> 7 8<link rel="icon" href="../images/favicon.ico" type="image/ico"/> 9<body><div class="spirit-nav"> 10<a accesskey="p" href="../experimental/map.html"><img src="../images/prev.png" alt="Prev"></a> 11 <a accesskey="u" href="../experimental.html"><img src="../images/up.png" alt="Up"></a> 12 <a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="../experimental/status_result.html"><img src="../images/next.png" alt="Next"></a></div><div id="content"> 13 <div class="titlepage"><div><div><h1 style="clear: both">Major differences</h1></div></div></div> 14 <p>The major design differences between <code><system_error></code> and proposed <code><system_error2></code> are 15as follows:</p> 16 17<ol> 18<li><p><code>experimental::status_code<DomainType></code> can represent warnings 19and form-of-success codes as well as failure codes. <code>experimental::errored_status_code<DomainType></code> 20is more similar to <code>std::error_code</code>, in that it can only represent failures 21(this is enforced by C++ 20 contract or runtime assertion check).</p></li> 22 23<li><p>The code’s domain implementation defines the payload type to be transported around by 24<code>experimental::status_code<DomainType></code>, rather than it being 25hardcoded to <code>int</code> as in <code>std::error_code</code>. The payload type can be anything 26you like, including non-trivially-copyable, move-only, complex etc types.</p> 27 28<p>This facility is extremely useful. Extra failure metadata such as stack 29backtraces can be returned, for example. You can absolutely vary the payload 30depending on whether <code>NDEBUG</code> or <code>_DEBUG</code> is defined, too.</p></li> 31 32<li><p>If your domain defines a payload type which is trivially copyable or 33move relocating<sup class="footnote-ref" id="fnref:1"><a href="#fn:1">1</a></sup>, it gains an implicit convertibility to a move-only 34<code>experimental::status_code<erased<T>></code> where <code>T</code> is another 35trivially copyable or move relocating type. This permits global headers 36to use a single, common, type erased, status code type which is highly 37desirable for code bases of any complexity. However, unlike <code>std::error_code</code>, 38which fulfils the exact same role in <code><system_error></code> based code, the type 39erased payload can be bigger than the hardcoded <code>int</code> in <code>std::error_code</code>.</p> 40 41<p>This facility is also extremely useful, as extra failure metadata can be 42type erased, transported through code with no knowledge of such things, 43and the original type with failure metadata resurrected at the handling point. 44Indeed P1095 proposed <code>std::error</code> is a type alias to 45<code>experimental::status_code<erased<intptr_t>></code>, and it can transport erased 46<code>std::exception_ptr</code> instances, POSIX error codes, and much more besides.</p></li> 47 48<li><p>Equality comparisons between status code’s with non-identical domains are 49always <b><em>semantic</em></b> i.e. are they semantically equivalent, rather than exactly 50equal? This mirrors when you compare <code>std::error_code</code> to a <code>std::error_condition</code>, 51but as there is no equivalent for the latter in <code><system_error2></code>, this means 52that when you see the code:</p> 53<div class="highlight"><pre class="chroma"><code class="language-c++" data-lang="c++"><span class="k">if</span><span class="p">(</span><span class="n">code1</span> <span class="o">==</span> <span class="n">code2</span><span class="p">)</span> <span class="p">...</span> 54</code></pre></div> 55<p>… you can be highly confident that this is an inexact, semantic, match operation. 56The same code under <code><system_error></code> is highly ambiguous as to whether exact 57or inexact comparison is being performed (after all, all there is is “<code>code1 == code2</code>”, 58so it depends on the types of <code>code1</code> and <code>code2</code> which usually is not obvious).</p> 59 60<p>The ambiguity, and high cognitive load during auditing <code><system_error></code> code for correctness, has 61led to many surprising and unexpected failure handling bugs during the past 62decade in production C++.</p></li> 63 64<li><p><code><system_error2></code>, being a new design, has all-constexpr construction and 65destruction which avoids the need for static global variables, as <code><system_error></code> 66has. Each of those static global variables requires an atomic fence just in 67case it has not been initialised, thus every retrieval of an error category bloats 68code and inhibits optimisation, plus makes the use of custom error code categories 69in header-only libraries unreliable. Boost.System has replicated the all-constexpr 70construction and destruction from <code><system_error2></code>, and thus now has similar 71characteristics in this regard.</p></li> 72 73<li><p>Finally, this is a small but important difference. Under <code><system_error></code>, 74this extremely common use case is ambiguous:</p> 75<div class="highlight"><pre class="chroma"><code class="language-c++" data-lang="c++"><span class="k">if</span><span class="p">(</span><span class="n">ec</span><span class="p">)</span> <span class="p">...</span> 76</code></pre></div> 77<p>Does this code mean “if there was an error?”, or “if the error code is set?”, 78or “is the error code non-zero?”. The correct answer according to the standard is the last choice, but 79a quick survey of open source <code><system_error></code> based code on github quickly 80demonstrates there is widespread confusion regarding correct usage.</p> 81 82<p><code><system_error2></code> solves this by removing the boolean test entirely. One 83now writes <code>if(sc.success()) ...</code>, <code>if(sc.failure()) ...</code>, <code>if(sc.empty()) ...</code> 84and so on, thus eliminating ambiguity.</p></li> 85</ol> 86<div class="footnotes"> 87 88<hr /> 89 90<ol> 91<li id="fn:1"><a href="http://wg21.link/P1029">Move relocating is not in the standard, nor has been reviewed by WG21 yet</a>. It is defined to be a type whose move constructor <code>memcpy()</code>’s the bits from source to destination, followed by <code>memcpy()</code> of the bits of a default constructed instance to source, and with a programmer-given guarantee that the destructor, when called on a default constructed instance, has no observable side effects. A surprising number of standard library types can meet this definition of move relocating, including <code>std::vector<T></code>, <code>std::shared_ptr<T></code>, and <code>std::exception_ptr</code>. 92 <a class="footnote-return" href="#fnref:1"><sup>[return]</sup></a></li> 93</ol> 94</div> 95 96 97 </div><p><small>Last revised: February 05, 2019 at 17:14:18 UTC</small></p> 98<hr> 99<div class="spirit-nav"> 100<a accesskey="p" href="../experimental/map.html"><img src="../images/prev.png" alt="Prev"></a> 101 <a accesskey="u" href="../experimental.html"><img src="../images/up.png" alt="Up"></a> 102 <a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="../experimental/status_result.html"><img src="../images/next.png" alt="Next"></a></div></body> 103</html> 104
