• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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>History - 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="./changelog.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="./requirements.html"><img src="./images/next.png" alt="Next"></a></div><div id="content">
13
14  <div class="titlepage"><div><div><h1 style="clear: both">History</h1></div></div></div>
15  <div class="toc"><dl class="toc">
16<dt>
17<dd><dl>
18<dt><a href="#the-genesis-of-outcome-v1">The genesis of Outcome v1</a></dt>
19<dt><a href="#outcome-v2">Outcome v2</a></dt>
20<dt><a href="#outcome-v2-1">Outcome v2.1</a></dt>
21</dl></dd></dt>
22</dl>
23  </div>
24
25
26<p>Outcome has had an interesting history, and it is worth summarising it here to show how a
27Boost library comes to life. The following recollections are by Niall Douglas, and may be
28faulty due to his aging memory.</p>
29
30
31<center><img src="./history/graph.png"></center>
32
33<h2 id="the-genesis-of-outcome-v1">The genesis of Outcome v1</h2>
34
35<p>The git repo began life as a &ldquo;Boost.Spinlock&rdquo; in June 2014 hived out of Boost.AFIO v1 where it had existed
36for some time as an internal library. In October 2014 I added in the original prototype
37Boost.Expected reference library as a git submodule, and began developing a non-allocating
38<code>future&lt;T&gt;</code>/<code>promise&lt;T&gt;</code> as an extension of <code>expected&lt;T, std::exception_ptr&gt;</code> as a faster,
39monadic future-promise was something which AFIO v1 sorely needed.</p>
40
41<p>The original prototype Boost.Expected library was a large and very complex beastie.
42I was fortunate to be employed on a contract in late 2014 early 2015 where I saw it deployed at
43scale into an existing large C++ codebase. Expected was really great and powerful, but it absolutely
44murdered compile times in a large C++ codebase, and made LTO effectively infeasible.
45I also found its implementation non-conducive to implementing
46future-promise with it, and so I resolved to implement a much more powerful policy driven
47monad factory which could stamp out everything from an <code>option&lt;T&gt;</code> right through to a
48future-promise pair, all using the exact same <code>basic_monad&lt;&gt;</code> and therefore all with a full
49monadic programming API, C++ 17 continuations/monadic bind and intelligently convertible into one another.
50Moreover, all this needed to have an absolute minimum impact on compile times and runtime
51overheads, neither of which were strengths of the original prototype Boost.Expected library.</p>
52
53<p>By August 2015 &ldquo;Boost.Monad&rdquo; was delivering on all those requirements and then some, but it lacked
54maturity through use in other code. Summer 2015 saw the Boost peer review of AFIO v1 which
55was roundly rejected. After considering the ample review feedback, it was realised that
56<a href="https://ned14.github.io/llfio/">AFIO v2</a> would be a very different design, one no longer using futures, memory allocation
57nor C++ exceptions. As AFIO v2 was started from scratch and using Outcome heavily from the
58very beginning (every AFIO v2 API returns a <code>result&lt;T&gt;</code>), Outcome began to gain bug fixes and
59shed features, with the non-allocating future-promise implementation being dropped in May
602016 and a large chunk of type based metaprogramming being replaced with cleaner variable template metaprogramming
61in June. After CppCon 2016 in September, then began the long process of getting Outcome
62ready for Boost peer review in Q1 2017 which involved a repeated sequence of complete rewrites
63of the tutorial in response to multiple rounds of feedback from the C++ community, with
64at least four complete rewrites currently at the time of writing.</p>
65
66<p>In parallel to all this development on Outcome, Expected went before the LEWG and entered
67the C++ standards track. As the WG21 meetings went by, Expected experienced a period
68of being stripped back and much of the complexity which had so murdered compile and
69link times in 2014-2015 fell away, thus the Expected proposed in P0323R1 ended up landing
70so close to Outcome that in January 2017 it was just a few hours work to implement
71Expected using the core <code>basic_monad</code> infrastructure in Outcome. That highly flexible
72policy based design which made monadic future-promise possible made it similarly easy
73to implement a highly conforming Expected, indeed in early 2017 Outcome&rsquo;s Expected was much
74closer to <a href="http://wg21.link/P0323">P0323R1</a> than any other implementation including the LEWG reference implementation.
75And unlike the LEWG reference implementation, Outcome has had eighteen months of that
76finely tuned patina you only get when a library is in use by other code bases.</p>
77
78<p>In February 2017 it became realised that the userbase really wanted a high quality <code>expected&lt;T, E&gt;</code>
79implementation rather than anything similar but not the same which Outcome had invented.
80The only just implemented Expected implementation based on <code>basic_monad</code> therefore took
81primacy. The final rewrite of the documentation before peer review submission was one
82which made it look like Outcome was primarily an <code>expected&lt;T, E&gt;</code> implementation with a
83few useful extensions like <code>outcome&lt;T&gt;</code> and <code>result&lt;T&gt;</code>. I was sad to so pivot, but it
84was obvious that Outcome would see far wider popularity and usage as primarily an Expected
85implementation.</p>
86
87<p>Almost three years after its beginning, Outcome v1 finally went before Boost peer review
88in May 2017 which turned into one of the longest and most detailed peer reviews Boost has
89done in recent years, with over 800 pieces of review feedback submitted. It was by consensus
90rejected, <a href="https://lists.boost.org/boost-announce/2017/06/0510.php">with substantial feedback on what to do instead</a>.</p>
91
92<h2 id="outcome-v2">Outcome v2</h2>
93
94<p>During the very lengthy peer review, roughly three groups of opinion emerged as to what
95a <code>value|error</code> transporting class ought to look like:</p>
96
97<dl>
98<dt><b>1. Lightweight</b></dt>
99<dd>A simple-as-possible <code>T</code> and/or <code>E</code> transport without any
100implementation complexity.</dd>
101<dt><b>2. Medium</b></dt>
102<dd>A variant stored <code>T</code> or <code>E1</code> ... <code>E<i>n</i></code>
103where <code>T</code> is the expected value and <code>E1 ...</code>
104are the potential unexpected values. This implemention really ought to be implemented
105using C++ 17's <code>std::variant<...></code> except with stronger never-empty guarantees.
106</dd>
107<dt><b>3. Heavy</b></dt>
108<dd>A full fat Either monad participating fully in a wider monadic programming framework for C++.</dd>
109</dl>
110
111<p>Peter Dimov was very quickly able to implement an <code>expected&lt;T, E1, ...&gt;</code> using his
112<a href="https://github.com/pdimov/variant2">variant2</a> library, and thus there seemed little
113point in replicating his work in an Outcome v2. The lightweight choice seemed to be the
114best path forwards, so in June 2017 the bare minimum <code>result&lt;T, E&gt;</code> and <code>outcome&lt;T, EC, P&gt;</code>
115as presented in this library was built, using the same constructor design as <code>std::variant&lt;...&gt;</code>.
116Significant backwards compatibility with v1 Outcome code was retained, as the review
117had felt the basic proposed design fine.</p>
118
119<p>A period of maturation then followed by porting a large existing codebase using Outcome v1
120to v2, and writing a significant amount of new code using v2 to test it for unanticipated
121surprises and bugs. Quite a few corner cases were found and fixed. At the end of September
1222017, Outcome v2 was deemed to be &ldquo;mature&rdquo;, and a script generated &ldquo;Boost edition&rdquo; made
123available.</p>
124
125<p>All that remained before it was ready for a second Boost peer review was the
126documentation. This took four months to write (same time as to write the library itself!),
127and in January 2018 Outcome had its second Boost peer review, which it passed!</p>
128
129<h2 id="outcome-v2-1">Outcome v2.1</h2>
130
131<p>The changes requsted during the review of v2.0 were fairly modest: <code>result</code> and <code>outcome</code> would
132be renamed to <code>basic_result</code> and <code>basic_outcome</code>, and a clean separation of concerns between the
133<code>basic_*</code> layer and the &ldquo;convenience&rdquo; layer would be created. That suited Outcome nicely,
134as the <code>basic_*</code> layer could have minimum possible header dependencies and thus minimum possible build times
135impact, which was great for big iron users with multi-million line C++ codebases. This also
136had the nice side effect of permitting both Boost and <code>std</code> implementations to be supported
137concurrently in both Outcome and Boost.Outcome.</p>
138
139<p>By April 2018, v2.1 was feature complete and entered a six month period of maturation and
140battle hardening under its already extensive userbase. However Outcome passing its review in January 2018 had much more consequence than I could have ever
141expected. Unbeknownst to me, some of the WG21 leadership had interpreted the success of
142Outcome, and especially its divergences from WG21 Expected into a more complete substitute
143for C++ exception handling, as a sign that the C++
144exception handling mechanism was no longer fit for purpose. <a href="http://wg21.link/P0709">It was thus proposed
145to remedy the standard exception handling mechanism into something much more
146efficient, thus rendering Outcome obsolete in future C++ standards (P0709 <em>Zero overhead exceptions</em> aka &ldquo;Herbceptions&rdquo;)</a>.</p>
147
148<p>Concurrently to that, just before the review of Outcome 2.0, I had mooted a number of semantic and compile time performance
149improvements to <code>&lt;system_error&gt;</code> with the proposal that we mildly break Boost.System with
150improvements and see how badly real world code broke in response. This was not widely
151accepted at that time (though they have been since incorporated into Boost.System, and proposed
152defect remedies for <code>&lt;system_error&gt;</code> for C++ 23). I therefore wrote <a href="https://ned14.github.io/status-code/">an improved <code>&lt;system_error2&gt;</code></a> which fixed all the problems
153listed at <a href="https://wg21.link/P0824">P0824 (Summary of SG14 discussion on <code>&lt;system_error&gt;</code>)</a>
154and fixed up Outcome so one could use it without any system error implementation,
155or with the STL one or with the proposed improved one.</p>
156
157<p>This proposed improved <code>&lt;system_error2&gt;</code> was proposed by me as the library support for
158P0709 <em>Zero overhead exceptions</em> in <a href="https://wg21.link/P1095">P1095 <em>Zero overhead deterministic failure</em></a>,
159specifically as the implementation of P0709&rsquo;s proposed <code>std::error</code> value type. As
160proposed improved <code>&lt;system_error2&gt;</code> is bundled with Outcome in
161<a href="./experimental.html">experimental</a>, that means that Outcome and Boost
162users can gain the non-language benefits of one possible implementation of P0709
163today in any conforming C++ 14 compiler.</p>
164
165<p>At the time of writing, just before Outcome enters Boost (January 2019), Herbceptions have
166been voted upon only by SG14 Low Latency and LEWG, both giving unanimous acclamation. They have yet to be voted upon by the
167rest of the committee. The P1095 proposed implementation of P0709 has been voted upon by
168WG14 <em>C Programming Language</em>, where the C-relevant parts were approved in principle by a large majority. So
169the future currently looks hopeful that C, and C++, will gain language support for
170specifying deterministic failure sometime in the 2020s.</p>
171
172<p>In the meantime, Outcome is a peer reviewed, battle tested, library-only implementation
173of <em>Zero overhead exceptions</em> with proposed <code>std::error</code> available under Experimental.
174Please strongly consider helping us test the proposed <code>&lt;system_error2&gt;</code> based <code>std::error</code>
175design! The committee would greatly welcome empirical experience.</p>
176
177
178
179        </div><p><small>Last revised: February 11, 2019 at 17:43:30 UTC</small></p>
180<hr>
181<div class="spirit-nav">
182<a accesskey="p" href="./changelog.html"><img src="./images/prev.png" alt="Prev"></a>
183    <a accesskey="u" href="./index.html"><img src="./images/up.png" alt="Up"></a>
184    <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>
185</html>
186