113 lines
7.2 KiB
HTML
113 lines
7.2 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html><meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<title>Experimental - Boost.Outcome documentation</title>
|
|
<link rel="stylesheet" href="./css/boost.css" type="text/css">
|
|
<meta name="generator" content="Hugo 0.52 with Boostdoc theme">
|
|
<meta name="viewport" content="width=device-width,initial-scale=1.0"/>
|
|
|
|
<link rel="icon" href="./images/favicon.ico" type="image/ico"/>
|
|
<body><div class="spirit-nav">
|
|
<a accesskey="p" href="./recipes/foreign-try.html"><img src="./images/prev.png" alt="Prev"></a>
|
|
<a accesskey="u" href="./index.html"><img src="./images/up.png" alt="Up"></a>
|
|
<a accesskey="h" href="./index.html"><img src="./images/home.png" alt="Home"></a><a accesskey="n" href="./experimental/advantages.html"><img src="./images/next.png" alt="Next"></a></div><div id="content">
|
|
|
|
<div class="titlepage"><div><div><h1 style="clear: both">Experimental</h1></div></div></div>
|
|
<p>In <code><boost/outcome/experimental></code>, there ships an Outcome-based simulation of
|
|
the proposed <a href="https://wg21.link/P1095">P1095 <em>Zero overhead deterministic failure</em></a>
|
|
specific implementation of <a href="http://wg21.link/P0709">P0709 <em>Zero overhead exceptions: Throwing values</em></a>.
|
|
This library-only implementation lets you use a close simulacrum
|
|
of potential future C++ lightweight exceptions today in <a href="./requirements.html">any C++ 14 compiler
|
|
which Outcome supports</a>.</p>
|
|
|
|
<p>This Experimental Outcome implementation has been in production use for some
|
|
years now. It has shipped on at least one billion devices, as part of a
|
|
games suite very popular on Microsoft Windows, Apple iOS and Google Android
|
|
devices. It powers big iron enterprise applications as well, indeed all
|
|
trades including futures in the United States are captured live into a database
|
|
for the SEC by an Experimental Outcome based codebase. Finally, Experimental
|
|
Outcome is used in the firmware of parts of driver assisting cars where its
|
|
particularly rich and flexible failure added information combined with
|
|
compatibility with globally disabled C++ exceptions proved to be a big win.</p>
|
|
|
|
<p>The base for failure handling in future C++ might be <code>std::error</code> from <a href="https://wg21.link/P1028">P1028
|
|
<code>status_code</code></a>. This proposal is currently being
|
|
refined before WG21’s Library Evolution Working Group with the expectation that
|
|
it will be standardised as a large enhancement and backwards compatible superset
|
|
of <code>std::error_code</code> which is also capable of transporting any move-only type
|
|
such as <code>std::exception_ptr</code>. Like <code>std::error_code</code>, proposed <code>std::error</code>
|
|
occupies exactly two CPU registers of layout, and thus is extremely lightweight.
|
|
It can wrap arbitrary third party error handling systems, and automatically
|
|
constructs from <code>std::error_code</code> and <code>std::exception_ptr</code>, propagating the
|
|
original underlying implementations (no matter how customised) exactly (e.g.
|
|
<code>boost::exception_ptr</code>). Unlike <code><system_error></code>, <code>std::error</code> does not have
|
|
dependencies on expensive standard library headers, so including it into your
|
|
global build has a very low build time impact. <code>std::error</code> knows how to throw
|
|
itself as a conventional C++ exception, and knows how to losslessly consume
|
|
arbitrary C++ exception throws. Finally, <code>std::error</code> is ABI stable, and is
|
|
a <a href="https://wg21.link/P1029">P1029 move bitcopying</a> type whereby moved-from
|
|
objects do not need to be destroyed.</p>
|
|
|
|
<hr />
|
|
|
|
<p>Experimental Outcome uses the <a href="https://wg21.link/P1028">same proposed <code>std::error</code> object as P1095 would do
|
|
for its <code>E</code> type</a> by bundling internally a copy of
|
|
<a href="https://ned14.github.io/status-code/">https://ned14.github.io/status-code/</a>, the reference implementation library
|
|
for proposed <code>std::error</code>. Outcome emulates move bitcopying semantics for types
|
|
declaring themselves move bitcopying via the trait <a href="./reference/traits/is_move_bitcopying.html" class="api-reference"><code>is_move_bitcopying<T></code></a>
|
|
,
|
|
and status codes opt into this. This greatly improves codegen to be no worse
|
|
than with <code>std::error_code</code> (a trivially copyable type), as <a href="https://godbolt.org/z/GEdEGc">https://godbolt.org/z/GEdEGc</a>
|
|
demonstrates, despite that proposed <code>std::error</code> is a move-only type with
|
|
a non-trivial destructor.</p>
|
|
|
|
<p>Outcome binds <code>status_code</code> into <code>basic_result</code> and <code>basic_outcome</code> customisations
|
|
via the following headers:</p>
|
|
|
|
<ul>
|
|
<li><code><boost/outcome/experimental/status_result.hpp></code></li>
|
|
<li><code><boost/outcome/experimental/status_outcome.hpp></code></li>
|
|
</ul>
|
|
|
|
<p>These headers import the entire contents of the <code>BOOST_OUTCOME_SYSTEM_ERROR2_NAMESPACE</code>
|
|
namespace into the <code>BOOST_OUTCOME_V2_NAMESPACE::experimental</code> namespace. You
|
|
can thus address everything in <code>BOOST_OUTCOME_SYSTEM_ERROR2_NAMESPACE</code> via
|
|
<code>BOOST_OUTCOME_V2_NAMESPACE::experimental</code>.</p>
|
|
|
|
<p>As P1095 also proposes C language support for lightweight C++ exceptions,
|
|
experimental Outcome also has a macro-based C interface that enables C
|
|
code to work with the C-compatible subset of <code>status_result<T, E></code>:</p>
|
|
|
|
<ul>
|
|
<li><code><boost/outcome/experimental/result.h></code></li>
|
|
</ul>
|
|
|
|
<p>For non-Windows non-POSIX platforms such as some embedded systems, standalone
|
|
Experimental Outcome can be used with the <code>BOOST_OUTCOME_SYSTEM_ERROR2_NOT_POSIX</code> macro
|
|
defined. This does not include POSIX headers, and makes available a high fidelity,
|
|
fully deterministic, alternative to C++ exceptions on such platforms.</p>
|
|
|
|
<p>Finally, there is a single include edition of Experimental Outcome, which
|
|
can be found at <a href="https://github.com/ned14/outcome/blob/develop/single-header/outcome-experimental.hpp">https://github.com/ned14/outcome/blob/develop/single-header/outcome-experimental.hpp</a>.
|
|
You can play with this on godbolt by <code>#include <outcome-experimental.hpp></code>.</p>
|
|
|
|
<div class="notices warning" style="background: url('images/warning.png') top left no-repeat padding-box padding-box;">
|
|
<div class="notices heading">warning</div>
|
|
<div class="notices message"><p><b>It is stressed, in the strongest possible terms, that any item inside
|
|
<code><boost/outcome/experimental></code> is subject to unannounced breaking change based
|
|
on WG21 standards committee feedback</b>. That said, the chances are high
|
|
that most of those breaking changes will be to naming rather than to
|
|
fundamental semantics, so you can upgrade with a bit of find and replace.</p>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
|
|
|
|
</div><p><small>Last revised: December 17, 2020 at 11:27:06 UTC</small></p>
|
|
<hr>
|
|
<div class="spirit-nav">
|
|
<a accesskey="p" href="./recipes/foreign-try.html"><img src="./images/prev.png" alt="Prev"></a>
|
|
<a accesskey="u" href="./index.html"><img src="./images/up.png" alt="Up"></a>
|
|
<a accesskey="h" href="./index.html"><img src="./images/home.png" alt="Home"></a><a accesskey="n" href="./experimental/advantages.html"><img src="./images/next.png" alt="Next"></a></div></body>
|
|
</html>
|