libs/outcome/doc/html/faq.html

   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>Frequently asked questions - 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="./reference/functions/try_throw_std_exception_from_error.html"><img src="./images/prev.png" alt="Prev"></a>
  11     <a accesskey="u" href="./index.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="./videos.html"><img src="./images/next.png" alt="Next"></a></div><div id="content">
  13
  14   <div class="titlepage"><div><div><h1 style="clear: both">Frequently asked questions</h1></div></div></div>
  15   <div class="toc"><dl class="toc">
  16 <dt>
  17 <dd><dl>
  18 <dt><a href="#is-outcome-safe-to-use-in-extern-apis">Is Outcome safe to use in extern APIs?</a></dt>
  19 <dt><a href="#does-outcome-implement-over-alignment">Does Outcome implement over-alignment?</a></dt>
  20 <dt><a href="#does-outcome-implement-the-no-fail-strong-or-basic-exception-guarantee">Does Outcome implement the no-fail, strong or basic exception guarantee?</a></dt>
  21 <dt><a href="#does-outcome-have-a-stable-abi-and-api">Does Outcome have a stable ABI and API?</a></dt>
  22 <dt><a href="#can-i-use-result-t-ec-across-dll-shared-object-boundaries">Can I use <code>result&lt;T, EC&gt;</code> across DLL/shared object boundaries?</a></dt>
  23 <dt><a href="#why-two-types-result-and-outcome-rather-than-just-one">Why two types <code>result&lt;&gt;</code>  and <code>outcome&lt;&gt;</code>, rather than just one?</a></dt>
  24 <dt><a href="#how-badly-will-including-outcome-in-my-public-interface-affect-compile-times">How badly will including Outcome in my public interface affect compile times?</a></dt>
  25 <dt><a href="#is-outcome-suitable-for-fixed-latency-predictable-execution-coding-such-as-for-high-frequency-trading-or-audio">Is Outcome suitable for fixed latency/predictable execution coding such as for high frequency trading or audio?</a></dt>
  26 <dt><a href="#what-kind-of-runtime-performance-impact-will-using-outcome-in-my-code-introduce">What kind of runtime performance impact will using Outcome in my code introduce?</a>
  27 <dd><dl>
  28 <dt><a href="#high-end-cpu-intel-skylake-x64">High end CPU: Intel Skylake x64</a></dt>
  29 <dt><a href="#mid-tier-cpu-arm-cortex-a72">Mid tier CPU: ARM Cortex A72</a></dt>
  30 <dt><a href="#low-end-cpus-intel-silvermont-x64-and-arm-cortex-a53">Low end CPUs: Intel Silvermont x64 and ARM Cortex A53</a></dt>
  31 </dl></dd></dt>
  32 <dt><a href="#why-is-implicit-default-construction-disabled">Why is implicit default construction disabled?</a></dt>
  33 <dt><a href="#how-far-away-from-the-proposed-std-expected-t-e-is-outcome-s-checked-t-e">How far away from the proposed <code>std::expected&lt;T, E&gt;</code> is Outcome&rsquo;s <code>checked&lt;T, E&gt;</code>?</a></dt>
  34 <dt><a href="#why-doesn-t-outcome-duplicate-std-expected-t-e-s-design">Why doesn&rsquo;t Outcome duplicate <code>std::expected&lt;T, E&gt;</code>&rsquo;s design?</a></dt>
  35 <dt><a href="#is-outcome-riddled-with-undefined-behaviour-for-const-const-containing-and-reference-containing-types">Is Outcome riddled with undefined behaviour for const, const-containing and reference-containing types?</a>
  36 <dd><dl>
  37 <dt><a href="#more-detail">More detail</a></dt>
  38 </dl></dd></dt>
  39 </dl></dd></dt>
  40 </dl>
  41   </div>
  42
  43
  44
  45
  46 <h2 id="is-outcome-safe-to-use-in-extern-apis">Is Outcome safe to use in extern APIs?</h2>
  47
  48 <p>Outcome is specifically designed for use in the public interfaces of multi-million
  49 line codebases. <code>result</code>&rsquo;s layout is hard coded to:</p>
  50 <div class="highlight"><pre class="chroma"><code class="language-c" data-lang="c"><span class="k">struct</span>
  51 <span class="p">{</span>
  52   <span class="n">T</span> <span class="n">value</span><span class="p">;</span>
  53   <span class="kt">unsigned</span> <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>
  54   <span class="n">EC</span> <span class="n">error</span><span class="p">;</span>
  55 <span class="p">};</span></code></pre></div>
  56 <p>This is C-compatible if <code>T</code> and <code>EC</code> are C-compatible.
  57 <a href="https://en.cppreference.com/w/cpp/error/error_code" class="api-reference" target="_blank"><i class="fa fa-book" aria-hidden="true"></i> <code>std::error_code</code></a>
  58
  59 is <em>probably</em> C-compatible, but its layout is not standardised (though there is a
  60 normative note in the standard about its layout). Hence Outcome cannot provide a
  61 C macro API for standard Outcome, but we can for <a href="./experimental/c-api.html">Experimental Outcome</a>.</p>
  62
  63 <h2 id="does-outcome-implement-over-alignment">Does Outcome implement over-alignment?</h2>
  64
  65 <p>Variant-based alternatives to Outcome such as
  66 <a href="https://wg21.link/P0323" class="api-reference" target="_blank"><i class="fa fa-book" aria-hidden="true"></i> P0323 <code>std::expected&lt;T, E&gt;</code></a>
  67
  68 would use <code>std::aligned_union</code> to ensure appropriate over-alignment for the storage of
  69 either a <code>T</code> or an <code>E</code>. This discovers the over-alignment for a type using
  70 <code>std::alignment_of</code>, which is defaulted to <code>alignof()</code>.</p>
  71
  72 <p>Outcome uses <code>struct</code>-based storage, as described above. Any over-alignment of
  73 <code>result</code> or <code>outcome</code> will follow the ordinary alignment and padding rules for
  74 <code>struct</code> on your compiler. Traits such as <code>std::alignment_of</code>, or other standard
  75 library facilities, are not used.</p>
  76
  77 <h2 id="does-outcome-implement-the-no-fail-strong-or-basic-exception-guarantee">Does Outcome implement the no-fail, strong or basic exception guarantee?</h2>
  78
  79 <p>(<a href="https://en.cppreference.com/w/cpp/language/exceptions#Exception_safety">You can read about the meaning of these guarantees at cppreference.com</a>)</p>
  80
  81 <p>If for the following operations:</p>
  82
  83 <ul>
  84 <li>Construction</li>
  85 <li>Assignment</li>
  86 <li>Swap</li>
  87 </ul>
  88
  89 <p>&hellip; the corresponding operation in <strong>all</strong> of <code>value_type</code>, <code>error_type</code> (and
  90 <code>exception_type</code> for <code>outcome</code>) is <code>noexcept(true)</code>, then <code>result</code> and
  91 <code>outcome</code>&rsquo;s operation is <code>noexcept(true)</code>. This propagates the no-fail exception
  92 guarantee of the underlying types. Otherwise the basic guarantee applies for all
  93 but Swap, under the same rules as for the <code>struct</code> layout type given above e.g.
  94 value would be constructed first, then the flags, then the error. If the error
  95 throws, value and status bits would be as if the failure had not occurred, same
  96 as for aborting the construction of any <code>struct</code> type.</p>
  97
  98 <p>It is recognised that these weak guarantees may be unsuitable for some people,
  99 so Outcome implements <code>swap()</code> with much stronger guarantees, as one can locally refine,
 100 without too much work, one&rsquo;s own custom classes from <code>result</code> and <code>outcome</code> implementing
 101 stronger guarantees for construction and assignment using <code>swap()</code> as the primitive
 102 building block.</p>
 103
 104 <p>The core ADL discovered implementation of strong guarantee swap is <a href="./reference/functions/strong_swap.html" class="api-reference"><code>strong_swap(bool &amp;all_good, T &amp;a, T &amp;b)</code></a>
 105 .
 106 This can be overloaded by third party code with custom strong guarantee swap
 107 implementations, same as for <code>std::swap()</code>. Because strong guarantee swap may fail
 108 when trying to restore input state during handling of failure to swap, the
 109 <code>all_good</code> boolean becomes false if restoration fails, at which point both
 110 results/outcomes get marked as tainted via <a href="./reference/types/basic_result/has_lost_consistency.html" class="api-reference"><code>has_lost_consistency()</code></a>
 111 .</p>
 112
 113 <p>It is <strong>up to you</strong> to check this flag to see if known good state has been lost,
 114 as Outcome never does so on your behalf. The simple solution to avoiding having
 115 to deal with this situation is to always choose your value, error and exception
 116 types to have non-throwing move constructors and move assignments. This causes
 117 the strong swap implementation to no longer be used, as it is no longer required,
 118 and standard swap is used instead.</p>
 119
 120 <h2 id="does-outcome-have-a-stable-abi-and-api">Does Outcome have a stable ABI and API?</h2>
 121
 122 <p>Right now, no. Though the data layout shown above is not expected to change.</p>
 123
 124 <p>Outcome&rsquo;s ABI and API will be formally fixed as <strong>the</strong> v2 interface approximately
 125 one year after its first Boost release. Thereafter the
 126 <a href="https://lvc.github.io/abi-compliance-checker/">ABI compliance checker</a>
 127 will be run per-commit to ensure Outcome&rsquo;s ABI and API remains stable.</p>
 128
 129 <p>Note that the stable ABI and API guarantee will only apply to standalone
 130 Outcome, not to Boost.Outcome. Boost.Outcome has dependencies on other
 131 parts of Boost which are not stable across releases.</p>
 132
 133 <p>Note also that the types you configure a <code>result</code> or <code>outcome</code> with also need
 134 to be ABI stable if <code>result</code> or <code>outcome</code> is to be ABI stable.</p>
 135
 136 <h2 id="can-i-use-result-t-ec-across-dll-shared-object-boundaries">Can I use <code>result&lt;T, EC&gt;</code> across DLL/shared object boundaries?</h2>
 137
 138 <p>A known problem with using DLLs (and to smaller extent shared libraries) is that global
 139 objects may get duplicated: one instance in the executable and one in the DLL. This
 140 behaviour is not incorrect according to the C++ Standard, as the Standard does not
 141 recognize the existence of DLLs or shared libraries. Therefore, program designs that
 142 depend on globals having unique addresses may become compromised when used in a program
 143 using DLLs.</p>
 144
 145 <p>Nothing in Outcome depends on the addresses of globals, plus the guaranteed fixed data
 146 layout (see answer above) means that different versions of Outcome can be used in
 147 different DLLs, and it probably will work okay (it is still not advised that you do that
 148 as that is an ODR violation).
 149 However, one of the most likely candidate for <code>EC</code> &ndash; <code>std::error_code</code> &ndash; does depend
 150 on the addresses of globals for correct functioning.</p>
 151
 152 <p>The standard library is required to implement globally unique addresses for the standard library
 153 provided
 154 <a href="https://en.cppreference.com/w/cpp/error/error_category" class="api-reference" target="_blank"><i class="fa fa-book" aria-hidden="true"></i> <code>std::error_category</code></a>
 155  implementations e.g. <code>std::system_category()</code>.
 156 User defined error code categories may <strong>not</strong> have unique global addresses, and thus
 157 introduce misoperation.</p>
 158
 159 <p><code>boost::system::error_code</code>, since version 1.69 does offer an <em>opt-in</em> guarantee
 160 that it does not depend on the addresses of globals <strong>if</strong> the user defined error code
 161 category <em>opts-in</em> to the 64-bit comparison mechanism. This can be seen in the specification of
 162 <code>error_category::operator==</code> in
 163 <a href="https://www.boost.org/doc/libs/1_69_0/libs/system/doc/html/system.html#ref_synopsis">Boost.System synopsis</a>.</p>
 164
 165 <p>Alternatively, the <code>status_code</code> in <a href="(/experimental/differences.html)">Experimental Outcome</a>,
 166 due to its more modern design, does not suffer from any problems from being used in shared
 167 libraries in any configuration.</p>
 168
 169 <h2 id="why-two-types-result-and-outcome-rather-than-just-one">Why two types <code>result&lt;&gt;</code>  and <code>outcome&lt;&gt;</code>, rather than just one?</h2>
 170
 171 <p><code>result</code> is the simple, success OR failure type.</p>
 172
 173 <p><code>outcome</code> extends <code>result</code> with a third state to transport, conventionally (but not necessarily) some sort of &ldquo;abort&rdquo; or &ldquo;exceptional&rdquo; state which a function can return to indicate that not only did the operation fail, but it did so <em>catastrophically</em> i.e. please abort any attempt to retry the operation.</p>
 174
 175 <p>A perfect alternative to using <code>outcome</code> is to throw a C++ exception for the abort code path, and indeed most programs ought to do exactly that instead of using <code>outcome</code>. However there are a number of use cases where choosing <code>outcome</code> shines:</p>
 176
 177 <ol>
 178 <li>Where C++ exceptions or RTTI is not available, but the ability to fail catastrophically without terminating the program is important.</li>
 179 <li>Where deterministic behaviour is required even in the catastrophic failure situation.</li>
 180 <li>In unit test suites of code using Outcome it is extremely convenient to accumulate test failures into an <code>outcome</code> for later reporting. A similar convenience applies to RPC situations, where C++ exception throws need to be accumulated for reporting back to the initiating endpoint.</li>
 181 <li>Where a function is &ldquo;dual use deterministic&rdquo; i.e. it can be used deterministically, in which case one switches control flow based on <code>.error()</code>, or it can be used non-deterministically by throwing an exception perhaps carrying a custom payload.</li>
 182 </ol>
 183
 184 <h2 id="how-badly-will-including-outcome-in-my-public-interface-affect-compile-times">How badly will including Outcome in my public interface affect compile times?</h2>
 185
 186 <p>The quick answer is that it depends on how much convenience you want.</p>
 187
 188 <p>The convenience header <code>&lt;result.hpp&gt;</code> is dependent on <code>&lt;system_error&gt;</code> or Boost.System, which unfortunately includes <code>&lt;string&gt;</code> and thus
 189 drags in quite a lot of other slow-to-parse stuff. If your public interface already includes <code>&lt;string&gt;</code>,
 190 then the impact of additionally including Outcome will be low. If you do not include <code>&lt;string&gt;</code>,
 191 unfortunately impact may be relatively quite high, depending on the total impact of your
 192 public interface files.</p>
 193
 194 <p>If you&rsquo;ve been extremely careful to avoid ever including the most of the STL headers
 195 into your interfaces in order to maximise build performance, then <code>&lt;basic_result.hpp&gt;</code>
 196 can have as few dependencies as:</p>
 197
 198 <ol>
 199 <li><code>&lt;cstdint&gt;</code></li>
 200 <li><code>&lt;initializer_list&gt;</code></li>
 201 <li><code>&lt;iosfwd&gt;</code></li>
 202 <li><code>&lt;new&gt;</code></li>
 203 <li><code>&lt;type_traits&gt;</code></li>
 204 <li><code>&lt;cstdio&gt;</code></li>
 205 <li><code>&lt;cstdlib&gt;</code></li>
 206 <li><code>&lt;cassert&gt;</code></li>
 207 </ol>
 208
 209 <p>These, apart from <code>&lt;iosfwd&gt;</code>, tend to be very low build time impact in most standard
 210 library implementations. If you include only <code>&lt;basic_result.hpp&gt;</code>, and manually configure
 211 <code>basic_result&lt;&gt;</code> by hand, compile time impact will be minimised.</p>
 212
 213 <p>(See reference documentation for <a href="./reference/types/basic_result.html" class="api-reference"><code>basic_result&lt;T, E, NoValuePolicy&gt;</code></a>
 214  for more detail.</p>
 215
 216 <h2 id="is-outcome-suitable-for-fixed-latency-predictable-execution-coding-such-as-for-high-frequency-trading-or-audio">Is Outcome suitable for fixed latency/predictable execution coding such as for high frequency trading or audio?</h2>
 217
 218 <p>Great care has been taken to ensure that Outcome never unexpectedly executes anything
 219 with unbounded execution times such as <code>malloc()</code>, <code>dynamic_cast&lt;&gt;()</code> or <code>throw</code>.
 220 Outcome works perfectly with C++ exceptions and RTTI globally disabled.</p>
 221
 222 <p>Outcome&rsquo;s entire design premise is that its users are happy to exchange a small, predictable constant overhead
 223 during successful code paths, in exchange for predictable failure code paths.</p>
 224
 225 <p>In contrast, table-based exception handling gives zero run time overhead for the
 226 successful code path, and completely unpredictable (and very expensive) overhead
 227 for failure code paths.</p>
 228
 229 <p>For code where predictability of execution, no matter the code path, is paramount,
 230 writing all your code to use Outcome is not a bad place to start. Obviously enough,
 231 do choose a non-throwing policy when configuring <code>outcome</code> or <code>result</code> such as
 232 <a href="./reference/policies/all_narrow.html" class="api-reference"><code>all_narrow</code></a>
 233  to guarantee that exceptions can never be thrown by Outcome
 234 (or use the convenience typedef for <code>result</code>, <a href="./reference/aliases/unchecked.html" class="api-reference"><code>unchecked&lt;T, E = varies&gt;</code></a>
 235  which uses <code>policy::all_narrow</code>).</p>
 236
 237 <h2 id="what-kind-of-runtime-performance-impact-will-using-outcome-in-my-code-introduce">What kind of runtime performance impact will using Outcome in my code introduce?</h2>
 238
 239 <p>It is very hard to say anything definitive about performance impacts in codebases one
 240 has never seen. Each codebase is unique. However to come up with some form of measure,
 241 we timed traversing ten stack frames via each of the main mechanisms, including the
 242 &ldquo;do nothing&rdquo; (null) case.</p>
 243
 244 <p>A stack frame is defined to be something called by the compiler whilst
 245 unwinding the stack between the point of return in the ultimate callee and the base
 246 caller, so for example ten stack allocated objects might be destructed, or ten levels
 247 of stack depth might be unwound. This is not a particularly realistic test, but it
 248 should at least give one an idea of the performance impact of returning Outcome&rsquo;s
 249 <code>result</code> or <code>outcome</code> over say returning a plain integer, or throwing an exception.</p>
 250
 251 <h3 id="high-end-cpu-intel-skylake-x64">High end CPU: Intel Skylake x64</h3>
 252
 253 <p>This is a high end CPU with very significant ability to cache, predict, parallelise
 254 and execute out-of-order such that tight, repeated loops perform very well. It has
 255 a large μop cache able to wholly contain the test loop, meaning that these results
 256 are a <strong>best case</strong> performance.</p>
 257
 258 <figure>
 259     <img src="./faq/results_skylake_log.png"/> <figcaption>
 260             <h4>Log graph comparing GCC 7.4, clang 8.0 and Visual Studio 2017.9 on x64, for exceptions-globally-disabled, ordinary and link-time-optimised build configurations.</h4>
 261         </figcaption>
 262 </figure>
 263
 264 <p>As you can see, throwing and catching an exception is
 265 expensive on table-based exception handling implementations such as these, anywhere
 266 between 26,000 and 43,000 CPU cycles. And this is the <em>hot path</em> situation, this
 267 benchmark is a loop around hot cached code. If the tables are paged out onto storage,
 268 you are talking about <strong>millions</strong> of CPU cycles.</p>
 269
 270 <p>Simple integer returns (i.e. do nothing null case)
 271 are always going to be the fastest as they do the least work, and that costs 80 to 90
 272 CPU cycles on this Intel Skylake CPU.</p>
 273
 274 <p>Note that returning a <code>result&lt;int, std::error_code&gt;</code> with a &ldquo;success (error code)&rdquo;
 275 is no more than 5% added runtime overhead over returning a naked int on GCC and clang. On MSVC
 276 it costs an extra 20% or so, mainly due to poor code optimisation in the VS2017.9 compiler. Note that &ldquo;success
 277 (experimental status code)&rdquo; optimises much better, and has almost no overhead over a
 278 naked int.</p>
 279
 280 <p>Returning a <code>result&lt;int, std::error_code&gt;</code> with a &ldquo;failure (error code)&rdquo;
 281 is less than 5% runtime overhead over returning a success on GCC, clang and MSVC.</p>
 282
 283 <p>You might wonder what happens if type <code>E</code> has a non-trivial destructor, thus making the
 284 <code>result&lt;T, E&gt;</code> have a non-trivial destructor? We tested <code>E = std::exception_ptr</code> and
 285 found less than a 5% overhead to <code>E = std::error_code</code> for returning success. Returning a failure
 286 was obviously much slower at anywhere between 300 and 1,100 CPU cycles, due to the
 287 dynamic memory allocation and free of the exception ptr, plus at least two atomic operations per stack frame, but that is
 288 still two orders of magnitude better than throwing and catching an exception.</p>
 289
 290 <p>We conclude that if failure is anything but extremely rare in your C++ codebase,
 291 using Outcome instead of throwing and catching exceptions ought to be quicker overall:</p>
 292
 293 <ul>
 294 <li>Experimental Outcome is statistically indistinguishable from the null case on this
 295 high end CPU, for both returning success and failure, on all compilers.</li>
 296 <li>Standard Outcome is less than 5%
 297 worse than the null case for returning successes on GCC and clang, and less than 10% worse than
 298 the null case for returning failures on GCC and clang.</li>
 299 <li>Standard Outcome optimises
 300 poorly on VS2017.9, indeed markedly worse than on previous point releases, so let&rsquo;s
 301 hope that Microsoft fix that soon. It currently has a less than 20% overhead on the null case.</li>
 302 </ul>
 303
 304 <h3 id="mid-tier-cpu-arm-cortex-a72">Mid tier CPU: ARM Cortex A72</h3>
 305
 306 <p>This is a four year old mid tier CPU used in many high end mobile phones and tablets
 307 of its day, with good ability to cache, predict, parallelise
 308 and execute out-of-order such that tight, repeated loops perform very well. It has
 309 a μop cache able to wholly contain the test loop, meaning that these results
 310 are a <strong>best case</strong> performance.</p>
 311
 312 <figure>
 313     <img src="./faq/results_arm_a72_log.png"/> <figcaption>
 314             <h4>Log graph comparing GCC 7.3 and clang 7.3 on ARM64, for exceptions-globally-disabled, ordinary and link-time-optimised build configurations.</h4>
 315         </figcaption>
 316 </figure>
 317
 318 <p>This ARM chip is a very consistent performer &ndash; null case, success, or failure, all take
 319 almost exactly the same CPU cycles. Choosing Outcome, in any configuration, makes no
 320 difference to not using Outcome at all. Throwing and catching a C++ exception costs
 321 about 90,000 CPU cycles, whereas the null case/Outcome costs about 130 - 140 CPU cycles.</p>
 322
 323 <p>There is very little to say about this CPU, other than Outcome is zero overhead on it. The same
 324 applied to the ARM Cortex A15 incidentally, which I test cased extensively when
 325 deciding on the Outcome v2 design back after the first peer review. The v2 design
 326 was chosen partially because of such consistent performance on ARM.</p>
 327
 328 <h3 id="low-end-cpus-intel-silvermont-x64-and-arm-cortex-a53">Low end CPUs: Intel Silvermont x64 and ARM Cortex A53</h3>
 329
 330 <p>These are low end CPUs with a mostly or wholly in-order execution core. They have a small
 331 or no μop cache, meaning that the CPU must always decode the instruction stream.
 332 These results represent an execution environment more typical of CPUs two decades
 333 ago, back when table-based EH created a big performance win if you never threw
 334 an exception.</p>
 335
 336 <p><figure>
 337     <img src="./faq/results_silvermont_log.png"/> <figcaption>
 338             <h4>Log graph comparing GCC 7.3 and clang 7.3 on x64, for exceptions-globally-disabled, ordinary and link-time-optimised build configurations.</h4>
 339         </figcaption>
 340 </figure>
 341 <figure>
 342     <img src="./faq/results_arm_a53_log.png"/> <figcaption>
 343             <h4>Log graph comparing GCC 7.3 and clang 7.3 on ARM64, for exceptions-globally-disabled, ordinary and link-time-optimised build configurations.</h4>
 344         </figcaption>
 345 </figure></p>
 346
 347 <p>The first thing to mention is that clang generates very high performance code for
 348 in-order cores, far better than GCC. It is said that this is due to a very large investment by
 349 Apple in clang/LLVM for their devices sustained over many years. In any case, if you&rsquo;re
 350 targeting in-order CPUs, don&rsquo;t use GCC if you can use clang instead!</p>
 351
 352 <p>For the null case, Silvermont and Cortex A53 are quite similar in terms of CPU clock cycles. Ditto
 353 for throwing and catching a C++ exception (approx 150,000 CPU cycles). However the Cortex
 354 A53 does far better with Outcome than Silvermont, a 15% versus 100% overhead for Standard
 355 Outcome, and a 4% versus 20% overhead for Experimental Outcome.</p>
 356
 357 <p>Much of this large difference is in fact due to calling convention differences. x64 permits up to 8 bytes
 358 to be returned from functions by CPU register. <code>result&lt;int&gt;</code> consumes 24 bytes, so on x64
 359 the compiler writes the return value to the stack. However ARM64 permits up to 64 bytes
 360 to be returned in registers, so <code>result&lt;int&gt;</code> is returned via CPU registers on ARM64.</p>
 361
 362 <p>On higher end CPUs, memory is read and written in cache lines (32 or 64 bytes), and
 363 reads and writes are coalesced and batched together by the out-of-order execution core. On these
 364 low end CPUs, memory is read and written sequentially per assembler instruction,
 365 so only one load or one store to L1
 366 cache can occur at a time. This makes writing the stack particularly slow on in-order
 367 CPUs. Memory operations which &ldquo;disappear&rdquo; on higher end CPUs take considerable time
 368 on low end CPUs. This particularly punishes Silvermont in a way which does not punish
 369 the Cortex A53, because of having to write multiple values to the stack to create the
 370 24 byte object to be returned.</p>
 371
 372 <p>The conclusion to take away from this is that if you are targeting a low end CPU,
 373 table-based EH still delivers significant performance improvements for the success
 374 code path. Unless determinism in failure is critically important, you should not
 375 use Outcome on in-order execution CPUs.</p>
 376
 377 <h2 id="why-is-implicit-default-construction-disabled">Why is implicit default construction disabled?</h2>
 378
 379 <p>This was one of the more interesting points of discussion during the peer review of
 380 Outcome v1. v1 had a formal empty state. This came with many advantages, but it
 381 was not felt to be STL idiomatic as <code>std::optional&lt;result&lt;T&gt;&gt;</code> is what was meant, so
 382 v2 has eliminated any legal possibility of being empty.</p>
 383
 384 <p>The <code>expected&lt;T, E&gt;</code> proposal of that time (May 2017) did permit default construction
 385 if its <code>T</code> type allowed default construction. This was specifically done to make
 386 <code>expected&lt;T, E&gt;</code> more useful in STL containers as one can say resize a vector without
 387 having to supply an <code>expected&lt;T, E&gt;</code> instance to fill the new items with. However
 388 there was some unease with that design choice, because it may cause programmers to
 389 use some type <code>T</code> whose default constructed state is overloaded with additional meaning,
 390 typically &ldquo;to be filled&rdquo; i.e. a de facto empty state via choosing a magic value.</p>
 391
 392 <p>For the v2 redesign, the various arguments during the v1 review were considered.
 393 Unlike <code>expected&lt;T, E&gt;</code> which is intended to be a general purpose Either monad
 394 vocabulary type, Outcome&rsquo;s types are meant primarily for returning success or failure
 395 from functions. The API should therefore encourage the programmer to not overload
 396 the successful type with additional meaning of &ldquo;to be filled&rdquo; e.g. <code>result&lt;std::optional&lt;T&gt;&gt;</code>.
 397 The decision was therefore taken to disable <em>implicit</em> default construction, but
 398 still permit <em>explicit</em> default construction by making the programmer spell out their
 399 intention with extra typing.</p>
 400
 401 <p>To therefore explicitly default construct a <code>result&lt;T&gt;</code> or <code>outcome&lt;T&gt;</code>, use one
 402 of these forms as is the most appropriate for the use case:</p>
 403
 404 <ol>
 405 <li>Construct with just <code>in_place_type&lt;T&gt;</code> e.g. <code>result&lt;T&gt;(in_place_type&lt;T&gt;)</code>.</li>
 406 <li>Construct via <code>success()</code> e.g. <code>outcome&lt;T&gt;(success())</code>.</li>
 407 <li>Construct from a <code>void</code> form e.g. <code>result&lt;T&gt;(result&lt;void&gt;(in_place_type&lt;void&gt;))</code>.</li>
 408 </ol>
 409
 410 <h2 id="how-far-away-from-the-proposed-std-expected-t-e-is-outcome-s-checked-t-e">How far away from the proposed <code>std::expected&lt;T, E&gt;</code> is Outcome&rsquo;s <code>checked&lt;T, E&gt;</code>?</h2>
 411
 412 <p>Not far, in fact after the first Boost.Outcome peer review in May 2017, Expected moved
 413 much closer to Outcome, and Outcome deliberately provides <a href="./reference/aliases/checked.html" class="api-reference"><code>checked&lt;T, E = varies&gt;</code></a>
 414
 415 as a semantic equivalent.</p>
 416
 417 <p>Here are the remaining differences which represent the
 418 divergence of consensus opinion between the Boost peer review and WG21 on the proper
 419 design for this object:</p>
 420
 421 <ol>
 422 <li><code>checked&lt;T, E&gt;</code> has no default constructor. Expected has a default constructor if
 423 <code>T</code> has a default constructor.</li>
 424 <li><code>checked&lt;T, E&gt;</code> uses the same constructor design as <code>std::variant&lt;...&gt;</code>. Expected
 425 uses the constructor design of <code>std::optional&lt;T&gt;</code>.</li>
 426 <li><code>checked&lt;T, E&gt;</code> cannot be modified after construction except by assignment.
 427 Expected provides an <code>.emplace()</code> modifier.</li>
 428 <li><code>checked&lt;T, E&gt;</code> permits implicit construction from both <code>T</code> and <code>E</code> when
 429 unambiguous. Expected permits implicit construction from <code>T</code> alone.</li>
 430 <li><code>checked&lt;T, E&gt;</code> does not permit <code>T</code> and <code>E</code> to be the same, and becomes annoying
 431 to use if they are constructible into one another (implicit construction self-disables).
 432 Expected permits <code>T</code> and <code>E</code> to be the same.</li>
 433 <li><code>checked&lt;T, E&gt;</code> throws <code>bad_result_access_with&lt;E&gt;</code> instead of Expected&rsquo;s
 434 <code>bad_expected_access&lt;E&gt;</code>.</li>
 435 <li><code>checked&lt;T, E&gt;</code> models <code>std::variant&lt;...&gt;</code>. Expected models <code>std::optional&lt;T&gt;</code>. Thus:
 436
 437 <ul>
 438 <li><code>checked&lt;T, E&gt;</code> does not provide <code>operator*()</code> nor <code>operator-&gt;</code></li>
 439 <li><code>checked&lt;T, E&gt;</code> <code>.error()</code> is wide (i.e. throws on no-value) like <code>.value()</code>.
 440 Expected&rsquo;s <code>.error()</code> is narrow (UB on no-error). [<code>checked&lt;T, E&gt;</code> provides
 441 <code>.assume_value()</code> and <code>.assume_error()</code> for narrow (UB causing) observers].</li>
 442 </ul></li>
 443 <li><code>checked&lt;T, E&gt;</code> uses <code>success&lt;T&gt;</code> and <code>failure&lt;E&gt;</code> type sugars for disambiguation.
 444 Expected uses <code>unexpected&lt;E&gt;</code> only.</li>
 445 <li><code>checked&lt;T, E&gt;</code> requires <code>E</code> to be default constructible.</li>
 446 <li><code>checked&lt;T, E&gt;</code> defaults <code>E</code> to <code>std::error_code</code> or <code>boost::system::error_code</code>.
 447 Expected does not default <code>E</code>.</li>
 448 </ol>
 449
 450 <p>In fact, the two are sufficiently close in design that a highly conforming <code>expected&lt;T, E&gt;</code>
 451 can be implemented by wrapping up <code>checked&lt;T, E&gt;</code> with the differing functionality:</p>
 452
 453 <div class="code-snippet"><div class="highlight"><pre class="chroma"><code class="language-c++" data-lang="c++"><span class="cm">/* Here is a fairly conforming implementation of P0323R3 `expected&lt;T, E&gt;` using `checked&lt;T, E&gt;`.
 454 </span><span class="cm">It passes the reference test suite for P0323R3 at
 455 </span><span class="cm">https://github.com/viboes/std-make/blob/master/test/expected/expected_pass.cpp with modifications
 456 </span><span class="cm">only to move the test much closer to the P0323R3 Expected, as the reference test suite is for a
 457 </span><span class="cm">much older proposed Expected.
 458 </span><span class="cm">
 459 </span><span class="cm">Known differences from P0323R3 in this implementation:
 460 </span><span class="cm">- `T` and `E` cannot be the same type.
 461 </span><span class="cm">- `E` must be default constructible.
 462 </span><span class="cm">- No variant storage is implemented (note the Expected proposal does not actually require this).
 463 </span><span class="cm">*/</span>
 464
 465 <span class="k">namespace</span> <span class="n">detail</span>
 466 <span class="p">{</span>
 467   <span class="k">template</span> <span class="o">&lt;</span><span class="k">class</span><span class="err"> </span><span class="nc">T</span><span class="p">,</span> <span class="k">class</span><span class="err"> </span><span class="nc">E</span><span class="o">&gt;</span> <span class="k">using</span> <span class="n">expected_result</span> <span class="o">=</span> <span class="n">BOOST_OUTCOME_V2_NAMESPACE</span><span class="o">::</span><span class="n">checked</span><span class="o">&lt;</span><span class="n">T</span><span class="p">,</span> <span class="n">E</span><span class="o">&gt;</span><span class="p">;</span>
 468   <span class="k">template</span> <span class="o">&lt;</span><span class="k">class</span><span class="err"> </span><span class="nc">T</span><span class="p">,</span> <span class="k">class</span><span class="err"> </span><span class="nc">E</span><span class="o">&gt;</span> <span class="k">struct</span> <span class="nl">enable_default_constructor</span> <span class="p">:</span> <span class="k">public</span> <span class="n">expected_result</span><span class="o">&lt;</span><span class="n">T</span><span class="p">,</span> <span class="n">E</span><span class="o">&gt;</span>
 469   <span class="p">{</span>
 470     <span class="k">using</span> <span class="n">base</span> <span class="o">=</span> <span class="n">expected_result</span><span class="o">&lt;</span><span class="n">T</span><span class="p">,</span> <span class="n">E</span><span class="o">&gt;</span><span class="p">;</span>
 471     <span class="k">using</span> <span class="n">base</span><span class="o">::</span><span class="n">base</span><span class="p">;</span>
 472     <span class="k">constexpr</span> <span class="nf">enable_default_constructor</span><span class="p">()</span>
 473         <span class="o">:</span> <span class="n">base</span><span class="p">{</span><span class="n">BOOST_OUTCOME_V2_NAMESPACE</span><span class="o">::</span><span class="n">in_place_type</span><span class="o">&lt;</span><span class="n">T</span><span class="o">&gt;</span><span class="p">}</span>
 474     <span class="p">{</span>
 475     <span class="p">}</span>
 476   <span class="p">};</span>
 477   <span class="k">template</span> <span class="o">&lt;</span><span class="k">class</span><span class="err"> </span><span class="nc">T</span><span class="p">,</span> <span class="k">class</span><span class="err"> </span><span class="nc">E</span><span class="o">&gt;</span> <span class="k">using</span> <span class="n">select_expected_base</span> <span class="o">=</span> <span class="n">std</span><span class="o">::</span><span class="n">conditional_t</span><span class="o">&lt;</span><span class="n">std</span><span class="o">::</span><span class="n">is_default_constructible</span><span class="o">&lt;</span><span class="n">T</span><span class="o">&gt;::</span><span class="n">value</span><span class="p">,</span> <span class="n">enable_default_constructor</span><span class="o">&lt;</span><span class="n">T</span><span class="p">,</span> <span class="n">E</span><span class="o">&gt;</span><span class="p">,</span> <span class="n">expected_result</span><span class="o">&lt;</span><span class="n">T</span><span class="p">,</span> <span class="n">E</span><span class="o">&gt;&gt;</span><span class="p">;</span>
 478 <span class="p">}</span>
 479 <span class="k">template</span> <span class="o">&lt;</span><span class="k">class</span><span class="err"> </span><span class="nc">T</span><span class="p">,</span> <span class="k">class</span><span class="err"> </span><span class="nc">E</span><span class="o">&gt;</span> <span class="k">class</span><span class="err"> </span><span class="nc">expected</span> <span class="o">:</span> <span class="k">public</span> <span class="n">detail</span><span class="o">::</span><span class="n">select_expected_base</span><span class="o">&lt;</span><span class="n">T</span><span class="p">,</span> <span class="n">E</span><span class="o">&gt;</span>
 480 <span class="p">{</span>
 481   <span class="k">static_assert</span><span class="p">(</span><span class="o">!</span><span class="n">std</span><span class="o">::</span><span class="n">is_same</span><span class="o">&lt;</span><span class="n">T</span><span class="p">,</span> <span class="n">E</span><span class="o">&gt;::</span><span class="n">value</span><span class="p">,</span> <span class="s">&#34;T and E cannot be the same in this expected implementation&#34;</span><span class="p">);</span>
 482   <span class="k">using</span> <span class="n">base</span> <span class="o">=</span> <span class="n">detail</span><span class="o">::</span><span class="n">select_expected_base</span><span class="o">&lt;</span><span class="n">T</span><span class="p">,</span> <span class="n">E</span><span class="o">&gt;</span><span class="p">;</span>
 483
 484 <span class="k">public</span><span class="o">:</span>
 485   <span class="c1">// Inherit base&#39;s constructors
 486 </span><span class="c1"></span>  <span class="k">using</span> <span class="n">base</span><span class="o">::</span><span class="n">base</span><span class="p">;</span>
 487   <span class="n">expected</span><span class="p">()</span> <span class="o">=</span> <span class="k">default</span><span class="p">;</span>
 488
 489   <span class="c1">// Expected takes in_place not in_place_type
 490 </span><span class="c1"></span>  <span class="k">template</span> <span class="o">&lt;</span><span class="k">class</span><span class="err">... </span><span class="nc">Args</span><span class="o">&gt;</span>
 491   <span class="k">constexpr</span> <span class="k">explicit</span> <span class="n">expected</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">in_place_t</span> <span class="cm">/*unused*/</span><span class="p">,</span> <span class="n">Args</span> <span class="o">&amp;&amp;</span><span class="p">...</span> <span class="n">args</span><span class="p">)</span>
 492       <span class="o">:</span> <span class="n">base</span><span class="p">{</span><span class="n">BOOST_OUTCOME_V2_NAMESPACE</span><span class="o">::</span><span class="n">in_place_type</span><span class="o">&lt;</span><span class="n">T</span><span class="o">&gt;</span><span class="p">,</span> <span class="n">std</span><span class="o">::</span><span class="n">forward</span><span class="o">&lt;</span><span class="n">Args</span><span class="o">&gt;</span><span class="p">(</span><span class="n">args</span><span class="p">)...}</span>
 493   <span class="p">{</span>
 494   <span class="p">}</span>
 495
 496   <span class="c1">// Expected always accepts a T even if ambiguous
 497 </span><span class="c1"></span>  <span class="n">BOOST_OUTCOME_TEMPLATE</span><span class="p">(</span><span class="k">class</span><span class="err"> </span><span class="nc">U</span><span class="p">)</span>
 498   <span class="n">BOOST_OUTCOME_TREQUIRES</span><span class="p">(</span><span class="n">BOOST_OUTCOME_TPRED</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">is_constructible</span><span class="o">&lt;</span><span class="n">T</span><span class="p">,</span> <span class="n">U</span><span class="o">&gt;::</span><span class="n">value</span><span class="p">))</span>
 499   <span class="k">constexpr</span> <span class="n">expected</span><span class="p">(</span><span class="n">U</span> <span class="o">&amp;&amp;</span><span class="n">v</span><span class="p">)</span>
 500       <span class="o">:</span> <span class="n">base</span><span class="p">{</span><span class="n">BOOST_OUTCOME_V2_NAMESPACE</span><span class="o">::</span><span class="n">in_place_type</span><span class="o">&lt;</span><span class="n">T</span><span class="o">&gt;</span><span class="p">,</span> <span class="n">std</span><span class="o">::</span><span class="n">forward</span><span class="o">&lt;</span><span class="n">U</span><span class="o">&gt;</span><span class="p">(</span><span class="n">v</span><span class="p">)}</span>
 501   <span class="p">{</span>
 502   <span class="p">}</span>
 503
 504   <span class="c1">// Expected has an emplace() modifier
 505 </span><span class="c1"></span>  <span class="k">template</span> <span class="o">&lt;</span><span class="k">class</span><span class="err">... </span><span class="nc">Args</span><span class="o">&gt;</span> <span class="kt">void</span> <span class="n">emplace</span><span class="p">(</span><span class="n">Args</span> <span class="o">&amp;&amp;</span><span class="p">...</span> <span class="n">args</span><span class="p">)</span> <span class="p">{</span> <span class="o">*</span><span class="k">static_cast</span><span class="o">&lt;</span><span class="n">base</span> <span class="o">*&gt;</span><span class="p">(</span><span class="k">this</span><span class="p">)</span> <span class="o">=</span> <span class="n">base</span><span class="p">{</span><span class="n">BOOST_OUTCOME_V2_NAMESPACE</span><span class="o">::</span><span class="n">in_place_type</span><span class="o">&lt;</span><span class="n">T</span><span class="o">&gt;</span><span class="p">,</span> <span class="n">std</span><span class="o">::</span><span class="n">forward</span><span class="o">&lt;</span><span class="n">Args</span><span class="o">&gt;</span><span class="p">(</span><span class="n">args</span><span class="p">)...};</span> <span class="p">}</span>
 506
 507   <span class="c1">// Expected has a narrow operator* and operator-&gt;
 508 </span><span class="c1"></span>  <span class="k">constexpr</span> <span class="k">const</span> <span class="n">T</span> <span class="o">&amp;</span><span class="k">operator</span><span class="o">*</span><span class="p">()</span> <span class="k">const</span> <span class="o">&amp;</span> <span class="p">{</span> <span class="k">return</span> <span class="n">base</span><span class="o">::</span><span class="n">assume_value</span><span class="p">();</span> <span class="p">}</span>
 509   <span class="k">constexpr</span> <span class="n">T</span> <span class="o">&amp;</span><span class="k">operator</span><span class="o">*</span><span class="p">()</span> <span class="o">&amp;</span> <span class="p">{</span> <span class="k">return</span> <span class="n">base</span><span class="o">::</span><span class="n">assume_value</span><span class="p">();</span> <span class="p">}</span>
 510   <span class="k">constexpr</span> <span class="k">const</span> <span class="n">T</span> <span class="o">&amp;&amp;</span><span class="k">operator</span><span class="o">*</span><span class="p">()</span> <span class="k">const</span> <span class="o">&amp;&amp;</span> <span class="p">{</span> <span class="k">return</span> <span class="n">base</span><span class="o">::</span><span class="n">assume_value</span><span class="p">();</span> <span class="p">}</span>
 511   <span class="k">constexpr</span> <span class="n">T</span> <span class="o">&amp;&amp;</span><span class="k">operator</span><span class="o">*</span><span class="p">()</span> <span class="o">&amp;&amp;</span> <span class="p">{</span> <span class="k">return</span> <span class="n">base</span><span class="o">::</span><span class="n">assume_value</span><span class="p">();</span> <span class="p">}</span>
 512   <span class="k">constexpr</span> <span class="k">const</span> <span class="n">T</span> <span class="o">*</span><span class="k">operator</span><span class="o">-&gt;</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span> <span class="k">return</span> <span class="o">&amp;</span><span class="n">base</span><span class="o">::</span><span class="n">assume_value</span><span class="p">();</span> <span class="p">}</span>
 513   <span class="k">constexpr</span> <span class="n">T</span> <span class="o">*</span><span class="k">operator</span><span class="o">-&gt;</span><span class="p">()</span> <span class="p">{</span> <span class="k">return</span> <span class="o">&amp;</span><span class="n">base</span><span class="o">::</span><span class="n">assume_value</span><span class="p">();</span> <span class="p">}</span>
 514
 515   <span class="c1">// Expected has a narrow error() observer
 516 </span><span class="c1"></span>  <span class="k">constexpr</span> <span class="k">const</span> <span class="n">E</span> <span class="o">&amp;</span><span class="n">error</span><span class="p">()</span> <span class="k">const</span> <span class="o">&amp;</span> <span class="p">{</span> <span class="k">return</span> <span class="n">base</span><span class="o">::</span><span class="n">assume_error</span><span class="p">();</span> <span class="p">}</span>
 517   <span class="k">constexpr</span> <span class="n">E</span> <span class="o">&amp;</span><span class="n">error</span><span class="p">()</span> <span class="o">&amp;</span> <span class="p">{</span> <span class="k">return</span> <span class="n">base</span><span class="o">::</span><span class="n">assume_error</span><span class="p">();</span> <span class="p">}</span>
 518   <span class="k">constexpr</span> <span class="k">const</span> <span class="n">E</span> <span class="o">&amp;&amp;</span><span class="n">error</span><span class="p">()</span> <span class="k">const</span> <span class="o">&amp;&amp;</span> <span class="p">{</span> <span class="k">return</span> <span class="n">base</span><span class="o">::</span><span class="n">assume_error</span><span class="p">();</span> <span class="p">}</span>
 519   <span class="k">constexpr</span> <span class="n">E</span> <span class="o">&amp;</span><span class="n">error</span><span class="p">()</span> <span class="o">&amp;&amp;</span> <span class="p">{</span> <span class="k">return</span> <span class="n">base</span><span class="o">::</span><span class="n">assume_error</span><span class="p">();</span> <span class="p">}</span>
 520 <span class="p">};</span>
 521 <span class="k">template</span> <span class="o">&lt;</span><span class="k">class</span><span class="err"> </span><span class="nc">E</span><span class="o">&gt;</span> <span class="k">class</span><span class="err"> </span><span class="nc">expected</span><span class="o">&lt;</span><span class="kt">void</span><span class="p">,</span> <span class="n">E</span><span class="o">&gt;</span> <span class="o">:</span> <span class="k">public</span> <span class="n">BOOST_OUTCOME_V2_NAMESPACE</span><span class="o">::</span><span class="n">result</span><span class="o">&lt;</span><span class="kt">void</span><span class="p">,</span> <span class="n">E</span><span class="p">,</span> <span class="n">BOOST_OUTCOME_V2_NAMESPACE</span><span class="o">::</span><span class="n">policy</span><span class="o">::</span><span class="n">throw_bad_result_access</span><span class="o">&lt;</span><span class="n">E</span><span class="p">,</span> <span class="kt">void</span><span class="o">&gt;&gt;</span>
 522 <span class="p">{</span>
 523   <span class="k">using</span> <span class="n">base</span> <span class="o">=</span> <span class="n">BOOST_OUTCOME_V2_NAMESPACE</span><span class="o">::</span><span class="n">result</span><span class="o">&lt;</span><span class="kt">void</span><span class="p">,</span> <span class="n">E</span><span class="p">,</span> <span class="n">BOOST_OUTCOME_V2_NAMESPACE</span><span class="o">::</span><span class="n">policy</span><span class="o">::</span><span class="n">throw_bad_result_access</span><span class="o">&lt;</span><span class="n">E</span><span class="p">,</span> <span class="kt">void</span><span class="o">&gt;&gt;</span><span class="p">;</span>
 524
 525 <span class="k">public</span><span class="o">:</span>
 526   <span class="c1">// Inherit base constructors
 527 </span><span class="c1"></span>  <span class="k">using</span> <span class="n">base</span><span class="o">::</span><span class="n">base</span><span class="p">;</span>
 528
 529   <span class="c1">// Expected has a narrow operator* and operator-&gt;
 530 </span><span class="c1"></span>  <span class="k">constexpr</span> <span class="kt">void</span> <span class="k">operator</span><span class="o">*</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span> <span class="n">base</span><span class="o">::</span><span class="n">assume_value</span><span class="p">();</span> <span class="p">}</span>
 531   <span class="k">constexpr</span> <span class="kt">void</span> <span class="k">operator</span><span class="o">-&gt;</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span> <span class="n">base</span><span class="o">::</span><span class="n">assume_value</span><span class="p">();</span> <span class="p">}</span>
 532 <span class="p">};</span>
 533 <span class="k">template</span> <span class="o">&lt;</span><span class="k">class</span><span class="err"> </span><span class="nc">E</span><span class="o">&gt;</span> <span class="k">using</span> <span class="n">unexpected</span> <span class="o">=</span> <span class="n">BOOST_OUTCOME_V2_NAMESPACE</span><span class="o">::</span><span class="n">failure_type</span><span class="o">&lt;</span><span class="n">E</span><span class="o">&gt;</span><span class="p">;</span>
 534 <span class="k">template</span> <span class="o">&lt;</span><span class="k">class</span><span class="err"> </span><span class="nc">E</span><span class="o">&gt;</span> <span class="n">unexpected</span><span class="o">&lt;</span><span class="n">E</span><span class="o">&gt;</span> <span class="n">make_unexpected</span><span class="p">(</span><span class="n">E</span> <span class="o">&amp;&amp;</span><span class="n">arg</span><span class="p">)</span>
 535 <span class="p">{</span>
 536   <span class="k">return</span> <span class="n">BOOST_OUTCOME_V2_NAMESPACE</span><span class="o">::</span><span class="n">failure</span><span class="o">&lt;</span><span class="n">E</span><span class="o">&gt;</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">forward</span><span class="o">&lt;</span><span class="n">E</span><span class="o">&gt;</span><span class="p">(</span><span class="n">arg</span><span class="p">));</span>
 537 <span class="p">}</span>
 538 <span class="k">template</span> <span class="o">&lt;</span><span class="k">class</span><span class="err"> </span><span class="nc">E</span><span class="p">,</span> <span class="k">class</span><span class="err">... </span><span class="nc">Args</span><span class="o">&gt;</span> <span class="n">unexpected</span><span class="o">&lt;</span><span class="n">E</span><span class="o">&gt;</span> <span class="n">make_unexpected</span><span class="p">(</span><span class="n">Args</span> <span class="o">&amp;&amp;</span><span class="p">...</span> <span class="n">args</span><span class="p">)</span>
 539 <span class="p">{</span>
 540   <span class="k">return</span> <span class="n">BOOST_OUTCOME_V2_NAMESPACE</span><span class="o">::</span><span class="n">failure</span><span class="o">&lt;</span><span class="n">E</span><span class="o">&gt;</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">forward</span><span class="o">&lt;</span><span class="n">Args</span><span class="o">&gt;</span><span class="p">(</span><span class="n">args</span><span class="p">)...);</span>
 541 <span class="p">}</span>
 542 <span class="k">template</span> <span class="o">&lt;</span><span class="k">class</span><span class="err"> </span><span class="nc">E</span><span class="o">&gt;</span> <span class="k">using</span> <span class="n">bad_expected_access</span> <span class="o">=</span> <span class="n">BOOST_OUTCOME_V2_NAMESPACE</span><span class="o">::</span><span class="n">bad_result_access_with</span><span class="o">&lt;</span><span class="n">E</span><span class="o">&gt;</span><span class="p">;</span>
 543 </code></pre></div><a href="https://github.com/boostorg/outcome/tree/master/doc/src/snippets/expected_implementation.cpp#L35" class="code-snippet-url" target="_blank">View this code on Github</a></div>
 544
 545
 546 <h2 id="why-doesn-t-outcome-duplicate-std-expected-t-e-s-design">Why doesn&rsquo;t Outcome duplicate <code>std::expected&lt;T, E&gt;</code>&rsquo;s design?</h2>
 547
 548 <p>There are a number of reasons:</p>
 549
 550 <ol>
 551 <li><p>Outcome is not aimed at the same audience as Expected. We target developers
 552 and users who would be happy to use Boost. Expected targets the standard library user.</p></li>
 553
 554 <li><p>Outcome believes that the monadic use case isn&rsquo;t as important as Expected does.
 555 Specifically, we think that 99% of use of Expected in the real world will be to
 556 return failure from functions, and not as some sort of enhanced or &ldquo;rich&rdquo; Optional.
 557 Outcome therefore models a subset of Variant, whereas Expected models an extended Optional.</p></li>
 558
 559 <li><p>Outcome believes that if you are thinking about using something like Outcome,
 560 then for you writing failure code will be in the same proportion as writing success code,
 561 and thus in Outcome writing for failure is exactly the same as writing for success.
 562 Expected assumes that success will be more common than failure, and makes you type
 563 more when writing for failure.</p></li>
 564
 565 <li><p>Outcome goes to considerable effort to help the end user type fewer characters
 566 during use. This results in tighter, less verbose, more succinct code. The cost of this is a steeper
 567 learning curve and more complex mental model than when programming with Expected.</p></li>
 568
 569 <li><p>Outcome has facilities to make easier interoperation between multiple third
 570 party libraries each using incommensurate Outcome (or Expected) configurations. Expected does
 571 not do any of this, but subsequent WG21 papers do propose various interoperation
 572 mechanisms, <a href="https://wg21.link/P0786">one of which</a> Outcome implements so code using Expected will seamlessly
 573 interoperate with code using Outcome.</p></li>
 574 </ol>
 575
 576 <h2 id="is-outcome-riddled-with-undefined-behaviour-for-const-const-containing-and-reference-containing-types">Is Outcome riddled with undefined behaviour for const, const-containing and reference-containing types?</h2>
 577
 578 <p>The short answer is not any more in C++ 20 and after, thanks to changes made to
 579 C++ 20 at the Belfast WG21 meeting in November 2019.</p>
 580
 581 <p>The longer answer is that before C++ 20, use of placement
 582 new on types containing <code>const</code> member types where the resulting pointer was
 583 thrown away is undefined behaviour. As of the resolution of a national body
 584 comment, this is no longer the case, and now Outcome is free of this particular
 585 UB for C++ 20 onwards.</p>
 586
 587 <p>This still affects C++ before 20, though no major compiler is affected. Still,
 588 if you wish to avoid UB, don&rsquo;t use <code>const</code> types within Outcome types (or any
 589 <code>optional&lt;T&gt;</code>, or <code>vector&lt;T&gt;</code> or any STL container type for that matter).</p>
 590
 591 <h3 id="more-detail">More detail</h3>
 592
 593 <p>Before the C++ 14 standard, placement new into storage which used to contain
 594 a const type was straight out always undefined behaviour, period. Thus all use of
 595 placement new within a <code>result&lt;const_containing_type&gt;</code>, or indeed an <code>optional&lt;const_containing_type&gt;</code>, is always
 596 undefined behaviour before C++ 14. From <code>[basic.life]</code> for the C++ 11 standard:</p>
 597
 598 <blockquote>
 599 <p>Creating a new object at the storage location that a const object with static,
 600 thread, or automatic storage duration occupies or, at the storage location
 601 that such a const object used to occupy before its lifetime ended results
 602 in undefined behavior.</p>
 603 </blockquote>
 604
 605 <p>This being excessively restrictive, from C++ 14 onwards, <code>[basic_life]</code> now states:</p>
 606
 607 <blockquote>
 608 <p>If, after the lifetime of an object has ended and before the storage which
 609 the object occupied is reused or released, a new object is created at the
 610 storage location which the original object occupied, a pointer that
 611 pointed to the original object, a reference that referred to the original
 612 object, or the name of the original object will automatically refer to the
 613 new object and, once the lifetime of the new object has started, can be
 614 used to manipulate the new object, if:</p>
 615
 616 <p>— the storage for the new object exactly overlays the storage location which
 617     the original object occupied, and</p>
 618
 619 <p>— the new object is of the same type as the original object (ignoring the
 620     top-level cv-qualifiers), and</p>
 621
 622 <p>— the type of the original object is not const-qualified, and, if a class type,
 623     does not contain any non-static data member whose type is const-qualified
 624     or a reference type, and</p>
 625
 626 <p>— neither the original object nor the new object is a potentially-overlapping
 627     subobject</p>
 628 </blockquote>
 629
 630 <p>Leaving aside my personal objections to giving placement new of non-const
 631 non-reference types magical pointer renaming powers, the upshot is that if
 632 you want defined behaviour for placement new of types containing const types
 633 or references, you must store the pointer returned by placement new, and use
 634 that pointer for all further reference to the newly created object. This
 635 obviously adds eight bytes of storage to a <code>result&lt;const_containing_type&gt;</code>, which is highly
 636 undesirable given all the care and attention paid to keeping it small. The alternative
 637 is to use
 638 <a href="https://en.cppreference.com/w/cpp/utility/launder" class="api-reference" target="_blank"><i class="fa fa-book" aria-hidden="true"></i> <code>std::launder</code></a>
 639 , which was added in C++ 17, to &lsquo;launder&rsquo;
 640 the storage into which we placement new before each and every use of that
 641 storage. This forces the compiler to reload the object stored by placement
 642 new on every occasion, and not assume it can be constant propagated, which
 643 impacts codegen quality.</p>
 644
 645 <p>As mentioned above, this issue (in so far as it applies to types containing
 646 user supplied <code>T</code> which might be <code>const</code>) has been resolved as of C++ 20 onwards,
 647 and it is extremely unlikely that any C++ compiler will act on any UB here in
 648 C++ 17 or 14 given how much of STL containers would break.</p>
 649
 650
 651
 652         </div><p><small>Last revised: November 15, 2019 at 15:43:29 UTC</small></p>
 653 <hr>
 654 <div class="spirit-nav">
 655 <a accesskey="p" href="./reference/functions/try_throw_std_exception_from_error.html"><img src="./images/prev.png" alt="Prev"></a>
 656     <a accesskey="u" href="./index.html"><img src="./images/up.png" alt="Up"></a>
 657     <a accesskey="h" href="./index.html"><img src="./images/home.png" alt="Home"></a><a accesskey="n" href="./videos.html"><img src="./images/next.png" alt="Next"></a></div></body>
 658 </html>