Skip to content

Commit

Permalink
CI regenerates Boost.Outcome docs
Browse files Browse the repository at this point in the history
  • Loading branch information
Jenkins nedprod CI committed Oct 17, 2024
1 parent bf938c2 commit 4e0def6
Show file tree
Hide file tree
Showing 549 changed files with 29,657 additions and 0 deletions.
21 changes: 21 additions & 0 deletions doc/html/_footer.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
<!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> - 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="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="./requirements.html"><img src="./images/next.png" alt="Next"></a></div><div id="content">
<div class="titlepage"><div><div><h1 style="clear: both"></h1></div></div></div>


</div><p><small>Last revised: January 01, 0001 at 00:00:00 UTC</small></p>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="./history.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="./requirements.html"><img src="./images/next.png" alt="Next"></a></div></body>
</html>
22 changes: 22 additions & 0 deletions doc/html/_header.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
<!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> - 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="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="./requirements.html"><img src="./images/next.png" alt="Next"></a></div><div id="content">
<div class="titlepage"><div><div><h1 style="clear: both"></h1></div></div></div>
<p>Outcome 2.2 library documentation</p>


</div><p><small>Last revised: January 01, 0001 at 00:00:00 UTC</small></p>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="./history.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="./requirements.html"><img src="./images/next.png" alt="Next"></a></div></body>
</html>
95 changes: 95 additions & 0 deletions doc/html/abi-stability.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
<!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>Future ABI stability guarantees - 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="./motivation/narrow_contract.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="./tutorial.html"><img src="./images/next.png" alt="Next"></a></div><div id="content">

<div class="titlepage"><div><div><h1 style="clear: both">Future ABI stability guarantees</h1></div></div></div>


<p>At the end of December 2021, <a href="./history.html">as had been intended and signposted from the beginning of development</a>, standalone Outcome v2.2.3 locked its ABI such that any code built with this Outcome release shall link, without recompilation, with any code built with any future Outcome release. This means that going forth, you are guaranteed that if your library returns an <code>outcome::</code><a href="./reference/aliases/result.html" class="api-reference"><code>result&lt;T, E = varies, NoValuePolicy = policy::default_policy&lt;T, E, void&gt;&gt;</code></a>
or <code>outcome::</code><a href="./reference/aliases/outcome.html" class="api-reference"><code>outcome&lt;T, EC = varies, EP = varies, NoValuePolicy = policy::default_policy&lt;T, EC, EP&gt;&gt;</code></a>
from a public API, consumers of your library are guaranteed 100% compatibility with unrecompiled library binaries when using any future version of Outcome in consuming code.</p>

<p>This is a critical use case for many large scale production use cases in industry, and to my knowledge, no other Outcome-like alternative implements this guarantee at the time of writing<sup class="footnote-ref" id="fnref:1"><a href="#fn:1">1</a></sup>. Note also that Boost.Outcome comes with no ABI guarantees, as the dependencies within Boost that Boost.Outcome uses do not have a stable ABI guarantee.</p>

<p>To ensure this guarantee going forth, a per commit CI step has been added which tests Outcome against the v2.2.3 ABI using these tools:</p>

<ul>
<li><a href="https://lvc.github.io/abi-compliance-checker/">The ABI compliance checker</a> (using its <code>abi-dumper</code> mode, not its translation unit parsing mode which is too brittle).</li>
<li><a href="https://sourceware.org/libabigail/manual/libabigail-tools.html">Sourceware&rsquo;s libabigail tooling</a>.</li>
</ul>

<p>Both tools are independent of one another, and whilst they test using the same mechanism (DWARF debug info extracted from an unoptimised shared library object), they have different implementations.</p>

<h4 id="abi-testing-implementation-notes">ABI testing implementation notes</h4>

<p>Outcome is a header only library, so to turn Outcome into a shared library suitable as input for these tools, we compile a dummy shared library which exports APIs which use Outcome. The coverage of that dummy shared library of Outcome is therefore what is actually ABI tested, rather than of Outcome itself. The dummy library locks the ABI for:</p>

<ul>
<li><code>basic_result&lt;trivial type, std::error_code, all policies&gt;</code> (i.e. union storage layout)</li>
<li><code>basic_outcome&lt;trivial type, std::error_code, trivial type, all policies&gt;</code></li>
<li><code>basic_result&lt;non-trivial type, std::error_code, all policies&gt;</code> (i.e. struct storage layout)</li>
<li><code>basic_outcome&lt;non-trivial type, std::error_code, std::exception_ptr, all policies&gt;</code></li>
<li><code>bad_result_access_with&lt;std::error_code&gt;</code></li>
<li><code>bad_outcome_access</code></li>
<li><code>atomic_eager&lt;int&gt;</code></li>
<li><code>atomic_eager&lt;basic_result&lt;trivial type, std::error_code, all policies&gt;&gt;</code></li>
<li><code>atomic_eager&lt;basic_result&lt;non-trivial type, std::error_code, all policies&gt;&gt;</code></li>
<li><code>atomic_lazy&lt;int&gt;</code></li>
<li><code>atomic_lazy&lt;basic_result&lt;trivial type, std::error_code, all policies&gt;&gt;</code></li>
<li><code>atomic_lazy&lt;basic_result&lt;non-trivial type, std::error_code, all policies&gt;&gt;</code></li>
<li><code>eager&lt;int&gt;</code></li>
<li><code>eager&lt;basic_result&lt;trivial type, std::error_code, all policies&gt;&gt;</code></li>
<li><code>eager&lt;basic_result&lt;non-trivial type, std::error_code, all policies&gt;&gt;</code></li>
<li><code>lazy&lt;int&gt;</code></li>
<li><code>lazy&lt;basic_result&lt;trivial type, std::error_code, all policies&gt;&gt;</code></li>
<li><code>lazy&lt;basic_result&lt;non-trivial type, std::error_code, all policies&gt;&gt;</code></li>
</ul>

<p>Obviously anything which any of these types touch in their implementation also gets locked in ABI, in so far as the ABI tool can deduce dependent types. If you examine the source code for the dummy shared library, you will see that we go out of our way to encode explicit lists of dependent types in template parameters, to ensure that the ABI tool definitely discovers everything.</p>

<div class="notices note" style="background: url('images/note.png') top left no-repeat padding-box padding-box;">
<div class="notices heading">note</div>
<div class="notices message"><p>Outcome.Experimental has no ABI guarantees, as WG21 LEWG is actively modifying its design as it approaches the C++ standard.</p>
</div>
</div>


<p>The following targets are tested for ABI stability:</p>

<ol>
<li><p>GCC 7.5 with libstdc++ configured with the C++ 14 standard and x64 architecture.</p></li>

<li><p>GCC 9.3 with libstdc++ configured with the C++ 17 standard and x64 architecture.</p></li>
</ol>

<p>At the time of writing, no POSIX implementation has guaranteed stability on its C++ 20 standard library ABI, so we do not test that.</p>

<p>There is currently no CI coverage of MSVC ABI stability. The ABI compliance checker can test MSVC binaries for ABI stability, however raising the ABI compliance checker on a Github Actions Windows test runner is quite a lot of work. Donations of sufficient test scripting would be welcome. Note that because the Windows and POSIX implementation is almost the same, ABI stability on POSIX will have strong impact on MSVC ABI stability i.e. MSVC ABI is unlikely to break, albeit without CI testing there are no guarantees.</p>
<div class="footnotes">

<hr />

<ol>
<li id="fn:1">libstdc++ implements a strong ABI stability guarantee and thus any future <code>std::expected&lt;T, E&gt;</code> implementation it provides will be ABI stable. However Expected offers only a small subset of the functionality which <code>outcome::result&lt;T, E&gt;</code> provides.
<a class="footnote-return" href="#fnref:1"><sup>[return]</sup></a></li>
</ol>
</div>



</div><p><small>Last revised: December 15, 2021 at 11:47:12 UTC</small></p>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="./motivation/narrow_contract.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="./tutorial.html"><img src="./images/next.png" alt="Next"></a></div></body>
</html>
45 changes: 45 additions & 0 deletions doc/html/alternatives.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
<!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>Review of Error Handling Frameworks - 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="./build.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="./alternatives/exceptions.html"><img src="./images/next.png" alt="Next"></a></div><div id="content">

<div class="titlepage"><div><div><h1 style="clear: both">Review of Error Handling Frameworks</h1></div></div></div>
<p>Outcome <a href="./history.html">started life in 2014</a>, entered Boost as Boost.Outcome in 2018, and therefore was amongst the very first of the major alternative error handling frameworks to standard exception throws in C++. Since then, and sometimes in reaction to Outcome&rsquo;s choice of design, alternative frameworks have appeared. This page tries to give a fairly even handed summary of those alternatives, and how they compare to Outcome in this author&rsquo;s opinion.</p>

<p>These are listed in order of approximate availability to the C++ ecosystem i.e. in order of appearance.</p>

<ol class="children children-li"><li>
<a href="./alternatives/exceptions.html" >std exception throws</a>
<p>Advantages and disadvantages of C++ exception throws</p><li>
<a href="./alternatives/error_code.html" >std error codes</a>
<p>Advantages and disadvantages of <code>std::error_code</code></p><li>
<a href="./alternatives/expected.html" >std expected</a>
<p>Advantages and disadvantages of <code>std::expected&lt;T, E&gt;</code></p><li>
<a href="./alternatives/outcome.html" >Outcome (proposed std result)</a>
<p>Advantages and disadvantages of Outcome and its proposed <code>std::result&lt;T&gt;</code></p><li>
<a href="./alternatives/leaf.html" >LEAF</a>
<p>Advantages and disadvantages of Lightweight Error Augmentation Framework</p></li></ol>

<p>My thanks to Emil Dotchevski for reviewing this summary and providing notes.</p>







</div><p><small>Last revised: January 10, 2022 at 14:29:13 UTC</small></p>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="./build.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="./alternatives/exceptions.html"><img src="./images/next.png" alt="Next"></a></div></body>
</html>
63 changes: 63 additions & 0 deletions doc/html/alternatives/error_code.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
<!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>std error codes - 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="../alternatives/exceptions.html"><img src="../images/prev.png" alt="Prev"></a>
<a accesskey="u" href="../alternatives.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="../alternatives/expected.html"><img src="../images/next.png" alt="Next"></a></div><div id="content">
<div class="titlepage"><div><div><h1 style="clear: both">std error codes</h1></div></div></div>


<p><code>std::error_code</code> came originally from <code>boost::error_code</code> which was designed around 2008 as part of implementing Filesystem and Networking. They are a simple trivially copyable type offering improved type safety and functionality over C enumerations. <a href="../motivation/std_error_code.html">You can read more about how <code>std::error_code</code> works here</a>. They were standardised in the C++ 11 standard, and have been available in Boost since 2008.</p>

<h4 id="pros">Pros:</h4>

<ul>
<li><p>Predictable runtime overhead on the happy path.</p></li>

<li><p>Predictable runtime overhead on the sad path.</p></li>

<li><p>Unbiased syntax equal for both success and failure requiring explicit code written to handle both.</p></li>

<li><p>Very little codegen bloat added to binaries (though there is a fixed absolute overhead for support libraries).</p></li>

<li><p>Once constructed, passing around <code>std::error_code</code> instances optimises well, often being passed in CPU registers.</p></li>

<li><p>Works well in all configurations of C++, including C++ exceptions and RTTI globally disabled.</p></li>

<li><p>Works well on all niche architectures, such as HPC, GPUs, DSPs and microcontrollers.</p></li>

<li><p>Ships with every standard library since C++ 11.</p></li>
</ul>

<h4 id="cons">Cons:</h4>

<ul>
<li><p>Failure to write handling code for failure means failures get silently dropped. This is disturbingly easy to do.</p></li>

<li><p>Results in branchy code, which is slow &ndash; though predictably so &ndash; for embedded controller CPUs.</p></li>

<li><p>Because the <code>std::error_category</code> instance used in construction comes from a magic static, the compiler inserts an atomic operation around every <code>std::error_code</code> construction (e.g. <a href="https://godbolt.org/z/oGaf4qe8a">https://godbolt.org/z/oGaf4qe8a</a>). This can impact optimisation on compilers with poor optimisation of atomics.</p></li>

<li><p>The payload of type <code>int</code> is incredibly constraining sometimes, especially on 64-bit platforms. It would have been much better if it were <code>intptr_t</code> instead of <code>int</code>.</p></li>

<li><p>The payload value of all bits zero has silent hard coded semantics which is incompatible with many C enumerations, which start from value zero. This can cause silent dropping of failures in a very hard to debug way.</p></li>

<li><p>How comparisons between disparate code categories (i.e. mapping) is supposed to work is non-obvious, and even standard library maintainers and many members of WG21 have been confused by it in the past.</p></li>
</ul>

<p>(Note that this long list of design caveats is what led to the proposed superseding of <code>std::error_code</code> with <code>std::error</code>, which you can use today in Outcome.Experimental. See <a href="../experimental.html">this page for more information</a>).</p>


</div><p><small>Last revised: January 10, 2022 at 14:29:13 UTC</small></p>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../alternatives/exceptions.html"><img src="../images/prev.png" alt="Prev"></a>
<a accesskey="u" href="../alternatives.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="../alternatives/expected.html"><img src="../images/next.png" alt="Next"></a></div></body>
</html>
Loading

0 comments on commit 4e0def6

Please sign in to comment.