Otherwise, simply download the raw file from above and place it wherever it suits you.
+If you might be debugging using Microsoft Visual Studio, you may find the debugger
+visualisation file at https://github.com/ned14/outcome/raw/master/include/outcome/outcome.natvis
+useful to include into your build.
+
+
Usage from the Conan package manager
+
+
(thanks to Théo Delrieu for contributing this support)
+
+
At the command line, add the bintray repo for Outcome to conan:
Outcome will be made available by Conan at <outcome.hpp>.
+
+
Usage as a git submodule
+
+
If you are very keen on tracking very latest Outcome, you can add it as a git
+submodule to your project so you can keep abreast of bug fixes. Here is how:
After this you can bring Outcome into your code using:
+
+
#include "outcome/include/outcome.hpp"
+
+
+
That’s it, you are ready to go. From time to time, you may wish to update to
+latest:
+
+
cd outcome
+git pull
+git submodule update
+
+
+
Usage as a stable source tarball
+
+
If you would prefer a single source tarball of the stable branch containing
+all the documentation, tests and sources, this can always be retrieved from:
This tarball is automatically generated when Outcome fully compiles and passes
+all unit tests on all platforms tested by the CIs. This currently includes:
+
+
+
Linux: GCC 6.5, clang 4.0.1
+
MacOS: XCode 9
+
Windows: VS2017.9
+
+
+
It should be emphasised that newer compilers are not tested, so there is
+an unlikely chance that the tarball may not work on a newer compiler.
+
+
+
+
Running the unit test suite
+
+
To run the unit test suite you will need cmake 3.1 or later installed.
On some cmake generators (Visual Studio, Xcode) you may need to tell cmake build a configuration
+like Release or Debug. Similarly, ctest needs to be told the same e.g.
If you are using Outcome in a CMake project, Outcome is a “modular cmake” project
+using only modern cmake 3 throughout. This lets you add the Outcome directory as a
+cmake subdirectory with no unexpected consequence on the rest of your cmake. You will need
+to be using cmake 3.1 or better.
+
+
add_subdirectory(
+ "${CMAKE_CURRENT_SOURCE_DIR}/outcome" # path to outcome source
+ "${CMAKE_CURRENT_BINARY_DIR}/outcome" # your choice of where to put binaries
+ EXCLUDE_FROM_ALL # please only lazy build outcome on demand
+)
+
+
+
Outcome’s cmake has the following useful products:
+
+
+
outcome::hl (target): the Outcome header-only library. Add this to any
+target_link_libraries() in your cmake to bring in Outcome as a header-only library. This will also
+add to your link (via PUBLIC) any debugger visualisation support files, any system library
+dependencies and also force all consuming executables to be configured with a minimum
+of C++ 14 as Outcome requires a minimum of that.
+
outcome_TEST_TARGETS (list): a list of targets which generate Outcome’s test
+suite. You can append this to your own test suite if you wish to run Outcome’s test
+suite along with your own.
Standalone outcome is now make install-able, and cmake find_package() can find it.
+Note that you must separately install and find_package() Outcome’s dependency, quickcpplib,
+else find_package() of Outcome will fail.
+
Breaking change!
+
The git submodule mechanism used by standalone Outcome of specifying dependent libraries
+has been replaced with a cmake superbuild of dependencies mechanism instead. Upon cmake
+configure, an internal copy of quickcpplib will be git cloned, built and installed into the
+build directory from where an internal find_package() uses it. This breaks the use of
+the unconfigured Outcome repo as an implementation of Outcome, one must now do one of:
+
+
+
Add Outcome as subdirectory to cmake build
+
Use cmake superbuild (i.e. ExternalProject_Add()) to build and install Outcome into
+a local installation.
+
Use one of the single header editions.
+
+
Breaking change!
+
For standalone Outcome, the current compiler is now checked for whether it will compile
+code containing C++ Concepts, and if it does, all cmake consumers of Outcome will enable
+C++ Concepts. Set the cmake variable BOOST_OUTCOME_C_CONCEPTS_FLAGS to an empty string to prevent
+auto detection and enabling of C++ Concepts support occurring.
+
BOOST_OUTCOME_TRY operation now hints to the compiler that operation will be successful
+
P1886 Error speed benchmarking showed that there is
+considerable gain in very small functions by hinting to the compiler whether the expression
+is expected to be successful or not. BOOST_OUTCOME_TRY previously did not hint to the compiler
+at all, but now it does. A new suite of macros BOOST_OUTCOME_TRY_FAILURE_LIKELY hint to the
+compiler that failure is expected. If you wish to return to the previously unhinted
+behaviour, define BOOST_OUTCOME_TRY_LIKELY(expr) to (!!expr).
Support for C++ Coroutines has been added. This comes in two parts, firstly there is
+now an BOOST_OUTCOME_CO_TRY() operation suitable for performing the TRY operation from
+within a C++ Coroutine. Secondly, in the header outcome/coroutine_support.hpp there are
+implementations of eager<OutcomeType> and lazy<OutcomeType> which let you more
+naturally and efficiently use basic_result or basic_outcome from within C++
+Coroutines – specifically, if the result or outcome will construct from an exception
+pointer, exceptions thrown in the coroutine return an errored or excepted result with
+the thrown exception instead of throwing the exception through the coroutine machinery
+(which in current compilers, has a high likelihood of blowing up the program). Both
+eager<T> and lazy<T> can accept any T as well. Both have been tested and found
+working on VS2019 and clang 9.
make_error_code() and make_exception_ptr() are now additionally considered for
+compatible copy and move conversions for basic_result<>. This lets you construct
+a basic_result<T, E> into a basic_result<T, error_code>, where E is a
+custom type which has implemented the ADL discovered free function
+error_code make_error_code(E), but is otherwise unrelated to error_code.
+The same availability applies for exception_ptr with make_exception_ptr() being
+the ADL discovered free function. basic_outcome<> has less support for this than
+basic_result<> in order to keep constructor count down, but it will accept via
+this mechanism conversions from basic_result<> and failure_type<>.
As per request from Boost release managers, relocated version.hpp and
+revision.hpp into detail, and added the Boost licence boilerplate to the top
+of every source file which was missing one (I think). Also took the opportunity
+to run the licence restamping script over all Outcome, so copyright dates are now
+up to date.
Refactored the BOOST_OUTCOME_TRY implementation to use more clarified
+customisation points capable of accepting very foreign inputs. Removed the
+std::experimental::expected<T, E> specialisations, as those are no longer
+necessary. Fixed the documentation for the customisation points which
+previously claimed that they are ADL discovered, which they are not. Added
+a recipe describing how to add in support for foreign input types.
Fix issue #182 where trait::is_exception_ptr_available<T> was always true,
+thus causing much weirdness, like not printing diagnostics and trying to feed
+everything to make_exception_ptr().
Fix issue #192 where the std::basic_outcome_failure_exception_from_error()
+was being defined twice for translation units which combine standalone and
+Boost Outcome’s.
success() and failure() now produce types marked [[nodiscard]].
+
+
+
include/outcome/outcome.natvis is now namespace permuted like the rest of
+Outcome, so debugging Outcome based code in Visual Studio should look much
+prettier than before.
BREAKING CHANGEresult<T, E>, boost_result<T, E> and std_result<T, E>
+no longer implement hard UB on fetching a value from a valueless instance if E is
+a UDT, they now fail to compile with a useful error message. If you wish hard UB,
+use unchecked<T, E>, boost_unchecked<T, E> or std_unchecked<T, E> instead.
Fixed a nasty corner case bug where value type’s without a copy constructor
+but with a move constructor would indicate via traits that copy construction
+was available. Thanks to Microsoft’s compiler team for reporting this issue.
+
+
+
Added experimental status_result and status_outcome based on experimental
+status_code.
+
+
Boost edition is now 100% Boost, so defaults for result and outcome are
+boost::system::error_code::errc_t and boost::exception_ptr. Moreover,
+the test suite in the Boost edition now exclusively tests the Boost edition.
+One can, of course, freely use the standalone edition with Boost, and the Boost
+edition with std types.
+
+
Renamed ADL discovered customisation point throw_as_system_error_with_payload()
+to outcome_throw_as_system_error_with_payload().
Added much clearer compile failure when user tries result<T, T> or outcome
+where two or more types are identical. Thanks to Andrzej Krzemieński
+for suggesting a technique which combines SFINAE correctness with
+the remaining ability for result<T, T> etc to be a valid type, but
+not constructible.
Outcome did not construct correctly from failure_type.
+
+
+
Inexplicably outcome’s error + exception constructor had been removed.
+Nobody noticed during the Boost peer review, which is worrying seeing as that
+constructor is needed for one of the main advertised features to Boost!
swap() now has correct noexcept calculation and now correctly orders
+the swaps to be whichever is the throwing swap first.
+
+
+
Added reference dump of v2.1 ABI so we can check if ABI breakage detection
+works in the next set of changes, plus Travis job to check ABI and API compatibility
+per commit.
Standardese - the API reference generator (up until Outcome v2.0)
+
+
+
Special thanks for Outcome v2.1
+
+
Once again Andrzej Krzemienski stands out for a never ceasing flow of excellent questions,
+“what if?”’s, eagle eyed spotting of corner case logic bugs, and design contradictions.
+Thank you Andrzej!
+
+
My thanks to the Microsoft Visual C++ compiler team for incorporating Outcome into the
+MSVC test suite, and thus finding many interesting corner case quirks in how best to
+interpret the C++ standard. In some cases, Outcome was refactored to be less ambiguous;
+in others, defects had to be submitted to WG21 because the standard wording was not clear.
+The Visual C++ compiler team were particularly generous with their time in helping track
+down the cause of these issues, complete with submitting pull requests with bug fixes.
+I am very grateful to them.
+
+
Special thanks for Outcome v2.0
+
+
For a second time, Charley Bay stepped up as review manager. Given how much work it was
+for the v1 review, I can only say thank you.
+
+
Andrzej Krzemienski went far beyond the call of duty in the development of Outcome v2.
+He wrote the front page, and the start of the tutorial. He thus set the tone, pacing,
+style and form of the tutorial which I merely continued for the rest of the tutorial.
+He also volunteered considerable amounts of his time as as primary peer reviewer for
+the v2 design and implementation, asking many very valuable “stupid questions” at least
+one of which caused a major rethink and refactor. If Outcome v2 passes its second peer
+review, it’s because of Andrzej. Thank you.
+
+
Jonathan Müller invested countless hours in his doxygen replacement tool Standardese
+which Outcome uses to generate the reference API docs, and a not insignificant number
+of those went on fixing issues for Outcome. Thank you.
+
+
Special thanks for Outcome v1
+
+
To Paul Bristow who
+proposed the name “Outcome” for the library after a very extended
+period of name bikeshedding on boost-dev. I had been minded to call the library “Boost.Donkey”
+just to shut everyone up because the name bike shedding was getting ridiculous. But
+Outcome is a lot nicer, so thank you Paul.
+
+
My heartfelt thanks to Charley Bay for acting as review manager for Outcome in May 2017.
+It is becoming ever harder to find a Boost review manager, so thank you! My thanks also
+to the CppCast team Rob Irving and Jason Turner for so quickly getting me on to CppCast
+to discuss expected<T, E> during the Outcome peer review to help publicise the review.
+
+
More general thanks are due to those on boost-dev, Reddit and SG14 for extensive and often very detailed
+feedback on the library pretty much from its beginning. You are all too numerous to
+remember, but certainly Tongari and Andrzej Krzemienski come to mind as having engaged
+in particularly long discussion threads with tons of useful feedback which clarified my
+thinking. Andrzej also went through the documentation with a fine toothed comb before the
+review, finding many small errata and confusing wording.
+
+
Finally, my thanks to Vicente for driving Expected from its beginnings to hopefully
+standardisation before 2020. It’s many years of work getting something standardised, even
+more years than getting a library into Boost which as you can see from the history above
+took about three years.
It is stressed, in the strongest possible terms, that any item inside
+<boost/outcome/experimental> is subject to unannounced breaking change based
+on WG21 standards committee feedback. 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.
+There are quite a few large code bases out there
+already using this experimental support in anger, we know it works well
+at scale and it’s a good bit superior to std::error_code et al on every
+measure.
+
+
+
+
+
P1095’s support library has a reference implementation at https://ned14.github.io/status-code/.
+You will find terse documentation there, and an API reference.
+This library is wholly incorporated into Outcome in the <boost/outcome/experimental/status-code>
+directory, with bindings into Outcome provided in the following headers:
+
+
+
<boost/outcome/experimental/status_result.hpp>
+
<boost/outcome/experimental/status_outcome.hpp>
+
+
+
These headers import the entire contents of the BOOST_OUTCOME_SYSTEM_ERROR2_NAMESPACE
+namespace into the BOOST_OUTCOME_V2_NAMESPACE::experimental namespace. You
+can thus address everything in BOOST_OUTCOME_SYSTEM_ERROR2_NAMESPACE via
+BOOST_OUTCOME_V2_NAMESPACE::experimental.
+
+
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 status_result<T, E>:
The main advantages of choosing <boost/outcome/experimental> over default Outcome:
+
+
+
Codegen is tighter and less verbose1, sometimes remarkably so.
+
+
Build time impact is markedly lower, barely above the inclusion of naked
+<basic_result.hpp>, as the STL allocator machinery and std::string et al
+is not dragged into inclusion by including <system_error>. Note that
+<boost/outcome/experimental/status_outcome.hpp> bring in <exception>,
+however <boost/outcome/experimental/status_result.hpp> brings in no extra system
+headers.
+
+
More discipline is imposed on your use of Outcome, leading to
+less ambiguous code which is easier to optimise by the compiler,
+lower cost to maintain, and lower cognitive load to audit code based on
+experimental Outcome for correctness.
+
+
Code written to <boost/outcome/experimental> can be fairly easily dual
+targeted, with just a few switching type aliases, to default Outcome.
+This author has several Outcome-based libraries with identical source code which
+can target either configuration of Outcome. The experimental Outcome
+build regularly beats the default Outcome build in benchmarks by 2-3%,
+and the dual target source code, being written to tighter discipline,
+is faster and more deterministic in the default target than it was before
+the (non-trivial) port to <boost/outcome/experimental>.
+
+
+
If you are building a codebase on top of Outcome expecting long term
+maintenance, the author’s personal recommendation is that you design, write, test and
+optimise it for <boost/outcome/experimental>. What you ship to your customers
+ought to be targeted at default Outcome however, so employ type aliases and
+macros as appropriate to switch the build configuration for production releases.
+This is what the Outcome author does himself, to date with great success,
+despite the fundamental architectural differences between <system_error>
+and proposed <system_error2>.
+
+
+
+
+
+
Boost.System’s error_code has incorporated some of the design improvements of experimental status_code, and produces codegen somewhere in between experimental status_code and std::error_code.
+ [return]
+
+
+
+
+
Last revised: February 05, 2019 at 21:41:47 UTC
+
+
+
+
+
+
diff --git a/doc/html/experimental/c-api.html b/doc/html/experimental/c-api.html
new file mode 100644
index 00000000..1043486a
--- /dev/null
+++ b/doc/html/experimental/c-api.html
@@ -0,0 +1,58 @@
+
+
+Using Outcome from C code - Boost.Outcome documentation
+
+
+
+
+
+
+
+
+
+
+
Using Outcome from C code
+
A long standing problem for C code (or more usually nowadays, the many other programming
+languages which can speak the C ABI but not the C++ ABI) is how to interpret C++ exception throws. The answer
+is of course that they cannot, thus requiring one to write C shim code on the C++ side
+of things of the form:
+
// The API we wish to expose to C
+constchar*get_value(doublev);
+
+// The C shim function for the C++ get_value() function.
+extern"C"intc_get_value(constchar**ret,doublev)
+{
+ try
+ {
+ *ret=get_value(v);
+ return0;// success
+}
+ catch(conststd::range_error&)
+ {
+ returnERANGE;
+ }
+ // More catch clauses may go in here ...
+catch(...)
+ {
+ returnEAGAIN;
+ }
+}
+
+
This is sufficiently painful that most reach for a bindings generator tool like
+SWIG to automate this sort of tedious boilerplate generation.
+And this is fine for larger projects, but for smaller projects the cost of
+setting up and configuring SWIG is also non-trivial.
+
+
What would be really great is if result<T> returning noexcept C++ functions
+could be used straight from C. And indeed Experimental Outcome provides just that facility
+which this section covers next.
+
+
+
+
Last revised: February 05, 2019 at 17:14:18 UTC
+
+
+
+
+
+
diff --git a/doc/html/experimental/c-api/example.html b/doc/html/experimental/c-api/example.html
new file mode 100644
index 00000000..24ad8a9a
--- /dev/null
+++ b/doc/html/experimental/c-api/example.html
@@ -0,0 +1,70 @@
+
+
+Example C++ function - Boost.Outcome documentation
+
+
+
+
+
+
+
+
+
+
Example C++ function
+
Let us start with a simple C++ function which we wish to make available to C code:
+
+
namespaceoutcome_e=BOOST_OUTCOME_V2_NAMESPACE::experimental;
+
+// Fill the supplied buffer with the integer v converted to a string,
+// returning length of string minus null terminator
+outcome_e::status_result<size_t>to_string(char*buffer,size_tbufferlen,intv)noexcept
+{
+ try
+ {
+ // Could throw an exception!
+std::stringtemp(std::to_string(v));
+
+ // Will this string exceed the supplied buffer?
+if(temp.size()+1>bufferlen)
+ returnoutcome_e::errc::no_buffer_space;
+
+ // Copy the string into the supplied buffer, and return length of string
+memcpy(buffer,temp.data(),temp.size()+1);
+ returntemp.size();
+ }
+ catch(...)
+ {
+ // This is the <system_error2> analogue of Standard Outcome's
+// error_from_exception() utility function. It consumes an exception
+// ptr (defaulted to current exception), and tries to match it to a
+// standard C++ library exception type, returning a system_code
+// with an appropriate code domain (generic_code, posix_code,
+// win32_code).
+//
+// Note that using this function requires including
+// <boost/outcome/experimental/status-code/system_code_from_exception.hpp>
+// It is NOT included by Experimental Outcome by default.
+returnoutcome_e::system_code_from_exception();
+ }
+}
+
As the alias status_result<size_t> defaults the erased type to the alias system_code,
+the to_string() function returns (in concrete types) basic_result<size_t, status_code<erased<intptr_t>>>.
+
diff --git a/doc/html/experimental/c-api/example2.html b/doc/html/experimental/c-api/example2.html
new file mode 100644
index 00000000..fe856c2a
--- /dev/null
+++ b/doc/html/experimental/c-api/example2.html
@@ -0,0 +1,77 @@
+
+
+Calling it from C - Boost.Outcome documentation
+
+
+
+
+
+
+
+
+
+
Calling it from C
+
Firstly we need to declare to C our result returning C++ function:
+
+
// Declare our C++ function's returning result type. Only needs to be done once.
+// This declares an `status_result<size_t, system_code>` which is an alias to
+// `basic_result<size_t, status_code<erased<intptr_t>>>`.
+//
+// The first parameter is some unique identifier for this type which will be used
+// whenever we reference this type in the future.
+CXX_DECLARE_RESULT_SYSTEM(to_string_rettype,size_t);
+
+// Tell C about our extern C++ function `to_string()`
+externCXX_RESULT_SYSTEM(to_string_rettype)_Z9to_stringPcmi(char*buffer,size_tbufferlen,intv);
+
to_string(9) fills buffer with '9' of 1 characters
+to_string(99) fills buffer with '99' of 2 characters
+to_string(999) fills buffer with '999' of 3 characters
+to_string(9999) failed with error code 105 (No buffer space available)
+
C++ has excellent two-way compatibility with the C ABI, but there are some
+limitations you must observe to write C++ code which C code can call without
+marshalling at the ABI boundary:
+
+
+
A C++ function may not throw exceptions if it is safe to call from C, and
+so should always be marked noexcept.
+
+
A C++ function should be annotated with extern "C" to prevent its symbol
+being mangled, and thus give it the C rather than C++ ABI.
+
+
You cannot use overloading in your extern "C" functions.
+
+
You may only use types in your C++ function declaration for which these traits are both true:
(Note that std::is_trivially_copyable_v<T> requires trivial destruction,
+but NOT trivial construction. This means that C++ can do non-trivial construction
+of otherwise trivial types)
+
+
+
+
+
The above is what the standard officially requires for well defined C and C++ interop.
+However, all of the three major compilers MSVC, GCC and clang are considerably more relaxed.
+In those three major compilers, “almost-standard-layout” C++ types work fine in C.
+
+
“Almost-standard-layout” C++ types have these requirements:
+
+
+
No virtual functions or virtual base classes i.e.
+std::is_polymorphic_v<T>
+must be false. This is because the vptrs offset the proper front of the data layout
+in an unknowable way to C.
+
Non-static data members of reference type appear to C as pointers. You
+must never supply from C to C++ a non-null pointer which is seen as a reference in C++.
+
C++ inheritance is seen in C data layout as if the most derived class has nested
+variables of the inherited types at the top, in order of inheritance.
+
Types with non-trivial destructors work fine so long as at least move construction
+and assignment is the same as
+copying bits like memcpy(). You just need to make sure instances of the type return
+to C++, and don’t get orphaned in C. This was referred to in previous pages in this
+section as “move relocating” types.
+
+
+
Experimental Outcome’s support for being used from C does not meet the current strict
+requirements, and thus relies on the (very common) implementation defined behaviour just
+described (it is hoped that future C++ standards can relax the requirements to those
+just described).
+
+
Specifically, proposed status_code is an almost-standard-layout type,
+and thus while it can’t be returned from extern "C" functions as the compiler
+will complain, it is perfectly safe to return from C++ functions to C code on the
+three major compilers, as it is an “almost-standard-layout” C++ type if T is
+an “almost-standard-layout” C++ type.
The C macro API header <boost/outcome/experimental/result.h> consists of these macros:
+
+
+
BOOST_OUTCOME_C_DECLARE_RESULT(ident, T, E)
+
Declares to C a basic_result type uniquely
+identified by ident. T is available at the
+member variable .value, and E is available
+at the member variable .error.
+
+
BOOST_OUTCOME_C_RESULT(ident)
+
A reference to a previously declared result type with
+unique ident.
+
+
BOOST_OUTCOME_C_RESULT_HAS_VALUE(r)
+
Evaluates to 1 (true) if the input result has a value.
+
+
BOOST_OUTCOME_C_RESULT_HAS_ERROR(r)
+
Evaluates to 1 (true) if the input result has an error.
+
+
BOOST_OUTCOME_C_RESULT_ERROR_IS_ERRNO(r)
+
Evaluates to 1 (true) if the input result's error value
+is a code in the POSIX errno domain.
+
+
+
The above let you work, somewhat awkwardly, with any C-compatible
+basic_result<T, E>. basic_result<T, E> is trivially copyable and
+standard layout if its T and E are both so, and it has the C layout:
Declares to C a status code type with domain value_type
+available at the member variable .value. The ident
+must be any identifier fragment unique in this translation unit. It is
+used to uniquely identify this status code type in other macros.
+
+
BOOST_OUTCOME_C_STATUS_CODE(ident)
+
A reference to a previously declared status code type with unique
+ident.
+
+
+
There is a high likelihood that C++ functions regularly called by C
+code will return their failures either in erased system_code
+or in posix_code (i.e. errno code domain). Via querying the
+returned value using BOOST_OUTCOME_C_RESULT_ERROR_IS_ERRNO(r), one can determine
+if the returned code is in the errno code domain, and thus can be
+fed to strerror() and so on. Therefore there are
+convenience macro APIs for those particular use cases.
+
+
+
BOOST_OUTCOME_C_DECLARE_RESULT_ERRNO(ident, T)
+
Declares to C a basic_result<T, posix_code>
+type uniquely identified by ident.
+
+
BOOST_OUTCOME_C_RESULT_ERRNO(ident)
+
A reference to a previously declared basic_result<T, posix_code>
+type with unique ident.
+
+
BOOST_OUTCOME_C_DECLARE_RESULT_SYSTEM(ident, T)
+
Declares to C a basic_result<T, system_code>
+type uniquely identified by ident.
+
+
BOOST_OUTCOME_C_RESULT_SYSTEM(ident)
+
A reference to a previously declared basic_result<T, system_code>
+type with unique ident.
+
The major design differences between <system_error> and proposed <system_error2> are
+as follows:
+
+
+
experimental::status_code<DomainType> can represent warnings
+and form-of-success codes as well as failure codes. experimental::errored_status_code<DomainType>
+is more similar to std::error_code, in that it can only represent failures
+(this is enforced by C++ 20 contract or runtime assertion check).
+
+
The code’s domain implementation defines the payload type to be transported around by
+experimental::status_code<DomainType>, rather than it being
+hardcoded to int as in std::error_code. The payload type can be anything
+you like, including non-trivially-copyable, move-only, complex etc types.
+
+
This facility is extremely useful. Extra failure metadata such as stack
+backtraces can be returned, for example. You can absolutely vary the payload
+depending on whether NDEBUG or _DEBUG is defined, too.
+
+
If your domain defines a payload type which is trivially copyable or
+move relocating1, it gains an implicit convertibility to a move-only
+experimental::status_code<erased<T>> where T is another
+trivially copyable or move relocating type. This permits global headers
+to use a single, common, type erased, status code type which is highly
+desirable for code bases of any complexity. However, unlike std::error_code,
+which fulfils the exact same role in <system_error> based code, the type
+erased payload can be bigger than the hardcoded int in std::error_code.
+
+
This facility is also extremely useful, as extra failure metadata can be
+type erased, transported through code with no knowledge of such things,
+and the original type with failure metadata resurrected at the handling point.
+Indeed P1095 proposed std::error is a type alias to
+experimental::status_code<erased<intptr_t>>, and it can transport erased
+std::exception_ptr instances, POSIX error codes, and much more besides.
+
+
Equality comparisons between status code’s with non-identical domains are
+always semantic i.e. are they semantically equivalent, rather than exactly
+equal? This mirrors when you compare std::error_code to a std::error_condition,
+but as there is no equivalent for the latter in <system_error2>, this means
+that when you see the code:
+
if(code1==code2)...
+
+
… you can be highly confident that this is an inexact, semantic, match operation.
+The same code under <system_error> is highly ambiguous as to whether exact
+or inexact comparison is being performed (after all, all there is is “code1 == code2”,
+so it depends on the types of code1 and code2 which usually is not obvious).
+
+
The ambiguity, and high cognitive load during auditing <system_error> code for correctness, has
+led to many surprising and unexpected failure handling bugs during the past
+decade in production C++.
+
+
<system_error2>, being a new design, has all-constexpr construction and
+destruction which avoids the need for static global variables, as <system_error>
+has. Each of those static global variables requires an atomic fence just in
+case it has not been initialised, thus every retrieval of an error category bloats
+code and inhibits optimisation, plus makes the use of custom error code categories
+in header-only libraries unreliable. Boost.System has replicated the all-constexpr
+construction and destruction from <system_error2>, and thus now has similar
+characteristics in this regard.
+
+
Finally, this is a small but important difference. Under <system_error>,
+this extremely common use case is ambiguous:
+
if(ec)...
+
+
Does this code mean “if there was an error?”, or “if the error code is set?”,
+or “is the error code non-zero?”. The correct answer according to the standard is the last choice, but
+a quick survey of open source <system_error> based code on github quickly
+demonstrates there is widespread confusion regarding correct usage.
+
+
<system_error2> solves this by removing the boolean test entirely. One
+now writes if(sc.success()) ..., if(sc.failure()) ..., if(sc.empty()) ...
+and so on, thus eliminating ambiguity.
+
+
+
+
+
+
+
Move relocating is not in the standard, nor has been reviewed by WG21 yet. It is defined to be a type whose move constructor memcpy()’s the bits from source to destination, followed by memcpy() of the bits of a default constructed instance to source, and with a programmer-given guarantee that the destructor, when called on a default constructed instance, has no observable side effects. A surprising number of standard library types can meet this definition of move relocating, including std::vector<T>, std::shared_ptr<T>, and std::exception_ptr.
+ [return]
Much of the design of Boost.System (which went on to become <system_error>)
+has been retained in proposed <system_error2>, so an approximate map between
+<system_error2> and <system_error> and Boost.System can be given:
No equivalent (deliberately removed as hindsight proved it to be a design mistake leading to much confusing and hard to audit for correctness code)
+
+
std::error_code
+
boost::system::error_code
+
One of:
+
experimental::status_code<DomainType>
+
const experimental::status_code<void> &
+
experimental::status_code<erased<intptr_t>> (aliased to experimental::system_code)
+
experimental::errored_status_code<DomainType>
+
const experimental::errored_status_code<void> &
+
experimental::errored_status_code<erased<intptr_t>> (aliased to experimental::error)
+
+
+
std::system_error
+
boost::system::system_error
+
One of:
+
const experimental::status_error<void> &
+
experimental::status_error<DomainType>
+
+
+
+
As is obvious from the above, in <system_error2> one must be much more specific and accurate
+with respect to intent and specification and desired semantics than with <system_error>. Much
+ambiguity and incorrectness which flies silently in <system_error> will
+refuse to compile in <system_error2>.
+
+
+
Last revised: January 27, 2019 at 13:13:26 UTC
+
+
+
+
+
+
diff --git a/doc/html/experimental/outcome.html b/doc/html/experimental/outcome.html
new file mode 100644
index 00000000..e44b8fb5
--- /dev/null
+++ b/doc/html/experimental/outcome.html
@@ -0,0 +1,101 @@
+
+
+Tying it all together - Boost.Outcome documentation
+
+
+
+
+
+
+
+
+
+
Tying it all together
+
+
+
Firstly let’s alias a more convenient form of status_result:
Returned error has a code domain of 'file i/o error domain', a message of 'No such file or directory (c:\users\ned\documents\boostish\outcome\doc\src\snippets\experimental_status_code.cpp:195)'
+
+And semantically comparing it to 'errc::no_such_file_or_directory' = 1
+
+
+
Conclusion
+
+
Once you get used to <system_error2> and the fact that any result with
+E = error is always move-only, using experimental Outcome is just like
+using normal Outcome. Except that codegen will be better, custom domains
+are safe to use in headers, semantic comparisons have guaranteed complexity
+bounds, and build times are much reduced.
+
+
What’s not to like? :)
+
+
Finally, if you have feedback on using experimental Outcome which you think
+would be of use to the standards committee when evaluating possible
+implementations of P0709 Zero overhead exceptions: Throwing values,
+please do get in touch! This especially includes successful experiences!!!
So, the default E is the erased status code system_code, which can represent
+any generic_code, posix_code, win32_code, nt_code, com_code and many
+other integer error and status
+codings. Note that system_code may represent successes as well as failures.
+This mirrors, somewhat, how std::error_code can have an all bits zero defaulted
+state.
+
+
You can absolutely choose an E type which is non-erased e.g. posix_code directly.
+You can also choose an E type which is contract guaranteed to be a failure
+rather than an unknown success or failure – see errored_status_code.
+
+
Whether to choose typed status codes versus the erased status codes depends on your
+use cases. Outcome replicates faithfully the implicit and explicit conversion
+semantics of its underlying types, so you can mix results and outcomes of
+<system_error2> types exactly as you can the <system_error2> types themselves
+e.g. typed forms will implicitly convert into erased forms if the source type
+is trivially copyable or move relocating. This means that you can return a
+generic_code from a function returning a system_code or error, and it’ll
+work exactly as you’d expect (implicit conversion).
+
+
+
note
+
As status_code<erased<T>> is move-only, so is any status_result or status_outcome.
+For some reason this surprises a lot of people, and they tend to react by not using the erased
+form because it seems “difficult”.
+
+
+
+
+
It is actually, in fact, a wise discipline to follow to make all functions return
+move-only types if you care about determinism and performance. Whilst C++ 17 onwards
+does much to have the compiler avoid copying of identical function return values thanks to
+guaranteed copy elision, when a chain of functions return different types, if the
+programmer forgets to scatter std::move() appropriately, copies rather than moves
+tend to occur in non-obvious ways. No doubt future C++ standards will improve on the
+automatic use of moves instead of copies where possible, but until then making all
+your result and outcome types move-only is an excellent discipline.
+
+
Note that move-only result and outcome capable code (i.e. your project is in Experimental
+Outcome configuration) usually compiles fine when result and outcome are copyable
+(i.e. your project is in Standard Outcome configuration), albeit sometimes with a few
+compiler warnings about unnecessary use of std::move().
Here follows a worked example of use of Experimental Outcome. It presents
+the same sample program I sent to the San Diego 2018 WG21 standards meeting
+after I was asked by the committee to demonstrate how P1095 implements P0709
+in a working code example they could study and discuss.
+
+
We will walk through this worked example, step by step, explaining how each
+part works in detail. This will help you implement your own code based on
+Experimental Outcome.
We are going to define a simple custom code domain which defines that
+the status code’s payload will consist of a POSIX error code, and the
+__FILE__ and __LINE__ where the failure occurred. This custom status
+code will have an implicit conversion to type erased error defined, which dynamically
+allocates memory for the original status code, and outputs an error
+which manages that dynamic allocation, indirecting all queries etc
+to the erased custom status code type such that the error instance
+quacks as if just like the original. This demonstrates that error could
+just as equally convey a std::exception_ptr, for example, or indeed
+manage the lifetime of any pointer.
Code domains are 100% constexpr to construct and destruct, as are status codes.
+This enables the compiler to 100% instantiate both only in its mind, and to emit
+zero code and thus zero overhead.
+
+
Unfortunately it also means that it must be possible for each domain to be instantiated an infinite
+number of times, and being 100% in constexpr, any instances never have a unique
+address in memory either. Thus we cannot compare domains for equivalence using
+their address in memory, as
+std::error_category
+ does.
(In case you are wondering about the chance of collision for a 64 bit integer, SG14 estimated that
+approximately 190,000 separate domains would need to exist in a single process
+for there to be a 0.00000001% probability of collision if the random number
+source is very random)
+
+
// unique id must be from a hard random number source
+// Use https://www.random.org/cgi-bin/randbyte?nbytes=8&format=h to get a hard random 64 bit id.
+// Do NOT make up your own value. Do NOT use zero.
+constexprexplicit_file_io_error_domain(typename_base::unique_id_typeid=0x230f170194fcc6c7)noexcept:_base(id){}
+ staticinlineconstexprconst_file_io_error_domain&get();
+
A nice side effect of this approach is that custom error domains in header-only
+libraries are safe, unlike custom <system_error> error categories. Boost.System’s
+error categories can now opt into this same safe mechanism in order to also be
+safe in header only library use cases.
Back in The payload, we
+mentioned that there was no default implicit conversion of file_io_error
+(status_code<_file_io_error_domain>) to error, as error is too small
+to hold _file_io_error_domain::value_type.
+
+
We can tell the framework about available implicit conversions by defining
+an ADL discovered free function make_status_code() which takes our
+custom status code as input, and returns an error:
+
+
// Now tell `error` how it can implicitly construct from `file_io_error`.
+// This is done by us defining a free function called `make_status_code()`
+// which is discovered using ADL. `error` is an alias to the refinement
+// `status_code<erased<intptr_t>>` which is a status code whose value type
+// has been erased into an `intptr_t`. `status_code<erased<intptr_t>>`
+// (i.e. `error`) are move relocating (P1029) i.e. they are move-only
+// types whose move operation is defined to leave the source in the same
+// representation as a default constructed instance, and for whose
+// non-trivial destructor when called upon a default constructed instance
+// is guaranteed to do nothing.
+inlineoutcome_e::system_codemake_status_code(file_io_errorv)
+{
+ // `make_status_code_ptr()` dynamically allocates memory to store an
+// instance of `file_io_error`, then returns a status code whose domain
+// specifies that its value type is a pointer to `file_io_error`. The
+// domain is a templated instance which indirects all observers of the
+// status code to the pointed-to status code.
+//
+// Note that the status code returned's value type is a pointer, which
+// by definition fits into `intptr_t` and is trivially copyable.
+// Therefore `system_code` (which is also a type alias to
+// `status_code<erased<intptr_t>>`) is happy to implicitly construct
+// from the status code returned by `make_status_code_ptr()`.
+returnmake_status_code_ptr(std::move(v));
+}
+
You may remember that our custom _file_io_error_domain inherits from
+outcome_e::posix_code::domain_type, and thus does not have to
+implement the many pure virtual functions required by outcome_e::status_code_domain.
+
+
What we do need to do is reimplement _do_message() to append the
+file and line information to the POSIX error description string
+returned by outcome_e::posix_code::domain_type. This causes
+the status code’s .message() observer to return a string
+with the extra payload information represented in text.
+
+
// Return a string describing a specific code. We will return the
+// string returned by our POSIX code base domain, with the source
+// file and line number appended
+virtual_base::string_ref_do_message(constoutcome_e::status_code<void>&code)constnoexceptoverridefinal// NOLINT
+{
+ assert(code.domain()==*this);
+
+ // Fetch message from base domain (POSIX)
+automsg=_base::_do_message(code);
+ constauto&c1=static_cast<constfile_io_error&>(code);// NOLINT
+constvalue_type&v=c1.value();
+
+ // Append my source file and line number
+if(v.file==nullptr)
+ {
+ returnmsg;
+ }
+ size_tlength=strlen(v.file)+16+msg.size();
+ auto*p=static_cast<char*>(malloc(length));// NOLINT
+if(p==nullptr)
+ {
+ return_base::string_ref("failed to get message from system");
+ }
+ sprintf(p,"%s (%s:%d)",msg.data(),v.file,v.lineno);
+
+ // Return as atomically reference counted string
+return_base::atomic_refcounted_string_ref(p,length);
+ }
+};
+
Firstly let’s alias the experimental Outcome namespace into something
+less tedious to type, declare our custom status code type, and get
+started on defining the custom status code domain implementation.
+
+
namespaceoutcome_e=BOOST_OUTCOME_V2_NAMESPACE::experimental;
+
+// To define a `file_io_error` which participates in the P1028 world
+// of `std::error`, we must first declare, then define, a custom code
+// domain which extends `posix_code` (the std error coding for POSIX
+// failures). The following is fairly standard boilerplate for defining
+// a custom code domain. It is analogous to defining a custom `std::error_category`.
+
+class_file_io_error_domain;
+// We define `file_io_error` to be the status code whose domain is `_file_io_error_domain`.
+usingfile_io_error=outcome_e::status_code<_file_io_error_domain>;
+
+// Now we define `_file_io_error_domain`.
+class_file_io_error_domain:publicoutcome_e::posix_code::domain_type
+{
+ using_base=typenameoutcome_e::posix_code::domain_type;
+
Note that we inherit from outcome_e::posix_code::domain_type, not
+from outcome_e::status_code_domain. We thus reuse most of the
+implementation of outcome_e::posix_code::domain_type rather than
+implementing required functionality. If you would like to see a
+fuller treatment of defining a custom status code domain from
+scratch, see this worked example here.
Back in The constructor, we
+declared but did not implement a .get() function which returns a constexpr static
+instance of the domain. We implement this now:
<system_error2> does not use std::string to return possibly statically
+or dynamically allocated strings, and thus avoids dragging in a lot of the
+standard library which impacts build times.
+
+
Instead status code domains have a string_ref,
+which has a polymorphic implementation which may or may not manage a dynamic
+memory allocation using an atomic reference counter. Due to this polymorphism, you don’t
+need to worry which implementation is actually in use under the bonnet
+when you pass around string_ref instances.
+
+
string_ref provides the same member functions as a span<const char>,
+and so participates ordinarily in STL algorithms and containers. In
+particular, if you need to string search or slice it, you can construct a
+string_view on top easily.
+
+
// Return the name of our custom code domain
+virtual_base::string_refname()constnoexceptoverridefinal// NOLINT
+{
+ staticstring_refv("file i/o error domain");
+ returnv;// NOLINT
+}
+
Now you understand what string_ref does, returning the name of the
+status code domain is self describing. Note we use the non-managing
+constructor of string_ref, as the string "file i/o error domain"
+is statically stored. We cache the returned value locally in static
+storage.
We define the code domain’s value_type – the payload to be transported by
+status codes using this code domain – to be a POSIX errno value, an integer
+line number and a const char pointer.
+
+
public:
+ // This is the value type for `file_io_error`. We add line number and source file path.
+structvalue_type
+ {
+ typenameoutcome_e::posix_code::value_typeerrcode;// from POSIX, as we inherit from _posix_code_domain
+
+ // Our additional payload
+intlineno;// from __LINE__
+constchar*file;// from __FILE__
+// Could also place a backtrace of void *[16] here ...
+};
+
You will note that this is a TriviallyCopyable type, and so gains an implicit
+conversion to any status_code<erased<T>> where sizeof(T) >= sizeof(value_type).
+
+
error is however status_code<erased<intptr_t>>, and sizeof(intptr_t) < sizeof(value_type),
+so it is not possible to implicitly convert status codes from this domain into
+error. Instead, you must tell the compiler how to do the conversion, as we
+shall see later.
This is C-compatible if T and EC are C-compatible.
+std::error_code
+
+is probably C-compatible, but its layout is not standardised (though there is a
+normative note in the standard about its layout). Hence Outcome cannot provide a
+C macro API for standard Outcome, but we can for Experimental Outcome.
+
+
Does Outcome implement over-alignment?
+
+
Variant-based alternatives to Outcome such as
+ P0323 std::expected<T, E>
+
+would use std::aligned_union to ensure appropriate over-alignment for the storage of
+either a T or an E. This discovers the over-alignment for a type using
+std::alignment_of, which is defaulted to alignof().
+
+
Outcome uses struct-based storage, as described above. Any over-alignment of
+result or outcome will follow the ordinary alignment and padding rules for
+struct on your compiler. Traits such as std::alignment_of, or other standard
+library facilities, are not used.
+
+
Does Outcome implement the no-fail, strong or basic exception guarantee?
… the corresponding operation in all of value_type, error_type (and
+exception_type for outcome) is noexcept(true), then result and
+outcome’s operation is noexcept(true). This propagates the no-fail exception
+guarantee of the underlying types. Otherwise the basic guarantee applies for all
+but Swap, under the same rules as for the struct layout type given above e.g.
+value would be constructed first, then the flags, then the error. If the error
+throws, value and status bits would be as if the failure had not occurred, same
+as for aborting the construction of any struct type.
+
+
It is recognised that these weak guarantees may be unsuitable for some people,
+so Outcome implements swap() with much stronger guarantees, as one can locally refine,
+without too much work, one’s own custom classes from result and outcome implementing
+stronger guarantees for construction and assignment using swap() as the primitive
+building block.
+
+
The core ADL discovered implementation of strong guarantee swap is strong_swap(bool &all_good, T &a, T &b)
+.
+This can be overloaded by third party code with custom strong guarantee swap
+implementations, same as for std::swap(). Because strong guarantee swap may fail
+when trying to restore input state during handling of failure to swap, the
+all_good boolean becomes false if restoration fails, at which point both
+results/outcomes get marked as tainted via has_lost_consistency()
+.
+
+
It is up to you to check this flag to see if known good state has been lost,
+as Outcome never does so on your behalf. The simple solution to avoiding having
+to deal with this situation is to always choose your value, error and exception
+types to have non-throwing move constructors and move assignments. This causes
+the strong swap implementation to no longer be used, as it is no longer required,
+and standard swap is used instead.
+
+
Does Outcome have a stable ABI and API?
+
+
Right now, no. Though the data layout shown above is not expected to change.
+
+
Outcome’s ABI and API will be formally fixed as the v2 interface approximately
+one year after its first Boost release. Thereafter the
+ABI compliance checker
+will be run per-commit to ensure Outcome’s ABI and API remains stable.
+
+
Note that the stable ABI and API guarantee will only apply to standalone
+Outcome, not to Boost.Outcome. Boost.Outcome has dependencies on other
+parts of Boost which are not stable across releases.
+
+
Note also that the types you configure a result or outcome with also need
+to be ABI stable if result or outcome is to be ABI stable.
+
+
Can I use result<T, EC> across DLL/shared object boundaries?
+
+
A known problem with using DLLs (and to smaller extent shared libraries) is that global
+objects may get duplicated: one instance in the executable and one in the DLL. This
+behaviour is not incorrect according to the C++ Standard, as the Standard does not
+recognize the existence of DLLs or shared libraries. Therefore, program designs that
+depend on globals having unique addresses may become compromised when used in a program
+using DLLs.
+
+
Nothing in Outcome depends on the addresses of globals, plus the guaranteed fixed data
+layout (see answer above) means that different versions of Outcome can be used in
+different DLLs, and it probably will work okay (it is still not advised that you do that
+as that is an ODR violation).
+However, one of the most likely candidate for EC – std::error_code – does depend
+on the addresses of globals for correct functioning.
+
+
The standard library is required to implement globally unique addresses for the standard library
+provided
+std::error_category
+ implementations e.g. std::system_category().
+User defined error code categories may not have unique global addresses, and thus
+introduce misoperation.
+
+
boost::system::error_code, since version 1.69 does offer an opt-in guarantee
+that it does not depend on the addresses of globals if the user defined error code
+category opts-in to the 64-bit comparison mechanism. This can be seen in the specification of
+error_category::operator== in
+Boost.System synopsis.
+
+
Alternatively, the status_code in Experimental Outcome,
+due to its more modern design, does not suffer from any problems from being used in shared
+libraries in any configuration.
+
+
Why two types result<> and outcome<>, rather than just one?
+
+
result is the simple, success OR failure type.
+
+
outcome extends result with a third state to transport, conventionally (but not necessarily) some sort of “abort” or “exceptional” state which a function can return to indicate that not only did the operation fail, but it did so catastrophically i.e. please abort any attempt to retry the operation.
+
+
A perfect alternative to using outcome is to throw a C++ exception for the abort code path, and indeed most programs ought to do exactly that instead of using outcome. However there are a number of use cases where choosing outcome shines:
+
+
+
Where C++ exceptions or RTTI is not available, but the ability to fail catastrophically without terminating the program is important.
+
Where deterministic behaviour is required even in the catastrophic failure situation.
+
In unit test suites of code using Outcome it is extremely convenient to accumulate test failures into an outcome 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.
+
Where a function is “dual use deterministic” i.e. it can be used deterministically, in which case one switches control flow based on .error(), or it can be used non-deterministically by throwing an exception perhaps carrying a custom payload.
+
+
+
How badly will including Outcome in my public interface affect compile times?
+
+
The quick answer is that it depends on how much convenience you want.
+
+
The convenience header <result.hpp> is dependent on <system_error> or Boost.System, which unfortunately includes <string> and thus
+drags in quite a lot of other slow-to-parse stuff. If your public interface already includes <string>,
+then the impact of additionally including Outcome will be low. If you do not include <string>,
+unfortunately impact may be relatively quite high, depending on the total impact of your
+public interface files.
+
+
If you’ve been extremely careful to avoid ever including the most of the STL headers
+into your interfaces in order to maximise build performance, then <basic_result.hpp>
+can have as few dependencies as:
+
+
+
<cstdint>
+
<initializer_list>
+
<iosfwd>
+
<new>
+
<type_traits>
+
<cstdio>
+
<cstdlib>
+
<cassert>
+
+
+
These, apart from <iosfwd>, tend to be very low build time impact in most standard
+library implementations. If you include only <basic_result.hpp>, and manually configure
+basic_result<> by hand, compile time impact will be minimised.
Is Outcome suitable for fixed latency/predictable execution coding such as for high frequency trading or audio?
+
+
Great care has been taken to ensure that Outcome never unexpectedly executes anything
+with unbounded execution times such as malloc(), dynamic_cast<>() or throw.
+Outcome works perfectly with C++ exceptions and RTTI globally disabled.
+
+
Outcome’s entire design premise is that its users are happy to exchange a small, predictable constant overhead
+during successful code paths, in exchange for predictable failure code paths.
+
+
In contrast, table-based exception handling gives zero run time overhead for the
+successful code path, and completely unpredictable (and very expensive) overhead
+for failure code paths.
+
+
For code where predictability of execution, no matter the code path, is paramount,
+writing all your code to use Outcome is not a bad place to start. Obviously enough,
+do choose a non-throwing policy when configuring outcome or result such as
+all_narrow
+ to guarantee that exceptions can never be thrown by Outcome
+(or use the convenience typedef for result, unchecked<T, E = varies>
+ which uses policy::all_narrow).
+
+
What kind of runtime performance impact will using Outcome in my code introduce?
+
+
It is very hard to say anything definitive about performance impacts in codebases one
+has never seen. Each codebase is unique. However to come up with some form of measure,
+we timed traversing ten stack frames via each of the main mechanisms, including the
+“do nothing” (null) case.
+
+
A stack frame is defined to be something called by the compiler whilst
+unwinding the stack between the point of return in the ultimate callee and the base
+caller, so for example ten stack allocated objects might be destructed, or ten levels
+of stack depth might be unwound. This is not a particularly realistic test, but it
+should at least give one an idea of the performance impact of returning Outcome’s
+result or outcome over say returning a plain integer, or throwing an exception.
+
+
High end CPU: Intel Skylake x64
+
+
This is a high end CPU with very significant ability to cache, predict, parallelise
+and execute out-of-order such that tight, repeated loops perform very well. It has
+a large μop cache able to wholly contain the test loop, meaning that these results
+are a best case performance.
+
+
+
+
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.
+
+
+
+
As you can see, throwing and catching an exception is
+expensive on table-based exception handling implementations such as these, anywhere
+between 26,000 and 43,000 CPU cycles. And this is the hot path situation, this
+benchmark is a loop around hot cached code. If the tables are paged out onto storage,
+you are talking about millions of CPU cycles.
+
+
Simple integer returns (i.e. do nothing null case)
+are always going to be the fastest as they do the least work, and that costs 80 to 90
+CPU cycles on this Intel Skylake CPU.
+
+
Note that returning a result<int, std::error_code> with a “success (error code)”
+is no more than 5% added runtime overhead over returning a naked int on GCC and clang. On MSVC
+it costs an extra 20% or so, mainly due to poor code optimisation in the VS2017.9 compiler. Note that “success
+(experimental status code)” optimises much better, and has almost no overhead over a
+naked int.
+
+
Returning a result<int, std::error_code> with a “failure (error code)”
+is less than 5% runtime overhead over returning a success on GCC, clang and MSVC.
+
+
You might wonder what happens if type E has a non-trivial destructor, thus making the
+result<T, E> have a non-trivial destructor? We tested E = std::exception_ptr and
+found less than a 5% overhead to E = std::error_code for returning success. Returning a failure
+was obviously much slower at anywhere between 300 and 1,100 CPU cycles, due to the
+dynamic memory allocation and free of the exception ptr, plus at least two atomic operations per stack frame, but that is
+still two orders of magnitude better than throwing and catching an exception.
+
+
We conclude that if failure is anything but extremely rare in your C++ codebase,
+using Outcome instead of throwing and catching exceptions ought to be quicker overall:
+
+
+
Experimental Outcome is statistically indistinguishable from the null case on this
+high end CPU, for both returning success and failure, on all compilers.
+
Standard Outcome is less than 5%
+worse than the null case for returning successes on GCC and clang, and less than 10% worse than
+the null case for returning failures on GCC and clang.
+
Standard Outcome optimises
+poorly on VS2017.9, indeed markedly worse than on previous point releases, so let’s
+hope that Microsoft fix that soon. It currently has a less than 20% overhead on the null case.
+
+
+
Mid tier CPU: ARM Cortex A72
+
+
This is a four year old mid tier CPU used in many high end mobile phones and tablets
+of its day, with good ability to cache, predict, parallelise
+and execute out-of-order such that tight, repeated loops perform very well. It has
+a μop cache able to wholly contain the test loop, meaning that these results
+are a best case performance.
+
+
+
+
Log graph comparing GCC 7.3 and clang 7.3 on ARM64, for exceptions-globally-disabled, ordinary and link-time-optimised build configurations.
+
+
+
+
This ARM chip is a very consistent performer – null case, success, or failure, all take
+almost exactly the same CPU cycles. Choosing Outcome, in any configuration, makes no
+difference to not using Outcome at all. Throwing and catching a C++ exception costs
+about 90,000 CPU cycles, whereas the null case/Outcome costs about 130 - 140 CPU cycles.
+
+
There is very little to say about this CPU, other than Outcome is zero overhead on it. The same
+applied to the ARM Cortex A15 incidentally, which I test cased extensively when
+deciding on the Outcome v2 design back after the first peer review. The v2 design
+was chosen partially because of such consistent performance on ARM.
+
+
Low end CPUs: Intel Silvermont x64 and ARM Cortex A53
+
+
These are low end CPUs with a mostly or wholly in-order execution core. They have a small
+or no μop cache, meaning that the CPU must always decode the instruction stream.
+These results represent an execution environment more typical of CPUs two decades
+ago, back when table-based EH created a big performance win if you never threw
+an exception.
+
+
+
+
Log graph comparing GCC 7.3 and clang 7.3 on x64, for exceptions-globally-disabled, ordinary and link-time-optimised build configurations.
+
+
+
+
+
Log graph comparing GCC 7.3 and clang 7.3 on ARM64, for exceptions-globally-disabled, ordinary and link-time-optimised build configurations.
+
+
+
+
The first thing to mention is that clang generates very high performance code for
+in-order cores, far better than GCC. It is said that this is due to a very large investment by
+Apple in clang/LLVM for their devices sustained over many years. In any case, if you’re
+targeting in-order CPUs, don’t use GCC if you can use clang instead!
+
+
For the null case, Silvermont and Cortex A53 are quite similar in terms of CPU clock cycles. Ditto
+for throwing and catching a C++ exception (approx 150,000 CPU cycles). However the Cortex
+A53 does far better with Outcome than Silvermont, a 15% versus 100% overhead for Standard
+Outcome, and a 4% versus 20% overhead for Experimental Outcome.
+
+
Much of this large difference is in fact due to calling convention differences. x64 permits up to 8 bytes
+to be returned from functions by CPU register. result<int> consumes 24 bytes, so on x64
+the compiler writes the return value to the stack. However ARM64 permits up to 64 bytes
+to be returned in registers, so result<int> is returned via CPU registers on ARM64.
+
+
On higher end CPUs, memory is read and written in cache lines (32 or 64 bytes), and
+reads and writes are coalesced and batched together by the out-of-order execution core. On these
+low end CPUs, memory is read and written sequentially per assembler instruction,
+so only one load or one store to L1
+cache can occur at a time. This makes writing the stack particularly slow on in-order
+CPUs. Memory operations which “disappear” on higher end CPUs take considerable time
+on low end CPUs. This particularly punishes Silvermont in a way which does not punish
+the Cortex A53, because of having to write multiple values to the stack to create the
+24 byte object to be returned.
+
+
The conclusion to take away from this is that if you are targeting a low end CPU,
+table-based EH still delivers significant performance improvements for the success
+code path. Unless determinism in failure is critically important, you should not
+use Outcome on in-order execution CPUs.
+
+
Why is implicit default construction disabled?
+
+
This was one of the more interesting points of discussion during the peer review of
+Outcome v1. v1 had a formal empty state. This came with many advantages, but it
+was not felt to be STL idiomatic as std::optional<result<T>> is what was meant, so
+v2 has eliminated any legal possibility of being empty.
+
+
The expected<T, E> proposal of that time (May 2017) did permit default construction
+if its T type allowed default construction. This was specifically done to make
+expected<T, E> more useful in STL containers as one can say resize a vector without
+having to supply an expected<T, E> instance to fill the new items with. However
+there was some unease with that design choice, because it may cause programmers to
+use some type T whose default constructed state is overloaded with additional meaning,
+typically “to be filled” i.e. a de facto empty state via choosing a magic value.
+
+
For the v2 redesign, the various arguments during the v1 review were considered.
+Unlike expected<T, E> which is intended to be a general purpose Either monad
+vocabulary type, Outcome’s types are meant primarily for returning success or failure
+from functions. The API should therefore encourage the programmer to not overload
+the successful type with additional meaning of “to be filled” e.g. result<std::optional<T>>.
+The decision was therefore taken to disable implicit default construction, but
+still permit explicit default construction by making the programmer spell out their
+intention with extra typing.
+
+
To therefore explicitly default construct a result<T> or outcome<T>, use one
+of these forms as is the most appropriate for the use case:
+
+
+
Construct with just in_place_type<T> e.g. result<T>(in_place_type<T>).
+
Construct via success() e.g. outcome<T>(success()).
+
Construct from a void form e.g. result<T>(result<void>(in_place_type<void>)).
+
+
+
How far away from the proposed std::expected<T, E> is Outcome’s checked<T, E>?
+
+
Not far, in fact after the first Boost.Outcome peer review in May 2017, Expected moved
+much closer to Outcome, and Outcome deliberately provides checked<T, E = varies>
+
+as a semantic equivalent.
+
+
Here are the remaining differences which represent the
+divergence of consensus opinion between the Boost peer review and WG21 on the proper
+design for this object:
+
+
+
checked<T, E> has no default constructor. Expected has a default constructor if
+T has a default constructor.
+
checked<T, E> uses the same constructor design as std::variant<...>. Expected
+uses the constructor design of std::optional<T>.
+
checked<T, E> cannot be modified after construction except by assignment.
+Expected provides an .emplace() modifier.
+
checked<T, E> permits implicit construction from both T and E when
+unambiguous. Expected permits implicit construction from T alone.
+
checked<T, E> does not permit T and E to be the same, and becomes annoying
+to use if they are constructible into one another (implicit construction self-disables).
+Expected permits T and E to be the same.
+
checked<T, E> throws bad_result_access_with<E> instead of Expected’s
+bad_expected_access<E>.
checked<T, E> does not provide operator*() nor operator->
+
checked<T, E>.error() is wide (i.e. throws on no-value) like .value().
+Expected’s .error() is narrow (UB on no-error). [checked<T, E> provides
+.assume_value() and .assume_error() for narrow (UB causing) observers].
+
+
checked<T, E> uses success<T> and failure<E> type sugars for disambiguation.
+Expected uses unexpected<E> only.
+
checked<T, E> requires E to be default constructible.
+
checked<T, E> defaults E to std::error_code or boost::system::error_code.
+Expected does not default E.
+
+
+
In fact, the two are sufficiently close in design that a highly conforming expected<T, E>
+can be implemented by wrapping up checked<T, E> with the differing functionality:
+
+
/* Here is a fairly conforming implementation of P0323R3 `expected<T, E>` using `checked<T, E>`.
+It passes the reference test suite for P0323R3 at
+https://github.com/viboes/std-make/blob/master/test/expected/expected_pass.cpp with modifications
+only to move the test much closer to the P0323R3 Expected, as the reference test suite is for a
+much older proposed Expected.
+
+Known differences from P0323R3 in this implementation:
+- `T` and `E` cannot be the same type.
+- `E` must be default constructible.
+- No variant storage is implemented (note the Expected proposal does not actually require this).
+*/
+
+namespacedetail
+{
+ template<classT,classE>usingexpected_result=BOOST_OUTCOME_V2_NAMESPACE::checked<T,E>;
+ template<classT,classE>structenable_default_constructor:publicexpected_result<T,E>
+ {
+ usingbase=expected_result<T,E>;
+ usingbase::base;
+ constexprenable_default_constructor()
+ :base{BOOST_OUTCOME_V2_NAMESPACE::in_place_type<T>}
+ {
+ }
+ };
+ template<classT,classE>usingselect_expected_base=std::conditional_t<std::is_default_constructible<T>::value,enable_default_constructor<T,E>,expected_result<T,E>>;
+}
+template<classT,classE>classexpected:publicdetail::select_expected_base<T,E>
+{
+ static_assert(!std::is_same<T,E>::value,"T and E cannot be the same in this expected implementation");
+ usingbase=detail::select_expected_base<T,E>;
+
+public:
+ // Inherit base's constructors
+usingbase::base;
+ expected()=default;
+
+ // Expected takes in_place not in_place_type
+template<class... Args>
+ constexprexplicitexpected(std::in_place_t/*unused*/,Args&&...args)
+ :base{BOOST_OUTCOME_V2_NAMESPACE::in_place_type<T>,std::forward<Args>(args)...}
+ {
+ }
+
+ // Expected always accepts a T even if ambiguous
+BOOST_OUTCOME_TEMPLATE(classU)
+ BOOST_OUTCOME_TREQUIRES(BOOST_OUTCOME_TPRED(std::is_constructible<T,U>::value))
+ constexprexpected(U&&v)
+ :base{BOOST_OUTCOME_V2_NAMESPACE::in_place_type<T>,std::forward<U>(v)}
+ {
+ }
+
+ // Expected has an emplace() modifier
+template<class... Args>voidemplace(Args&&...args){*static_cast<base*>(this)=base{BOOST_OUTCOME_V2_NAMESPACE::in_place_type<T>,std::forward<Args>(args)...};}
+
+ // Expected has a narrow operator* and operator->
+constexprconstT&operator*()const&{returnbase::assume_value();}
+ constexprT&operator*()&{returnbase::assume_value();}
+ constexprconstT&&operator*()const&&{returnbase::assume_value();}
+ constexprT&&operator*()&&{returnbase::assume_value();}
+ constexprconstT*operator->()const{return&base::assume_value();}
+ constexprT*operator->(){return&base::assume_value();}
+
+ // Expected has a narrow error() observer
+constexprconstE&error()const&{returnbase::assume_error();}
+ constexprE&error()&{returnbase::assume_error();}
+ constexprconstE&&error()const&&{returnbase::assume_error();}
+ constexprE&error()&&{returnbase::assume_error();}
+};
+template<classE>classexpected<void,E>:publicBOOST_OUTCOME_V2_NAMESPACE::result<void,E,BOOST_OUTCOME_V2_NAMESPACE::policy::throw_bad_result_access<E,void>>
+{
+ usingbase=BOOST_OUTCOME_V2_NAMESPACE::result<void,E,BOOST_OUTCOME_V2_NAMESPACE::policy::throw_bad_result_access<E,void>>;
+
+public:
+ // Inherit base constructors
+usingbase::base;
+
+ // Expected has a narrow operator* and operator->
+constexprvoidoperator*()const{base::assume_value();}
+ constexprvoidoperator->()const{base::assume_value();}
+};
+template<classE>usingunexpected=BOOST_OUTCOME_V2_NAMESPACE::failure_type<E>;
+template<classE>unexpected<E>make_unexpected(E&&arg)
+{
+ returnBOOST_OUTCOME_V2_NAMESPACE::failure<E>(std::forward<E>(arg));
+}
+template<classE,class... Args>unexpected<E>make_unexpected(Args&&...args)
+{
+ returnBOOST_OUTCOME_V2_NAMESPACE::failure<E>(std::forward<Args>(args)...);
+}
+template<classE>usingbad_expected_access=BOOST_OUTCOME_V2_NAMESPACE::bad_result_access_with<E>;
+
Outcome is not aimed at the same audience as Expected. We target developers
+and users who would be happy to use Boost. Expected targets the standard library user.
+
+
Outcome believes that the monadic use case isn’t as important as Expected does.
+Specifically, we think that 99% of use of Expected in the real world will be to
+return failure from functions, and not as some sort of enhanced or “rich” Optional.
+Outcome therefore models a subset of Variant, whereas Expected models an extended Optional.
+
+
Outcome believes that if you are thinking about using something like Outcome,
+then for you writing failure code will be in the same proportion as writing success code,
+and thus in Outcome writing for failure is exactly the same as writing for success.
+Expected assumes that success will be more common than failure, and makes you type
+more when writing for failure.
+
+
Outcome goes to considerable effort to help the end user type fewer characters
+during use. This results in tighter, less verbose, more succinct code. The cost of this is a steeper
+learning curve and more complex mental model than when programming with Expected.
+
+
Outcome has facilities to make easier interoperation between multiple third
+party libraries each using incommensurate Outcome (or Expected) configurations. Expected does
+not do any of this, but subsequent WG21 papers do propose various interoperation
+mechanisms, one of which Outcome implements so code using Expected will seamlessly
+interoperate with code using Outcome.
+
+
+
Is Outcome riddled with undefined behaviour for const, const-containing and reference-containing types?
+
+
The short answer is yes, but it probably won’t matter to you in practice.
+
+
The longer answer is that the same problem affects lots of C++ out there,
+so lots of production code will break if Outcome ever breaks on this. The
+potentially sometime-in-the-future affected code sequence would be:
+
structconst_containing_type
+{
+ constintno;// only concerns const and reference types
+const_containing_type(intn):no(n){}
+};
+
+externvoidexternal_function(int,constresult<const_containing_type>&);
+
+intexample_const_propagation2()
+{
+ result<const_containing_type>a{5};
+ constint&x=a.value().no;
+ external_function(x,a);// might call an outcome function which calls placement new!
+returnx;// does this reload x, or assume it hasn't changed?
+}
+
+
GCCs up to v10, clangs up to v9 and MSVCs up to VS2019.1 do reload x after
+the call of an unknown function, even though it has constant type. This may change
+in future compilers due to changes in the C++ standard to encourage such
+optimisations.
+
+
Brief history of C++ standard changes
+
+
Before the C++ 14 standard, placement new into storage which used to contain
+a const type was straight out always undefined behaviour, period. Thus all use of
+placement new within a result<const_containing_type>, or indeed an optional<const_containing_type>, is always
+undefined behaviour before C++ 14. From [basic.life] for the C++ 11 standard:
+
+
+
Creating a new object at the storage location that a const object with static,
+thread, or automatic storage duration occupies or, at the storage location
+that such a const object used to occupy before its lifetime ended results
+in undefined behavior.
+
+
+
This being excessively restrictive, from C++ 14 onwards, [basic_life] now states:
+
+
+
If, after the lifetime of an object has ended and before the storage which
+the object occupied is reused or released, a new object is created at the
+storage location which the original object occupied, a pointer that
+pointed to the original object, a reference that referred to the original
+object, or the name of the original object will automatically refer to the
+new object and, once the lifetime of the new object has started, can be
+used to manipulate the new object, if:
+
+
— the storage for the new object exactly overlays the storage location which
+ the original object occupied, and
+
+
— the new object is of the same type as the original object (ignoring the
+ top-level cv-qualifiers), and
+
+
— the type of the original object is not const-qualified, and, if a class type,
+ does not contain any non-static data member whose type is const-qualified
+ or a reference type, and
+
+
— neither the original object nor the new object is a potentially-overlapping
+ subobject
+
+
+
Leaving aside my personal objections to giving placement new of non-const
+non-reference types magical pointer renaming powers, the upshot is that if
+you want defined behaviour for placement new of types containing const types
+or references, you must store the pointer returned by placement new, and use
+that pointer for all further reference to the newly created object. This
+obviously adds eight bytes of storage to a result<const_containing_type>, which is highly
+undesirable given all the care and attention paid to keeping it small. The alternative
+is to use
+std::launder
+, which was added in C++ 17, to ‘launder’
+the storage into which we placement new before each and every use of that
+storage. This forces the compiler to reload the object stored by placement
+new on every occasion, and not assume it is can be constant propagated, which
+impacts codegen quality.
+
+
As neither situation is obviously desirable, after much thought I have
+decided to simply do nothing apart from add this FAQ entry. I would say that
+because Outcome is 100% header-only, the compiler can always see the
+calls of placement new, and thus the compiler always knows that the
+preceding const or reference object is dead, and there is now a new const
+or reference object in its place. I appreciate that this is a hand waving
+response, and code using Outcome will still contain undefined behaviour if
+you use it with a const type, or a type containing const or reference types.
+
+
However the reality on the ground is that a ton of production C++ code does
+placement new of types potentially containing const or reference types, and
+it is highly unlikely that C++ compilers will, in practice, break all that
+production code, especially as the template type supplied to library code is often
+outside one’s control. If, however, compilers do end up moving ahead on
+optimising this aggressively, Outcome will need to add laundering for any
+type containing const or reference types, for which one needs Reflection
+into the language in any case. We shall thus wait until later to see what
+happens.
Outcome has had an interesting history, and it is worth summarising it here to show how a
+Boost library comes to life. The following recollections are by Niall Douglas, and may be
+faulty due to his aging memory.
+
+
+
+
+
The genesis of Outcome v1
+
+
The git repo began life as a “Boost.Spinlock” in June 2014 hived out of Boost.AFIO v1 where it had existed
+for some time as an internal library. In October 2014 I added in the original prototype
+Boost.Expected reference library as a git submodule, and began developing a non-allocating
+future<T>/promise<T> as an extension of expected<T, std::exception_ptr> as a faster,
+monadic future-promise was something which AFIO v1 sorely needed.
+
+
The original prototype Boost.Expected library was a large and very complex beastie.
+I was fortunate to be employed on a contract in late 2014 early 2015 where I saw it deployed at
+scale into an existing large C++ codebase. Expected was really great and powerful, but it absolutely
+murdered compile times in a large C++ codebase, and made LTO effectively infeasible.
+I also found its implementation non-conducive to implementing
+future-promise with it, and so I resolved to implement a much more powerful policy driven
+monad factory which could stamp out everything from an option<T> right through to a
+future-promise pair, all using the exact same basic_monad<> and therefore all with a full
+monadic programming API, C++ 17 continuations/monadic bind and intelligently convertible into one another.
+Moreover, all this needed to have an absolute minimum impact on compile times and runtime
+overheads, neither of which were strengths of the original prototype Boost.Expected library.
+
+
By August 2015 “Boost.Monad” was delivering on all those requirements and then some, but it lacked
+maturity through use in other code. Summer 2015 saw the Boost peer review of AFIO v1 which
+was roundly rejected. After considering the ample review feedback, it was realised that
+AFIO v2 would be a very different design, one no longer using futures, memory allocation
+nor C++ exceptions. As AFIO v2 was started from scratch and using Outcome heavily from the
+very beginning (every AFIO v2 API returns a result<T>), Outcome began to gain bug fixes and
+shed features, with the non-allocating future-promise implementation being dropped in May
+2016 and a large chunk of type based metaprogramming being replaced with cleaner variable template metaprogramming
+in June. After CppCon 2016 in September, then began the long process of getting Outcome
+ready for Boost peer review in Q1 2017 which involved a repeated sequence of complete rewrites
+of the tutorial in response to multiple rounds of feedback from the C++ community, with
+at least four complete rewrites currently at the time of writing.
+
+
In parallel to all this development on Outcome, Expected went before the LEWG and entered
+the C++ standards track. As the WG21 meetings went by, Expected experienced a period
+of being stripped back and much of the complexity which had so murdered compile and
+link times in 2014-2015 fell away, thus the Expected proposed in P0323R1 ended up landing
+so close to Outcome that in January 2017 it was just a few hours work to implement
+Expected using the core basic_monad infrastructure in Outcome. That highly flexible
+policy based design which made monadic future-promise possible made it similarly easy
+to implement a highly conforming Expected, indeed in early 2017 Outcome’s Expected was much
+closer to P0323R1 than any other implementation including the LEWG reference implementation.
+And unlike the LEWG reference implementation, Outcome has had eighteen months of that
+finely tuned patina you only get when a library is in use by other code bases.
+
+
In February 2017 it became realised that the userbase really wanted a high quality expected<T, E>
+implementation rather than anything similar but not the same which Outcome had invented.
+The only just implemented Expected implementation based on basic_monad therefore took
+primacy. The final rewrite of the documentation before peer review submission was one
+which made it look like Outcome was primarily an expected<T, E> implementation with a
+few useful extensions like outcome<T> and result<T>. I was sad to so pivot, but it
+was obvious that Outcome would see far wider popularity and usage as primarily an Expected
+implementation.
+
+
Almost three years after its beginning, Outcome v1 finally went before Boost peer review
+in May 2017 which turned into one of the longest and most detailed peer reviews Boost has
+done in recent years, with over 800 pieces of review feedback submitted. It was by consensus
+rejected, with substantial feedback on what to do instead.
+
+
Outcome v2
+
+
During the very lengthy peer review, roughly three groups of opinion emerged as to what
+a value|error transporting class ought to look like:
+
+
+
1. Lightweight
+
A simple-as-possible T and/or E transport without any
+implementation complexity.
+
2. Medium
+
A variant stored T or E1 ... En
+where T is the expected value and E1 ...
+are the potential unexpected values. This implemention really ought to be implemented
+using C++ 17's std::variant<...> except with stronger never-empty guarantees.
+
+
3. Heavy
+
A full fat Either monad participating fully in a wider monadic programming framework for C++.
+
+
+
Peter Dimov was very quickly able to implement an expected<T, E1, ...> using his
+variant2 library, and thus there seemed little
+point in replicating his work in an Outcome v2. The lightweight choice seemed to be the
+best path forwards, so in June 2017 the bare minimum result<T, E> and outcome<T, EC, P>
+as presented in this library was built, using the same constructor design as std::variant<...>.
+Significant backwards compatibility with v1 Outcome code was retained, as the review
+had felt the basic proposed design fine.
+
+
A period of maturation then followed by porting a large existing codebase using Outcome v1
+to v2, and writing a significant amount of new code using v2 to test it for unanticipated
+surprises and bugs. Quite a few corner cases were found and fixed. At the end of September
+2017, Outcome v2 was deemed to be “mature”, and a script generated “Boost edition” made
+available.
+
+
All that remained before it was ready for a second Boost peer review was the
+documentation. This took four months to write (same time as to write the library itself!),
+and in January 2018 Outcome had its second Boost peer review, which it passed!
+
+
Outcome v2.1
+
+
The changes requsted during the review of v2.0 were fairly modest: result and outcome would
+be renamed to basic_result and basic_outcome, and a clean separation of concerns between the
+basic_* layer and the “convenience” layer would be created. That suited Outcome nicely,
+as the basic_* layer could have minimum possible header dependencies and thus minimum possible build times
+impact, which was great for big iron users with multi-million line C++ codebases. This also
+had the nice side effect of permitting both Boost and std implementations to be supported
+concurrently in both Outcome and Boost.Outcome.
Concurrently to that, just before the review of Outcome 2.0, I had mooted a number of semantic and compile time performance
+improvements to <system_error> with the proposal that we mildly break Boost.System with
+improvements and see how badly real world code broke in response. This was not widely
+accepted at that time (though they have been since incorporated into Boost.System, and proposed
+defect remedies for <system_error> for C++ 23). I therefore wrote an improved <system_error2> which fixed all the problems
+listed at P0824 (Summary of SG14 discussion on <system_error>)
+and fixed up Outcome so one could use it without any system error implementation,
+or with the STL one or with the proposed improved one.
+
+
This proposed improved <system_error2> was proposed by me as the library support for
+P0709 Zero overhead exceptions in P1095 Zero overhead deterministic failure,
+specifically as the implementation of P0709’s proposed std::error value type. As
+proposed improved <system_error2> is bundled with Outcome in
+experimental, that means that Outcome and Boost
+users can gain the non-language benefits of one possible implementation of P0709
+today in any conforming C++ 14 compiler.
+
+
At the time of writing, just before Outcome enters Boost (January 2019), Herbceptions have
+been voted upon only by SG14 Low Latency and LEWG, both giving unanimous acclamation. They have yet to be voted upon by the
+rest of the committee. The P1095 proposed implementation of P0709 has been voted upon by
+WG14 C Programming Language, where the C-relevant parts were approved in principle by a large majority. So
+the future currently looks hopeful that C, and C++, will gain language support for
+specifying deterministic failure sometime in the 2020s.
+
+
In the meantime, Outcome is a peer reviewed, battle tested, library-only implementation
+of Zero overhead exceptions with proposed std::error available under Experimental.
+Please strongly consider helping us test the proposed <system_error2> based std::error
+design! The committee would greatly welcome empirical experience.
+
+
+
+
Last revised: February 11, 2019 at 17:43:30 UTC
+
+
+
+
+
+
diff --git a/doc/html/history/graph.png b/doc/html/history/graph.png
new file mode 100644
index 00000000..9351158e
Binary files /dev/null and b/doc/html/history/graph.png differ
diff --git a/doc/html/images/boost.png b/doc/html/images/boost.png
new file mode 100644
index 00000000..b4d51fcd
Binary files /dev/null and b/doc/html/images/boost.png differ
diff --git a/doc/html/images/caution.png b/doc/html/images/caution.png
new file mode 100644
index 00000000..a5a5d348
Binary files /dev/null and b/doc/html/images/caution.png differ
diff --git a/doc/html/images/favicon.ico b/doc/html/images/favicon.ico
new file mode 100644
index 00000000..8968430d
Binary files /dev/null and b/doc/html/images/favicon.ico differ
diff --git a/doc/html/images/header-bg.png b/doc/html/images/header-bg.png
new file mode 100644
index 00000000..5be7cba7
Binary files /dev/null and b/doc/html/images/header-bg.png differ
diff --git a/doc/html/images/header-fg.png b/doc/html/images/header-fg.png
new file mode 100644
index 00000000..549c812e
Binary files /dev/null and b/doc/html/images/header-fg.png differ
diff --git a/doc/html/images/home.png b/doc/html/images/home.png
new file mode 100644
index 00000000..5584aacb
Binary files /dev/null and b/doc/html/images/home.png differ
diff --git a/doc/html/images/important.png b/doc/html/images/important.png
new file mode 100644
index 00000000..574cf282
Binary files /dev/null and b/doc/html/images/important.png differ
diff --git a/doc/html/images/next.png b/doc/html/images/next.png
new file mode 100644
index 00000000..59800b4e
Binary files /dev/null and b/doc/html/images/next.png differ
diff --git a/doc/html/images/next_disabled.png b/doc/html/images/next_disabled.png
new file mode 100644
index 00000000..10a8c59d
Binary files /dev/null and b/doc/html/images/next_disabled.png differ
diff --git a/doc/html/images/note.png b/doc/html/images/note.png
new file mode 100644
index 00000000..ad6296a1
Binary files /dev/null and b/doc/html/images/note.png differ
diff --git a/doc/html/images/prev.png b/doc/html/images/prev.png
new file mode 100644
index 00000000..d88a40f9
Binary files /dev/null and b/doc/html/images/prev.png differ
diff --git a/doc/html/images/prev_disabled.png b/doc/html/images/prev_disabled.png
new file mode 100644
index 00000000..ab3c17e0
Binary files /dev/null and b/doc/html/images/prev_disabled.png differ
diff --git a/doc/html/images/space.png b/doc/html/images/space.png
new file mode 100644
index 00000000..a17badc2
Binary files /dev/null and b/doc/html/images/space.png differ
diff --git a/doc/html/images/up.png b/doc/html/images/up.png
new file mode 100644
index 00000000..17d9c3ec
Binary files /dev/null and b/doc/html/images/up.png differ
diff --git a/doc/html/images/up_disabled.png b/doc/html/images/up_disabled.png
new file mode 100644
index 00000000..e22bc871
Binary files /dev/null and b/doc/html/images/up_disabled.png differ
diff --git a/doc/html/images/warning.png b/doc/html/images/warning.png
new file mode 100644
index 00000000..cdb17c93
Binary files /dev/null and b/doc/html/images/warning.png differ
diff --git a/doc/html/index.html b/doc/html/index.html
new file mode 100644
index 00000000..484033bc
--- /dev/null
+++ b/doc/html/index.html
@@ -0,0 +1,173 @@
+
+
+Home - Boost.Outcome documentation
+
+
+
+
+
+
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
Outcome is a set of tools for reporting and handling function failures in contexts where directly using C++ exception handling is unsuitable. Such contexts include:
+
+
+
there are programs, or parts thereof, that are compiled with exceptions disabled;
+
+
there are parts of program that have a lot of branches depending on types of failures,
+where if-statements are cleaner than try-catch blocks;
+
+
there is a hard requirement that the failure path of execution should not cost more than the successful path of execution;
+
+
there are situations, like in the filesystem library, where whether the failure should be handled remotely
+(using a C++ exception throw), or locally cannot be made inside the function and needs to be decided by the caller,
+and in the latter case throwing a C++ exception is not desirable for the aforementioned reasons;
+
+
there are parts of the program/framework that themselves implement exception handling and prefer
+to not use exceptions to propagate failure reports across threads, tasks, fibers, etc;
+
+
one needs to propagate exceptions through layers that do not implement exception throw safety;
+
+
there is an external requirement (such as a company-wide policy) that failure handling paths are explicitly indicated in the code.
+
+
where interoperation with C code, without having to resort to C++ exception wrapper shims, is important.
+
+
+
Outcome addresses failure handling through returning a special type from functions, which is able to store either a successfully computed value (or void), or the information about failure. Outcome also comes with a set of idioms for dealing with such types.
+
+
Particular care has been taken to ensure that Outcome has the lowest possible impact on build times,
+thus making it suitable for use in the global headers of really large codebases. Storage layout is
+guaranteed and is C-compatible for result<T, E>1, thus making Outcome based code long term ABI-stable.
+
+
Sample usage
+
+
The main workhorse in the Outcome library is result<T>: it represents either a successfully computed value of type T, or a std::error_code/boost::system::error_code2 representing the reason for failure. You use it in the function’s return type:
BOOST_OUTCOME_TRY is a control statement. If the returned result<T> object contains an error information, the enclosing function is immediately returned with result<U> containing the same failure information; otherwise an automatic object of type T
+is available in scope.
If you choose a C-compatible T and E type.
+ [return]
+
result<T> defaults to std::error_code for Standalone Outcome, and to boost::system::error_code for Boost.Outcome. You can mandate a choice using std_result<T> or boost_result<T>.
+ [return]
This section describes techniques currently used to report and handle failures
+in functions, it also shows why these techniques might be insufficient.
+
+
If you just want to learn how to use Outcome library go straight to Tutorial
+section.
+
+
+
note
+
Motivation section of this documentation is not complete yet.
The idiom of returning, upon failure, a special value and storing an error code
+(an int) inside a global (or thread-local) object errno is inherited from C,
+and used in its Standard Library:
+
intreadValue(constchar*filename)
+{
+ FILE*f=fopen(filename,"r");
+ if(f==NULL)
+ return0;// special value indicating failure
+// keep errno value set by fopen()
+
+ inti;
+ intr=fscanf(f,"%d",&i);
+ if(r==0||r==EOF){// special values: i not read
+errno=ENODATA;// choose error value to return
+return0;
+
+ fclose(f);
+ errno=0;// clear error info (success)
+returni;
+}
+
+
One advantage (to some, and a disadvantage to others) of this technique is that it
+uses familiar control statements (if and return) to indicate all execution
+paths that handle failures. When we read this code we know when and under what
+conditions it can exit without producing the expected result.
+
+
Downsides
+
+
Because on failure, as well as success, we write into a global (or thread-local)
+object, our functions are not pure: they have side effects. This means many
+useful compiler optimizations (like common subexpression elimination) cannot be
+applied. This shows that it is not only C++ that chooses suboptimal solutions
+for reporting failures.
+
+
Whatever type we return, we always need a special value to spare, which is
+sometimes troublesome. In the above example, if the successfully read value of
+i is 0, and we return it, our callers will think it is a failure even though
+it is not.
+
+
Error propagation using if statements and early returns is manual. We can easily
+forget to check for the failure, and incorrectly let the subsequent operations
+execute, potentially causing damage to the program state.
+
+
Upon nearly each function call layer we may have to change error code value
+so that it reflects the error condition adequate to the current layer. If we
+do so, the original error code is gone.
Error codes are reasonable error handling technique, also working in C.
+In this case the information is also stored as an int, but returned by value,
+which makes it possible to make functions pure (side-effect-free and referentially
+transparent).
Because the type of the error information (int) is known statically, no memory
+allocation or type erasure is required. This technique is very efficient.
+
+
Downsides
+
+
All failure paths written manually can be considered both an advantage and a
+disadvantage. Forgetting to put a failure handling if causes bugs.
+
+
If I need to substitute an error code returned by lower-level function with mine
+more appropriate at this level, the information about the original failure is
+gone.
+
+
Also, all possible error codes invented by different programmers in different
+third party libraries must fit into one int and not overlap with any other error
+code value. This is quite impossible and does not scale well.
+
+
Because errors are communicated through returned values, we cannot use function’s
+return type to return computed values. Computed values are written to function
+output parameters, which requires objects to be created before we have values
+to put into them. This requires many objects in unintended state to exist. Writing
+to output parameters often requires an indirection and can incur some run-time cost.
Exceptions are the default mechanism in C++ for reporting, propagating and
+processing the information about function failures. Their main advantage is
+the ability to describe the “success dependency” between functions: if you want to
+say that calling function g() depends on the successful execution of function f(),
+you just put g() below f() and that’s it:
+
inta()
+{
+ f();
+ g();// don't call g() and further if f() fails
+returnh();// don't call h() if g() fails
+}
+
+
In the C++ Standard terms this means that f() is sequenced beforeg().
+This makes failure handling extremely easy: in a lot of cases you do not have
+to do anything.
+
+
Also, while next operations are being canceled, the exception object containing
+the information about the initial failure is kept on the side. When at some point
+the cancellation cascade is stopped by an exception handler, the exception object
+can be inspected. It can contain arbitrarily big amount of data about the failure
+reason, including the entire call stack.
+
+
Downsides
+
+
There are two kinds of overheads caused by the exception handling mechanism. The
+first is connected with storing the exceptions on the side. Stack unwinding works
+independently in each thread of execution; each thread can be potentially handling
+a number of exceptions (even though only one exception can be active in one thread).
+This requires being prepared for storing an arbitrary number of exceptions of arbitrary
+types per thread. Additional things like jump tables also need to be stored in the
+program binaries.
+
+
Second overhead is experienced when throwing an exception and trying to find the
+handler. Since nearly any function can throw an exception of any time, this is
+a dynamic memory allocation. The type of an exception is erased and a run-time type
+identification (RTTI) is required to asses the type of the active exception object.
+The worst case time required for matching exceptions against handlers cannot be easily
+predicted and therefore exceptions are not suitable for real-time or low-latency
+systems.
+
+
Another problem connected with exceptions is that while they are good for program
+flows with linear “success dependency”, they become inconvenient in situations where
+this success dependency does not occur. One such notable example is releasing acquired
+resources which needs to be performed even if previous operations have failed.
+Another example is when some function c() depends on the success of at least one
+of two functions a() and b() (which try, for instance, to store user data by
+two different means), another example is when implementing a strong exception safety
+guarantee we may need to apply some fallback actions when previous operations have
+failed. When failures are reported by exceptions, the semantics of canceling all
+subsequent operations is a hindrance rather than help; these situations require special
+and non-trivial idioms to be employed.
+
+
For these reasons in some projects using exceptions is forbidden. Compilers offer
+switches to disable exceptions altogether (they refuse to compile a throw, and turn
+already compiled throws into calls to std::abort()).
A program’s thread of execution can enter a “disappointing” state for two reasons:
+
+
+
due to disappointing situation in the environment (operating system, external input),
+or
+
due to a bug in the program.
+
+
+
The key to handling these disappointments correctly is to identify to which
+category they belong, and use the tools adequate for a given category. In this
+tutorial when we say “error” or “failure” we only refer to the first category.
+A bug is not an error.
+
+
A bug is when a program is something else than what it is supposed to be. The
+correct action in that case is to change the program so that it is exactly what
+it is supposed to be. Unfortunately, sometimes the symptoms of a bug are only
+detected when the system is running and at this point no code changes are possible.
+
+
In contrast, a failure is when a correct function in a correct program reflects
+some disappointing behavior in the environment. The correct action in that case
+is for the program to take a control path different than usual, which will likely
+cancel some operations and will likely result in different communication with the
+outside world.
+
+
Symptoms of bugs can sometimes be detected during compilation or static program
+analysis or at run-time when observing certain values of objects that are declared
+never to be valid at certain points. One classical example is passing a null pointer
+to functions that expect a pointer to a valid object:
+
intf(int*pi)// expects: pi != nullptr
+{
+ return*pi+1;
+}
+
+
Passing a null pointer where it is not expected is so common a bug that tools
+are very good at finding them. For instance, static analyzers will usually detect
+it without even executing your code. Similarly, tools like undefined behavior
+sanitizers will compile a code as the one above so that a safety check is performed
+to check if the pointer is null, and an error message will be logged and program
+optionally terminated.
+
+
More, compilers can perform optimizations based on undefined behavior caused by
+dereferencing a null pointer. In the following code:
The compiler can see that if pi is null, the program would have undefined
+behavior. Since undefined behavior is required by the C++ standard to never
+be the programmer’s intention, the compiler
+assumes that apparently this function is never called with pi == nullptr. If so,
+j is always 0 and the code can be transformed to a faster one:
Functions like the one above that declare that certain values of input parameters
+must not be passed to them are said to have a narrow contract.
+
+
Compilers give you non-standard tools to tell them about narrow contracts, so
+that they can detect it and make use of it the same way as they are detecting
+invalid null pointers. For instance, if a function in your library takes an int
+and declares that the value of this int must never be negative. You can use
+__builtin_trap() available in GCC and clang:
+
voidh(inti)// expects: i >= 0
+{
+ if(i<0)__builtin_trap();
+
+ // normal program logic follows ...
+}
+
+
This instruction when hit, causes the program to exit abnormally, which means:
+
+
+
a debugger can be launched,
+
static analyzer can warn you if it can detect a program flow that reaches this
+point,
+
UB-sanitizer can log error message when it hits it.
+
+
+
Another tool you could use is __builtin_unreachable(), also available in GCC
+and clang:
+
voidh(inti)// expects: i >= 0
+{
+ if(i<0)__builtin_unreachable();
+
+ // normal program logic follows ...
+}
+
+
This gives a hint to the tools: the programmer guarantees that the program flow
+will never reach to the point of executing it. In other words, it is undefined
+behavior if control reaches this point. Compiler and other tools can take this
+for granted. This way they can deduce that expression i < 0 will never be true,
+and they can further use this assumption to issue warnings or to optimize the code.
+UB-sanitizers can use it to inject a log message and terminate if this point is
+nonetheless reached.
+
+
Allowing for some input values to be invalid works similarly to cyclic redundancy
+checks. It allows for the possibility to observe the symptoms of the bugs (not
+the bugs themselves), and if the symptom is revealed the hunt for the bug can start.
+This is not only tools that can now easily detect symptoms of bugs, but also
+humans during the code review. A reviewer can now say, “hey, function h() is
+expecting a non-negative value, but this i is actually -1; maybe you wanted
+to pass j instead?“.
+
+
+
Last revised: April 26, 2019 at 17:43:41 +0200
+
+
+
+
+
+
diff --git a/doc/html/motivation/plug_error_code.html b/doc/html/motivation/plug_error_code.html
new file mode 100644
index 00000000..ec556134
--- /dev/null
+++ b/doc/html/motivation/plug_error_code.html
@@ -0,0 +1,187 @@
+
+
+Plugging a library into std::error_code - Boost.Outcome documentation
+
+
+
+
+
+
This section illustrates how you can hook into the std::error_code system from
+the Standard Library in order to work with your own set of error codes. As is usually
+the case in C++, doing this is straightforward but requires typing boilerplate
+to tell the C++ STL about your custom error type. This is not part of Outcome library,
+but we still provide this short guide here, because how to do this is not well documented [1].
+
+
Suppose you want to report all reasons for failure in converting a std::string to a non-negative int.
+The list is:
+
+
+
EmptyString – the input string is empty,
+
IllegalChar – input contains characters that are not digits,
+
TooLong – input represents a number, but this number would not fit into a variable of type int.
+
+
+
#include<iostream>
+#include<string> // for string printing
+#include<system_error> // bring in std::error_code et al
+
+// This is the custom error code enum
+enumclassConversionErrc
+{
+ Success=0,// 0 should not represent an error
+EmptyString=1,
+ IllegalChar=2,
+ TooLong=3,
+};
+
+namespacestd
+{
+ // Tell the C++ 11 STL metaprogramming that enum ConversionErrc
+// is registered with the standard error code system
+template<>structis_error_code_enum<ConversionErrc>:true_type
+ {
+ };
+}
+
+namespacedetail
+{
+ // Define a custom error code category derived from std::error_category
+classConversionErrc_category:publicstd::error_category
+ {
+ public:
+ // Return a short descriptive name for the category
+virtualconstchar*name()constnoexceptoverridefinal{return"ConversionError";}
+ // Return what each enum means in text
+virtualstd::stringmessage(intc)constoverridefinal
+ {
+ switch(static_cast<ConversionErrc>(c))
+ {
+ caseConversionErrc::Success:
+ return"conversion successful";
+ caseConversionErrc::EmptyString:
+ return"converting empty string";
+ caseConversionErrc::IllegalChar:
+ return"got non-digit char when converting to a number";
+ caseConversionErrc::TooLong:
+ return"the number would not fit into memory";
+ default:
+ return"unknown";
+ }
+ }
+ // OPTIONAL: Allow generic error conditions to be compared to me
+virtualstd::error_conditiondefault_error_condition(intc)constnoexceptoverridefinal
+ {
+ switch(static_cast<ConversionErrc>(c))
+ {
+ caseConversionErrc::EmptyString:
+ returnmake_error_condition(std::errc::invalid_argument);
+ caseConversionErrc::IllegalChar:
+ returnmake_error_condition(std::errc::invalid_argument);
+ caseConversionErrc::TooLong:
+ returnmake_error_condition(std::errc::result_out_of_range);
+ default:
+ // I have no mapping for this code
+returnstd::error_condition(c,*this);
+ }
+ }
+ };
+}
+
+// Define the linkage for this function to be used by external code.
+// This would be the usual __declspec(dllexport) or __declspec(dllimport)
+// if we were in a Windows DLL etc. But for this example use a global
+// instance but with inline linkage so multiple definitions do not collide.
+#define THIS_MODULE_API_DECL extern inline
+
+// Declare a global function returning a static instance of the custom category
+THIS_MODULE_API_DECLconstdetail::ConversionErrc_category&ConversionErrc_category()
+{
+ staticdetail::ConversionErrc_categoryc;
+ returnc;
+}
+
+
+// Overload the global make_error_code() free function with our
+// custom enum. It will be found via ADL by the compiler if needed.
+inlinestd::error_codemake_error_code(ConversionErrce)
+{
+ return{static_cast<int>(e),ConversionErrc_category()};
+}
+
+intmain(void)
+{
+ // Note that we can now supply ConversionErrc directly to error_code
+std::error_codeec=ConversionErrc::IllegalChar;
+
+ std::cout<<"ConversionErrc::IllegalChar is printed by std::error_code as "
+ <<ec<<" with explanatory message "<<ec.message()<<std::endl;
+
+ // We can compare ConversionErrc containing error codes to generic conditions
+std::cout<<"ec is equivalent to std::errc::invalid_argument = "
+ <<(ec==std::errc::invalid_argument)<<std::endl;
+ std::cout<<"ec is equivalent to std::errc::result_out_of_range = "
+ <<(ec==std::errc::result_out_of_range)<<std::endl;
+ return0;
+}
+
This might look like a lot of extra boilerplate over simply using your custom
+error code enum directly, but look at the advantages:
+
+
+
Any code which can speak std::error_code can now work with errors from your
+code, AND without being recompiled.
+
std::system_error can now wrap your custom error codes seamlessly, allowing
+your custom error code to be converted into a C++ exception and back out again
+without losing information.
+
std::error_code knows how to print itself, and will print your custom error
+code without extra work from you. As usually you’d need to define a print routine
+for any custom error code you’d write anyway, there is actually very little extra
+boilerplate here.
+
If you implement the default_error_condition() override, you can allow code
+exclusively written to understand std::errc alone to examine your custom error
+code domain for equivalence to the standard error conditions, AND without being
+recompiled.
+
+
+
+
note
+
This documentation recommends that when you define your custom enum for representing
+error_codes, you should always make sure that value 0 never represents an actual error:
+it should either represent a success or should not be provided at all. If you only
+intend to use your enum inside result<> or outcome<> you can just start your
+enumerations from 1. If you intend to also return std::error_code directly from
+functions, you should probably define value 0 as success, so that you are able to
+inform about function’s success by returning MyEnum::Success. This is because error_code’s
+contextual conversion to bool (which some people use to check if there was an error or not)
+only checks for the numeric value of the error code (without looking at error domain (category)).
+
+
+
+
+
[1]: The only documentation I’m aware of is the quite old guide by Chris Kohlhoff, founder of ASIO and the Networking TS:
This section illustrates how you can hook into the boost::system::error_code system from
+the Boost in order to work with your own set of error codes. As is usually
+the case in C++, doing this is straightforward but requires typing boilerplate
+to tell Boost.System about your custom error type. This is not part of Outcome library,
+but we still provide this short guide here, because how to do this is not well documented [1].
+
+
Suppose you want to report all reasons for failure in converting a std::string to a non-negative int.
+The list is:
+
+
+
EmptyString – the input string is empty,
+
IllegalChar – input contains characters that are not digits,
+
TooLong – input represents a number, but this number would not fit into a variable of type int.
+
+
+
#include<boost/system/error_code.hpp> // bring in boost::system::error_code et al
+#include<iostream>
+#include<string> // for string printing
+
+// This is the custom error code enum
+enumclassConversionErrc
+{
+ Success=0,// 0 should not represent an error
+EmptyString=1,
+ IllegalChar=2,
+ TooLong=3,
+};
+
+namespaceboost
+{
+ namespacesystem
+ {
+ // Tell the C++ 11 STL metaprogramming that enum ConversionErrc
+// is registered with the standard error code system
+template<>structis_error_code_enum<ConversionErrc>:std::true_type
+ {
+ };
+ }// namespace system
+}// namespace boost
+
+namespacedetail
+{
+ // Define a custom error code category derived from boost::system::error_category
+classConversionErrc_category:publicboost::system::error_category
+ {
+ public:
+ // Return a short descriptive name for the category
+virtualconstchar*name()constnoexceptoverridefinal{return"ConversionError";}
+ // Return what each enum means in text
+virtualstd::stringmessage(intc)constoverridefinal
+ {
+ switch(static_cast<ConversionErrc>(c))
+ {
+ caseConversionErrc::Success:
+ return"conversion successful";
+ caseConversionErrc::EmptyString:
+ return"converting empty string";
+ caseConversionErrc::IllegalChar:
+ return"got non-digit char when converting to a number";
+ caseConversionErrc::TooLong:
+ return"the number would not fit into memory";
+ default:
+ return"unknown";
+ }
+ }
+ // OPTIONAL: Allow generic error conditions to be compared to me
+virtualboost::system::error_conditiondefault_error_condition(intc)constnoexceptoverridefinal
+ {
+ switch(static_cast<ConversionErrc>(c))
+ {
+ caseConversionErrc::EmptyString:
+ returnmake_error_condition(boost::system::errc::invalid_argument);
+ caseConversionErrc::IllegalChar:
+ returnmake_error_condition(boost::system::errc::invalid_argument);
+ caseConversionErrc::TooLong:
+ returnmake_error_condition(boost::system::errc::result_out_of_range);
+ default:
+ // I have no mapping for this code
+returnboost::system::error_condition(c,*this);
+ }
+ }
+ };
+}// namespace detail
+
+// Define the linkage for this function to be used by external code.
+// This would be the usual __declspec(dllexport) or __declspec(dllimport)
+// if we were in a Windows DLL etc. But for this example use a global
+// instance but with inline linkage so multiple definitions do not collide.
+#define THIS_MODULE_API_DECL extern inline
+
+// Declare a global function returning a static instance of the custom category
+THIS_MODULE_API_DECLconstdetail::ConversionErrc_category&ConversionErrc_category()
+{
+ staticdetail::ConversionErrc_categoryc;
+ returnc;
+}
+
+
+// Overload the global make_error_code() free function with our
+// custom enum. It will be found via ADL by the compiler if needed.
+inlineboost::system::error_codemake_error_code(ConversionErrce)
+{
+ return{static_cast<int>(e),ConversionErrc_category()};
+}
+
+intmain(void)
+{
+ // Note that we can now supply ConversionErrc directly to error_code
+boost::system::error_codeec=ConversionErrc::IllegalChar;
+
+ std::cout<<"ConversionErrc::IllegalChar is printed by boost::system::error_code as "
+ <<ec<<" with explanatory message "<<ec.message()<<std::endl;
+
+ // We can compare ConversionErrc containing error codes to generic conditions
+std::cout<<"ec is equivalent to boost::system::errc::invalid_argument = "
+ <<(ec==std::errc::invalid_argument)<<std::endl;
+ std::cout<<"ec is equivalent to boost::system::errc::result_out_of_range = "
+ <<(ec==std::errc::result_out_of_range)<<std::endl;
+ return0;
+}
+
This might look like a lot of extra boilerplate over simply using your custom
+error code enum directly, but look at the advantages:
+
+
+
Any code which can speak boost::system::error_code can now work with errors from your
+code, AND without being recompiled.
+
boost::system::system_error can now wrap your custom error codes seamlessly, allowing
+your custom error code to be converted into a C++ exception and back out again
+without losing information.
+
boost::system::error_code knows how to print itself, and will print your custom error
+code without extra work from you. As usually you’d need to define a print routine
+for any custom error code you’d write anyway, there is actually very little extra
+boilerplate here.
+
If you implement the default_error_condition() override, you can allow code
+exclusively written to understand boost::system::errc alone to examine your custom error
+code domain for equivalence to the standard error conditions, AND without being
+recompiled.
+
+
+
+
note
+
This documentation recommends that when you define your custom enum for representing
+error_codes, you should always make sure that value 0 never represents an actual error:
+it should either represent a success or should not be provided at all. If you only
+intend to use your enum inside result<> or outcome<> you can just start your
+enumerations from 1. If you intend to also return boost::system::error_code directly from
+functions, you should probably define value 0 as success, so that you are able to
+inform about function’s success by returning MyEnum::Success. This is because error_code’s
+contextual conversion to bool (which some people use to check if there was an error or not)
+only checks for the numeric value of the error code (without looking at error domain (category)).
+
+
+
+
+
[1]: The only documentation I’m aware of is the quite old guide by Chris Kohlhoff, founder of ASIO and the Networking TS:
Type std::error_code has been designed to be sufficiently small and trivial
+to be cheaply passed around, and at the same time be able to store sufficient
+information to represent any error situation from any library/sub-system in the
+world without a clash. Its representation is basically:
+
classerror_code
+{
+ error_category*domain;// domain from which the error originates
+intvalue;// numeric value of error within the domain
+};
+
+
Here, domain indicates the library from which the error originates. It is a
+pointer to a global object representing a given library/domain. Different
+libraries will be represented by different pointers to different globals.
+Each domain is expected to be represented by a global object derived from
+std::error_category. The uniqueness of the domain pointer value is guaranteed
+by the uniqueness of addresses of different global objects.
+
+
Now, value represents a numeric value of a particular error situation within
+the domain. Thus, different domains can use the same numeric value 1 to
+indicate different error situations, but two std::error_code objects will be
+different because the pointers representing domains will be different.
+
+
std::error_code comes with additional tools: a facility for defining custom
+domains with their set of error codes, and a facility for building predicates
+that allow classifying errors.
+
+
Once created and passed around (either inside a thrown exception or returned from functions by value) there is never a need to change the value of error_code
+object at any level. But at different levels one can use different predicates
+for classifying error situations appropriately to the program layer.
+
+
When a new library needs to represent its own set of error situations in an
+error_code it first has to declare the list of numeric value as an enumeration:
+
enumclassConvertErrc
+{
+ StringTooLong=1,// 0 should not represent an error
+EmptyString=2,
+ IllegalChar=3,
+};
+
+
Then it has to put some boiler-plate code to plug the new enumeration into the
+std::error_code system. Then, it can use the enum as an error_code:
Member value is mapped directly from the numeric value in the enumeration, and
+member domain is mapped from the type of the enumeration. Thus, this is a form
+of type erasure, but one that does allow type std::error_code to be trivial
+and standard-layout.
This recipe targets Boost versions including and after 1.70, where coroutine support is
+based around the asio::use_awaitable completion token. For integration with Boost versions
+before 1.70, see this recipe.
+
+
+
+
Use case
+
+
Boost.ASIO
+and standalone ASIO provide the
+async_result
+customisation point for adapting arbitrary third party libraries, such as Outcome, into ASIO.
+
+
Historically in ASIO you need to pass completion handler instances
+to the ASIO asynchronous i/o initiation functions. These get executed when the i/o
+completes.
+
+
// Dynamically allocate a buffer to read into. This must be move-only
+// so it can be attached to the completion handler, hence the unique_ptr.
+autobuffer=std::make_unique<std::vector<byte>>(1024);
+
+ // Begin an asynchronous socket read, upon completion invoke
+// the lambda function specified
+skt.async_read_some(asio::buffer(buffer->data(),buffer->size()),
+
+ // Retain lifetime of the i/o buffer until completion
+[buffer=std::move(buffer)](consterror_code&ec,size_tbytes){
+ // Handle the buffer read
+if(ec)
+ {
+ std::cerr<<"Buffer read failed with "<<ec<<std::endl;
+ return;
+ }
+ std::cout<<"Read "<<bytes<<" bytes into buffer"<<std::endl;
+
+ // buffer will be dynamically freed now
+});
+
One of the big value adds of the Coroutines TS is the ability to not have to write
+so much boilerplate if you have a Coroutines supporting compiler:
+
+
// As coroutines suspend the calling thread whilst an asynchronous
+// operation executes, we can use stack allocation instead of dynamic
+// allocation
+charbuffer[1024];
+
+ // Asynchronously read data, suspending this coroutine until completion,
+// returning the bytes of the data read into the result.
+try
+ {
+ // The use_awaitable completion token represents the current coroutine
+// (requires Coroutines TS)
+size_tbytesread=//
+co_awaitskt.async_read_some(asio::buffer(buffer),asio::use_awaitable);
+ std::cout<<"Read "<<bytesread<<" bytes into buffer"<<std::endl;
+ }
+ catch(conststd::system_error&e)
+ {
+ std::cerr<<"Buffer read failed with "<<e.what()<<std::endl;
+ }
+
The default ASIO implementation always throws exceptions on failure through
+its coroutine token transformation. The redirect_error
+token transformation recovers the option to use the error_code interface,
+but it suffers from the same drawbacks
+that make pure error codes unappealing in the synchronous case.
+
+
This recipe fixes that by making it possible for coroutinised
+i/o in ASIO to return a result<T>:
+
+
// Asynchronously read data, suspending this coroutine until completion,
+// returning the bytes of the data read into the result, or any failure.
+outcome::result<size_t,error_code>bytesread=//
+co_awaitskt.async_read_some(asio::buffer(buffer),as_result(asio::use_awaitable));
+
+ // Usage is exactly like ordinary Outcome. Note the lack of exception throw!
+if(bytesread.has_error())
+ {
+ std::cerr<<"Buffer read failed with "<<bytesread.error()<<std::endl;
+ return;
+ }
+ std::cout<<"Read "<<bytesread.value()<<" bytes into buffer"<<std::endl;
+
The below involves a lot of ASIO voodoo. NO SUPPORT WILL BE GIVEN HERE FOR THE ASIO
+CODE BELOW. Please raise any questions or problems that you have with how to implement
+this sort of stuff in ASIO
+on Stackoverflow #boost-asio.
+
+
+
+
+
The real world, production-level recipe can be found at the bottom of this page.
+You ought to use that in any real world use case.
+
+
It is however worth providing a walkthrough of a simplified edition of the real world
+recipe, as a lot of barely documented ASIO voodoo is involved. You should not
+use the code presented next in your own code, it is too simplified. But it should
+help you understand how the real implementation works.
+
+
Firstly we need to define some helper type sugar and a factory function for wrapping
+any arbitrary third party completion token with that type sugar:
+
+
namespacedetail
+{
+ // Type sugar for wrapping an external completion token
+template<classCompletionToken>structas_result_t
+ {
+ CompletionTokentoken;
+ };
+}// namespace detail
+
+// Factory function for wrapping a third party completion token with
+// our type sugar
+template<classCompletionToken>//
+inlineautoas_result(CompletionToken&&token)
+{
+ returndetail::as_result_t<std::decay_t<CompletionToken>>{std::forward<CompletionToken>(token)};
+};
+
Next we tell ASIO about a new completion token it ought to recognise by specialising
+async_result:
+
+
// Tell ASIO about a new kind of completion token, the kind returned
+// from our as_result() factory function. This implementation is
+// for functions with handlers void(error_code, T) only.
+template<classCompletionToken,classT>//
+structasio::async_result<detail::as_result_t<CompletionToken>,//
+void(error_code,T)>//
+
+{
+ // The result type we shall return
+usingresult_type=outcome::result<T,error_code>;
+ // The awaitable type to be returned by the initiating function,
+// the co_await of which will yield a result_type
+usingreturn_type=//
+typenameasio::async_result<CompletionToken,void(result_type)>//
+::return_type;
+
There are a couple tricky parts to understand. First of all, we want our
+async_result specialization to work, in particular, with the async_result for
+ASIO’s
+use_awaitable_t completion token.
+With this token, the async_result specialization takes the form with a static
+initiate method which defers initiation of the asynchronous operation until,
+for example,
+co_await is called on the returned awaitable. Thus, our async_result
+specialization will take the same form. With this in mind, we need only
+understand how our specialization will implement its initiate method. The trick
+is that it will pass the initiation work off to an async_result for the
+supplied completion token type with a completion handler which consumes result<T>.
+Our async_result is thus just a simple wrapper over this underlying
+async_result, but we inject a completion handler with the
+void(error_code, size_t) signature which constructs from that a result:
+
+
// Wrap a completion handler with void(error_code, T) converting
+// handler
+template<classHandler>
+ structcompletion_handler{
+ // Our completion handler spec
+voidoperator()(error_codeec,Tv)
+ {
+ // Call the underlying completion handler, whose
+// completion function is void(result_type)
+if(ec)
+ {
+ // Complete with a failed result
+_handler(result_type(outcome::failure(ec)));
+ return;
+ }
+ // Complete with a successful result
+_handler(result_type(outcome::success(v)));
+ }
+
+ Handler_handler;
+ };
+
+ // NOTE the initiate member function initiates the async operation,
+// and we want to defer to what would be the initiation of the
+// async_result whose handler signature is void(result_type).
+template<classInitiation,class... Args>
+ staticreturn_type
+ initiate(
+ Initiation&&init,
+ detail::as_result_t<CompletionToken>&&token,
+ Args&&...args)
+ {
+ // The async_initiate<CompletionToken, void(result_type)> helper
+// function will invoke the async initiation method of the
+// async_result<CompletionToken, void(result_type)>, as desired.
+// Instead of CompletionToken and void(result_type) we start with
+// detail::as_result_t<CompletionToken> and void(ec, T), so
+// the inputs need to be massaged then passed along.
+returnasio::async_initiate<CompletionToken,void(result_type)>(
+ // create a new initiation which wraps the provided init
+[init=std::forward<Initiation>(init)](
+ auto&&handler,auto&&...initArgs)mutable{
+ std::move(init)(
+ // we wrap the handler in the converting completion_handler from
+// above, and pass along the args
+completion_handler<std::decay_t<decltype(handler)>>{
+ std::forward<decltype(handler)>(handler)},
+ std::forward<decltype(initArgs)>(initArgs)...);
+ },
+ // the new initiation is called with the handler unwrapped from
+// the token, and the original initiation arguments.
+token.token,
+ std::forward<Args>(args)...);
+ }
+};
+
To use, simply wrap the third party completion token with as_result to cause
+ASIO to return from co_await a result instead of throwing exceptions on
+failure:
The real world production-level implementation below is a lot more complex than the
+above which has been deliberately simplified to aid exposition. The above
+should help you get up and running with the below, eventually.
+
+
One again I would like to remind you that Outcome is not the appropriate place
+to seek help with ASIO voodoo. Please ask on
+Stackoverflow #boost-asio.
This recipe targets Boost versions before 1.70, where coroutine support is based around
+the asio::experimental::this_coro::token completion token. For integration with Boost
+versions 1.70 and onward, see this recipe.
+
+
+
+
Use case
+
+
Boost.ASIO
+and standalone ASIO provide the
+async_result
+customisation point for adapting arbitrary third party libraries, such as Outcome, into ASIO.
+
+
Historically in ASIO you need to pass completion handler instances
+to the ASIO asynchronous i/o initiation functions. These get executed when the i/o
+completes.
+
+
// Dynamically allocate a buffer to read into. This must be move-only
+// so it can be attached to the completion handler, hence the unique_ptr.
+autobuffer=std::make_unique<std::vector<byte>>(1024);
+
+ // Begin an asynchronous socket read, upon completion invoke
+// the lambda function specified
+skt.async_read_some(asio::buffer(buffer->data(),buffer->size()),
+
+ // Retain lifetime of the i/o buffer until completion
+[buffer=std::move(buffer)](consterror_code&ec,size_tbytes){
+ // Handle the buffer read
+if(ec)
+ {
+ std::cerr<<"Buffer read failed with "<<ec<<std::endl;
+ return;
+ }
+ std::cout<<"Read "<<bytes<<" bytes into buffer"<<std::endl;
+
+ // buffer will be dynamically freed now
+});
+
One of the big value adds of the Coroutines TS is the ability to not have to write
+so much boilerplate if you have a Coroutines supporting compiler:
+
+
// As coroutines suspend the calling thread whilst an asynchronous
+// operation executes, we can use stack allocation instead of dynamic
+// allocation
+charbuffer[1024];
+
+ // Get an ASIO completion token for the current coroutine (requires
+// Coroutines TS)
+asio::experimental::await_tokentoken=//
+co_awaitasio::experimental::this_coro::token();
+
+ // Asynchronously read data, suspending this coroutine until completion,
+// returning the bytes of the data read into the result.
+try
+ {
+ size_tbytesread=//
+co_awaitskt.async_read_some(asio::buffer(buffer),token);
+ std::cout<<"Read "<<bytesread<<" bytes into buffer"<<std::endl;
+ }
+ catch(conststd::system_error&e)
+ {
+ std::cerr<<"Buffer read failed with "<<e.what()<<std::endl;
+ }
+
The default ASIO implementation always throws exceptions on failure through
+its coroutine token transformation. The redirect_error
+token transformation recovers the option to use the error_code interface,
+but it suffers from the same drawbacks
+that make pure error codes unappealing in the synchronous case.
+
+
This recipe fixes that by making it possible for coroutinised
+i/o in ASIO to return a result<T>:
+
+
// Asynchronously read data, suspending this coroutine until completion,
+// returning the bytes of the data read into the result, or any failure.
+outcome::result<size_t,error_code>bytesread=//
+co_awaitskt.async_read_some(asio::buffer(buffer),as_result(token));
+
+ // Usage is exactly like ordinary Outcome. Note the lack of exception throw!
+if(bytesread.has_error())
+ {
+ std::cerr<<"Buffer read failed with "<<bytesread.error()<<std::endl;
+ return;
+ }
+ std::cout<<"Read "<<bytesread.value()<<" bytes into buffer"<<std::endl;
+
The below involves a lot of ASIO voodoo. NO SUPPORT WILL BE GIVEN HERE FOR THE ASIO
+CODE BELOW. Please raise any questions or problems that you have with how to implement
+this sort of stuff in ASIO
+on Stackoverflow #boost-asio.
+
+
+
+
+
The real world, production-level recipe can be found at the bottom of this page.
+You ought to use that in any real world use case.
+
+
It is however worth providing a walkthrough of a simplified edition of the real world
+recipe, as a lot of barely documented ASIO voodoo is involved. You should not
+use the code presented next in your own code, it is too simplified. But it should
+help you understand how the real implementation works.
+
+
Firstly we need to define some helper type sugar and a factory function for wrapping
+any arbitrary third party completion token with that type sugar:
+
+
namespacedetail
+{
+ // Type sugar for wrapping an external completion token
+template<classCompletionToken>structas_result_t
+ {
+ CompletionTokentoken;
+ };
+}// namespace detail
+
+// Factory function for wrapping a third party completion token with
+// our type sugar
+template<classCompletionToken>//
+inlineautoas_result(CompletionToken&&token)
+{
+ returndetail::as_result_t<std::decay_t<CompletionToken>>{std::forward<CompletionToken>(token)};
+};
+
Next we tell ASIO about a new completion token it ought to recognise by specialising
+async_result:
+
+
// Tell ASIO about a new kind of completion token, the kind returned
+// from our as_result() factory function. This implementation is
+// for functions with handlers void(error_code, T) only.
+template<classCompletionToken,classT>//
+structasio::async_result<detail::as_result_t<CompletionToken>,//
+void(error_code,T)>//
+
+ // NOTE we subclass for an async result taking an outcome::result
+// as its completion handler. We will mangle the void(error_code, T)
+// completion handler into this completion handler below.
+:publicasio::async_result<CompletionToken,void(outcome::result<T,error_code>)>
+{
+ // The result type we shall return
+usingresult_type=outcome::result<T,error_code>;
+ using_base=asio::async_result<CompletionToken,void(result_type)>;
+ // The awaitable type to be returned by the initiating function,
+// the co_await of which will yield a result_type
+usingreturn_type=typename_base::return_type;
+
+ // Get what would be the completion handler for the async_result
+// whose completion handler is void(result_type)
+usingresult_type_completion_handler_type=//
+typename_base::completion_handler_type;
+
The tricky part to understand is that our async_result specialisation inherits
+from an async_result for the supplied completion token type with a completion
+handler which consumes a result<T>. Our async_result is actually therefore
+the base async_result, but we layer on top a completion_handler_type with
+the void(error_code, size_t) signature which constructs from that a result:
+
+
// Wrap that completion handler with void(error_code, T) converting
+// handler
+structcompletion_handler_type
+ {
+ // Pass through unwrapped completion token
+template<classU>
+ completion_handler_type(::detail::as_result_t<U>&&ch)
+ :_handler(std::forward<U>(ch.token))
+ {
+ }
+
+ // Our completion handler spec
+voidoperator()(error_codeec,Tv)
+ {
+ // Call the underlying completion handler, whose
+// completion function is void(result_type)
+if(ec)
+ {
+ // Complete with a failed result
+_handler(result_type(outcome::failure(ec)));
+ return;
+ }
+ // Complete with a successful result
+_handler(result_type(outcome::success(v)));
+ }
+
+ result_type_completion_handler_type_handler;
+ };
+
+ // Initialise base with the underlying completion handler
+async_result(completion_handler_type&h)
+ :_base(h._handler)
+ {
+ }
+
+ using_base::get;
+};
+
To use, simply wrap the third party completion token with as_result to cause
+ASIO to return from co_await a result instead of throwing exceptions on
+failure:
The real world production-level implementation below is a lot more complex than the
+above which has been deliberately simplified to aid exposition. The above
+should help you get up and running with the below, eventually.
+
+
One again I would like to remind you that Outcome is not the appropriate place
+to seek help with ASIO voodoo. Please ask on
+Stackoverflow #boost-asio.
Outcome’s BOOST_OUTCOME_TRY(var, expr)
+ operation is fully extensible
+to accept as input any foreign types.
+It already recognises types matching the
+ValueOrError<T, E>
+ concept, which is to say all types which have:
+
+
+
A public .has_value() member function which returns a bool.
+
In order of preference, a public .assume_value()/.value() member
+function.
+
In order of preference, a public .as_failure()/.assume_error()/.error()
+member function.
+
+
+
This should automatically handle inputs of std::expected<T, E>, and many others,
+including intermixing Boost.Outcome and standalone Outcome within the same
+translation unit.
+
+
BOOST_OUTCOME_TRY has the following free function customisation points:
Returns a suitable failure_type<EC, EP = void>
+ which
+is returned immediately to cause stack unwind. Ought to preserve rvalue
+semantics (i.e. if passed an rvalue, move the error state into the failure
+type).
+
Extracts a value type from the input for the `TRY` to set its variable.
+Ought to preserve rvalue semantics (i.e. if passed an rvalue, move the value).
+
+
+
New overloads of these to support additional input types must be injected into
+the BOOST_OUTCOME_V2_NAMESPACE namespace before the compiler parses the relevant
+BOOST_OUTCOME_TRY in order to be found. This is called ‘early binding’ in the two
+phase name lookup model in C++. This was chosen over ‘late binding’, where an
+BOOST_OUTCOME_TRY in a templated piece of code could look up overloads introduced after
+parsing the template containing the BOOST_OUTCOME_TRY, because it has much lower
+impact on build times, as binding is done once at the point of parse, instead
+of on every occasion at the point of instantiation. If you are careful to ensure
+that you inject the overloads which you need early in the parse of the
+translation unit, all will be well.
+
+
Let us work through an applied example.
+
+
+
+
A very foreign pseudo-Expected type
+
+
This is a paraphrase of a poorly written pseudo-Expected type which I once
+encountered in the production codebase of a large multinational. Lots
+of the code was already using it, and it was weird enough that it couldn’t
+be swapped out for something better easily.
Evaluate within a coroutine an expression which results in an understood type, assigning T to a variable called var if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.
Evaluate from within a coroutine an expression which results in an understood type, continuing execution if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.
Evaluate from within a coroutine an expression which results in an understood type, continuing execution if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.
Evaluate from within a coroutine an expression which results in an understood type, emitting the T if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.
Evaluate from within a coroutine an expression which results in an understood type, emitting the T if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.
Evaluate within a coroutine an expression which results in an understood type, assigning T to a variable called var if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.
Evaluate an expression which results in an understood type, assigning T to a variable called var if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.
Evaluate an expression which results in an understood type, continuing execution if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.
Evaluate an expression which results in an understood type, continuing execution if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.
Evaluate an expression which results in an understood type, emitting the T if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.
Evaluate an expression which results in an understood type, emitting the T if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.
Evaluate an expression which results in an understood type, assigning T to a variable called var if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.
Policy class defining that hard undefined behaviour should occur on incorrect narrow and wide value, error or exception observation. Inherits publicly from base.
Policy class defining that EP ought to be rethrown if possible, then the ADL discovered free function outcome_throw_as_system_error_with_payload() should be called on incorrect wide value observation. Inherits publicly from base. Can only be used with basic_outcome.
Policy class defining that the ADL discovered free function outcome_throw_as_system_error_with_payload() should be called on incorrect wide value observation. Inherits publicly from base. Can only be used with basic_result.
Policy class defining that the ADL discovered free function rethrow_exception() should be called on incorrect wide value observation. Inherits publicly from base. Can only be used with basic_outcome.
Policy class defining that the ADL discovered free function rethrow_exception() should be called on incorrect wide value observation. Inherits publicly from base. Can only be used with basic_result.
Policy class defining that a static assertion should occur upon compilation of the wide value, error or exception observation. Inherits publicly from base.
A type carrying one of (i) a successful T (ii) a disappointment EC (iii) a failure EP (iv) both a disappointment EC and a failure EP, with NoValuePolicy specifying what to do if one tries to read state which isn’t there.
A sum type carrying either a successful T, or a disappointment E, with NoValuePolicy specifying what to do if one tries to read state which isn’t there.
This is very similar to lazy<T>
+, except that execution of the eager<T>
+returning function begins immediately, and if the function never suspends during the
+course of its execution, no suspend-resume cycle occurs. Functions which return eager<T>
+are therefore suitable for tasks which may require suspension, but will often complete
+immediately.
+
+
atomic_eager<T> is like eager<T>, except that the setting of the coroutine result
+performs an atomic release, whilst the checking of whether the coroutine has finished
+is an atomic acquire.
+
+
Example of use (must be called from within a coroutinised function):
+
eager<int>func(intx)
+{
+ co_returnx+1;
+}
+...
+// Executes like a non-coroutine function i.e. r is immediately set to 6.
+intr=co_awaitfunc(5);
+
+
eager<T> has special semantics if T is a type capable of constructing from
+an exception_ptr or error_code – any exceptions thrown during the function’s body
+are sent via T, preferably via the error code route if error_from_exception(
+)
+successfully matches the exception throw. This means that a basic_result<T, E, NoValuePolicy>
+
+or basic_outcome<T, EC, EP, NoValuePolicy>
+ where one of its types is
+is compatible will have its .error() or .exception() set.
+
+
Note that eager<T> does not otherwise transport exception throws, and rethrows
+any exceptions thrown within the coroutine body through the coroutine machinery.
+This does not produce reliable consequences in current C++ compilers. You should
+therefore wrap the coroutine body in a try...catch if T is not able to transport
+exceptions on its own.
+
+
Requires: C++ coroutines to be available in your compiler.
This is very similar to eager<T>
+, except that execution of the
+lazy<T> returning function suspends immediately. Functions which return lazy<T>
+are therefore suitable for tasks which you need to instantiate right now, but whose
+execution will occur elsewhere e.g. in a separate kernel thread. Because of the very
+common use case of using worker threads to execute the body of lazily executed
+coroutines, most people will want to use atomic_lazy<T> instead of lazy<T>.
+
+
atomic_lazy<T> is like lazy<T>, except that the setting of the coroutine result
+performs an atomic release, whilst the checking of whether the coroutine has finished
+is an atomic acquire.
+
+
lazy<T> has similar semantics to std::lazy<T>, which is being standardised. See
+https://wg21.link/P1056Add lazy coroutine (coroutine task) type.
+
+
Example of use (must be called from within a coroutinised function):
+
lazy<int>func(intx)
+{
+ co_returnx+1;
+}
+...
+// Always suspends perhaps causing other coroutines to execute, then resumes.
+intr=co_awaitfunc(5);
+
+
lazy<T> has special semantics if T is a type capable of constructing from
+an exception_ptr or error_code – any exceptions thrown during the function’s body
+are sent via T, preferably via the error code route if error_from_exception(
+)
+successfully matches the exception throw. This means that a basic_result<T, E, NoValuePolicy>
+
+or basic_outcome<T, EC, EP, NoValuePolicy>
+ where one of its types is
+is compatible will have its .error() or .exception() set.
+
+
Note that lazy<T> does not otherwise transport exception throws, and rethrows
+any exceptions thrown within the coroutine body through the coroutine machinery.
+This does not produce reliable consequences in current C++ compilers. You should
+therefore wrap the coroutine body in a try...catch if T is not able to transport
+exceptions on its own.
+
+
Requires: C++ coroutines to be available in your compiler.
If on C++ 20 or the Concepts TS is enabled, a boolean concept matching types with a public .has_value() observer which returns bool, a public .value() observer function, and a public .error() observer function.
+
+
If without Concepts, a static constexpr bool which is true for types matching the same requirements, using a SFINAE based emulation.
+
+
This concept matches expected-like types such as
+ P0323 std::expected<T, E>
+, one of which is basic_result<T, E, NoValuePolicy>
+. Be aware it does not differentiate between value-or-error types and value-and-error types if they present the interface matched above.
If on C++ 20 or the Concepts TS is enabled, a boolean concept matching types with a public .has_value() observer which returns bool, and a public .value() observer function.
+
+
If without Concepts, a static constexpr bool which is true for types matching the same requirements, using a SFINAE based emulation.
+
+
This concept matches optional-like types such as
+std::optional<T>
+. Note it also matches
+ P0323 std::expected<T, E>
+, which also has an optional-like interface. You may thus wish to preferentially match ValueOrError<T, E>
+ for any given T.
A customisable converter of ValueOrError<T, E>
+ concept matching types. It must have the following form:
+
// `T` will be the destination basic_result or basic_outcome.
+// `U` will be the decayed form of the `ValueOrError<T, E>` concept matching input type.
+template<classT>structvalue_or_error<T,U>
+{
+ // False to indicate that this converter wants `basic_result`/`basic_outcome` to reject all other `basic_result`
+staticconstexprboolenable_result_inputs=false;
+ // False to indicate that this converter wants `basic_outcome` to reject all other `basic_outcome`
+staticconstexprboolenable_outcome_inputs=false;
+
+ // `X` will be the raw input form of `U`. It must return a `T`.
+template<classX>constexprToperator()(X&&v);
+};
+
+
Overridable: By template specialisation into the convert namespace.
+
+
Default: If decayed X is same as U, concept ValueOrError<U> matches, X::value_type is void or is explicitly constructible to T::value_type, and X::error_type is void or is explicitly constructible to T::error_type, then operator()(X &&) is made available.
+
+
operator()(X &&v) tests if v.has_value() is true, if so then a T with successful value is returned, else a T with unsuccessful value. If the input type was void, a default constructed value is used for either, else a move/copy construction from the source is performed.
Specialisation of outcome_throw_as_system_error_with_payload() for input types where boost::system::is_error_code_enum<BoostErrorCodeEnum> or boost::system::is_error_condition_enum<BoostErrorCodeEnum> is true.
Specialisation of outcome_throw_as_system_error_with_payload() for input types where std::is_error_code_enum<ErrorCodeEnum> or std::is_error_condition_enum<ErrorCodeEnum> is true.
This function saves writing boilerplate by rethrowing ep within a try
+block, with a long sequence of catch() handlers, one for every standard
+C++ exception type which has a near or exact equivalent code in
+std::errc
+.
+
+
If matched, ep is set to a default constructed
+std::exception_ptr
+,
+and a
+std::error_code
+ is constructed using the ADL discovered free
+function make_error_code() upon the std::errc enumeration value matching the
+thrown exception.
+
+
If not matched, ep is left intact, and the not_matched error code supplied
+is returned instead.
Returns appropriate type sugar for constructing an unsuccessful result or outcome, usually failure_type<EC, EP = void>
+ with a decayed T.
+
+
Two default overloads are provided, one taking a single parameter returning failure_type<std::decay_t<T>>, the other taking two parameters returning failure_type<std::decay_t<T>, std::decay_t<U>>. Both overloads perfectly forward their inputs.
+
+
Note that failure() overloads are permitted by Outcome to return something other than failure_type. For example, basic_result’s auto as_failure() const &
+ returns whatever type failure() returns, and BOOST_OUTCOME_TRY(var, expr)
+ by default returns for failure whatever .as_failure() returns. This can be useful to have BOOST_OUTCOME_TRY(...} propagate on failure something custom for some specific input basic_result or basic_outcome.
void hook_outcome_construction(T *, U &&) noexcept
+
One of the constructor hooks for basic_outcome<T, EC, EP, NoValuePolicy>
+, generally invoked by the implicit constructors of basic_outcome. See each constructor’s documentation to see which specific hook it invokes.
+
+
Overridable: By Argument Dependent Lookup.
+
+
Requires: Nothing.
+
+
Namespace: BOOST_OUTCOME_V2_NAMESPACE::hooks
+
+
Header: <boost/outcome/basic_outcome.hpp>
+
+
+
Last revised: January 30, 2019 at 16:16:10 UTC
+
+
+
+
+
+
diff --git a/doc/html/reference/functions/hooks/hook_outcome_construction2.html b/doc/html/reference/functions/hooks/hook_outcome_construction2.html
new file mode 100644
index 00000000..6a7fe0be
--- /dev/null
+++ b/doc/html/reference/functions/hooks/hook_outcome_construction2.html
@@ -0,0 +1,32 @@
+
+
+void hook_outcome_construction(T *, U &&, V &&) noexcept - Boost.Outcome documentation
+
+
+
+
+
+
+
+
+
+
void hook_outcome_construction(T *, U &&, V &&) noexcept
+
One of the constructor hooks for basic_outcome<T, EC, EP, NoValuePolicy>
+, generally invoked by the implicit constructors of basic_outcome which consume two arguments. See each constructor’s documentation to see which specific hook it invokes.
void hook_outcome_copy_construction(T *, U &&) noexcept
+
One of the constructor hooks for basic_outcome<T, EC, EP, NoValuePolicy>
+, generally invoked by the converting copy constructors of basic_outcome (NOT the standard copy constructor). See each constructor’s documentation to see which specific hook it invokes.
+
+
Overridable: By Argument Dependent Lookup.
+
+
Requires: Nothing.
+
+
Namespace: BOOST_OUTCOME_V2_NAMESPACE::hooks
+
+
Header: <boost/outcome/basic_outcome.hpp>
+
+
+
Last revised: January 30, 2019 at 16:16:10 UTC
+
+
+
+
+
+
diff --git a/doc/html/reference/functions/hooks/hook_outcome_copy_construction2.html b/doc/html/reference/functions/hooks/hook_outcome_copy_construction2.html
new file mode 100644
index 00000000..f72556a4
--- /dev/null
+++ b/doc/html/reference/functions/hooks/hook_outcome_copy_construction2.html
@@ -0,0 +1,32 @@
+
+
+void hook_outcome_copy_construction(T *, U &&, V &&) noexcept - Boost.Outcome documentation
+
+
+
+
+
+
+
+
+
+
void hook_outcome_copy_construction(T *, U &&, V &&) noexcept
+
One of the constructor hooks for basic_outcome<T, EC, EP, NoValuePolicy>
+, generally invoked by the converting copy constructors of basic_outcome (NOT the standard copy constructor) which consume two arguments. See each constructor’s documentation to see which specific hook it invokes.
One of the constructor hooks for basic_outcome<T, EC, EP, NoValuePolicy>
+, generally invoked by the in-place constructors of basic_outcome. See each constructor’s documentation to see which specific hook it invokes.
void hook_outcome_move_construction(T *, U &&) noexcept
+
One of the constructor hooks for basic_outcome<T, EC, EP, NoValuePolicy>
+, generally invoked by the converting move constructors of basic_outcome (NOT the standard move constructor). See each constructor’s documentation to see which specific hook it invokes.
+
+
Overridable: By Argument Dependent Lookup.
+
+
Requires: Nothing.
+
+
Namespace: BOOST_OUTCOME_V2_NAMESPACE::hooks
+
+
Header: <boost/outcome/basic_outcome.hpp>
+
+
+
Last revised: January 30, 2019 at 16:16:10 UTC
+
+
+
+
+
+
diff --git a/doc/html/reference/functions/hooks/hook_outcome_move_construction2.html b/doc/html/reference/functions/hooks/hook_outcome_move_construction2.html
new file mode 100644
index 00000000..8d1b2dbb
--- /dev/null
+++ b/doc/html/reference/functions/hooks/hook_outcome_move_construction2.html
@@ -0,0 +1,32 @@
+
+
+void hook_outcome_move_construction(T *, U &&, V &&) noexcept - Boost.Outcome documentation
+
+
+
+
+
+
+
+
+
+
void hook_outcome_move_construction(T *, U &&, V &&) noexcept
+
One of the constructor hooks for basic_outcome<T, EC, EP, NoValuePolicy>
+, generally invoked by the converting move constructors of basic_outcome (NOT the standard move constructor) which consume two arguments. See each constructor’s documentation to see which specific hook it invokes.
One of the constructor hooks for basic_result<T, E, NoValuePolicy>
+, generally invoked by the implicit constructors of basic_result. See each constructor’s documentation to see which specific hook it invokes.
void hook_result_copy_construction(T *, U &&) noexcept
+
One of the constructor hooks for basic_result<T, E, NoValuePolicy>
+, generally invoked by the converting copy constructors of basic_result (NOT the standard copy constructor). See each constructor’s documentation to see which specific hook it invokes.
One of the constructor hooks for basic_result<T, E, NoValuePolicy>
+, generally invoked by the in-place constructors of basic_result. See each constructor’s documentation to see which specific hook it invokes.
void hook_result_move_construction(T *, U &&) noexcept
+
One of the constructor hooks for basic_result<T, E, NoValuePolicy>
+, generally invoked by the converting move constructors of basic_result (NOT the standard move constructor). See each constructor’s documentation to see which specific hook it invokes.
void override_outcome_exception(basic_outcome<T, EC, EP, NoValuePolicy> *, U &&) noexcept
+
Overrides the exception to something other than what was constructed. You almost certainly never
+want to use this function. A much better way of overriding the exception returned is to create
+a custom no-value policy which lazily synthesises a custom exception object at the point of need.
+
+
The only reason that this function exists is because some people have very corner case needs
+where a custom no-value policy can’t be used, and where move-constructing a new outcome from
+an old outcome with the exception state replaced isn’t possible (e.g. when the types are
+non-copyable and non-moveable).
+
+
Unless you are in a situation where no other viable alternative exists, do not use this function.
Specialisation of outcome_throw_as_system_error_with_payload() for input types where boost::system::is_error_code_enum<BoostErrorCodeEnum> or boost::system::is_error_condition_enum<BoostErrorCodeEnum> is true.
Specialisation of outcome_throw_as_system_error_with_payload() for input types where std::is_error_code_enum<ErrorCodeEnum> or std::is_error_condition_enum<ErrorCodeEnum> is true.
auto basic_outcome_failure_exception_from_error(const EC &)
+
Synthesises an exception type from an error type, used by the exception_type failure() const noexcept
+
+observers. ADL discovered. Default
+overloads for this function are defined in Outcome for
+std::error_code
+
+and boost::system::error_code, these return std::make_exception_ptr(std::system_error(ec))
+and boost::copy_exception(boost::system::system_error(ec)) respectively.
A specialisation of outcome_throw_as_system_error_with_payload() for types where boost::system::is_error_code_enum<BoostErrorCodeEnum> or boost::system::is_error_condition_enum<BoostErrorCodeEnum> is true. This executes BOOST_OUTCOME_THROW_EXCEPTION(expr)
+ with a boost::system::system_error constructed from the result of the ADL discovered free function make_error_code(BoostErrorCodeEnum).
+
+
Overridable: Argument dependent lookup.
+
+
Requires: Either boost::system::is_error_code_enum<T> or boost::system::is_error_condition_enum<T> to be true for a decayed BoostErrorCodeEnum.
A specialisation of outcome_throw_as_system_error_with_payload() for boost::system::error_code. This executes BOOST_OUTCOME_THROW_EXCEPTION(expr)
+ with a boost::system::system_error constructed from the input.
A specialisation of outcome_throw_as_system_error_with_payload() for types where std::is_error_code_enum<ErrorCodeEnum> or std::is_error_condition_enum<ErrorCodeEnum> is true. This executes BOOST_OUTCOME_THROW_EXCEPTION(expr)
+ with a
+std::system_error
+ constructed from the result of the ADL discovered free function make_error_code(ErrorCodeEnum).
+
diff --git a/doc/html/reference/functions/strong_swap.html b/doc/html/reference/functions/strong_swap.html
new file mode 100644
index 00000000..cdbc5b5b
--- /dev/null
+++ b/doc/html/reference/functions/strong_swap.html
@@ -0,0 +1,34 @@
+
+
+void strong_swap(bool &all_good, T &a, T &b) - Boost.Outcome documentation
+
+
+
+
+
+
+
+
+
+
void strong_swap(bool &all_good, T &a, T &b)
+
The standard swap() function provides the weak guarantee i.e. that no resources are lost. This ADL discovered function provides the strong guarantee instead: that if any of these operations throw an exception (i) move construct to temporary (ii) move assign b to a (iii) move assign temporary to b, an attempt is made to restore the exact pre-swapped state upon entry, and if that recovery too fails, then the boolean all_good will be false during stack unwind from the exception throw, to indicate that state has been lost.
+
+
This function is used within basic_result::swap(basic_result &)
+ if, and only if, either or both of value_type or error_type have a throwing move constructor or move assignment. It permits you to customise the implementation of the strong guarantee swap in Outcome with a more efficient implementation.
+
+
Overridable: By Argument Dependent Lookup (ADL).
+
+
Requires: That T is both move constructible and move assignable.
Returns appropriate type sugar for constructing a successful result or outcome, usually success_type<T>
+ with a decayed T.
+
+
Two default overloads are provided, one taking a single parameter returning success_type<std::decay_t<T>> and perfectly forwarding the input. The other overload takes no parameters, and returns success_type<void>, which usually causes the construction of the receiving basic_result or basic_outcome’s with a default construction of their value type.
This default implementation returns whatever the .assume_value() or .value() member functions return, preferentially choosing the former where both are available.
+
+
Requires: That the expression std::declval<T>().assume_value() and/or std::declval<T>().value() is a valid expression.
This default implementation preferentially returns whatever the input type’s .as_failure() member function returns.
+basic_result and basic_outcome provide such a member function, see auto as_failure() const &
+.
+
+
If .as_failure() is not available, it will also match any .error() member function, which it wraps into a failure type sugar using failure(T &&, ...)
+.
+
+
Requires: That the expression std::declval<T>().as_failure() and/or std::declval<T>().error() is a valid expression.
This function saves writing boilerplate by throwing a standard library exception
+type equivalent to the supplied error code, with an optional custom message.
+
+
If the function returns, there is no standard library exception type equivalent
+to the supplied error code. The following codes produce the following exception
+throws:
+
+
+
EINVAL
+
std::invalid_argument
+
EDOM
+
std::domain_error
+
E2BIG
+
std::length_error
+
ERANGE
+
std::out_of_range
+
EOVERFLOW
+
std::overflow_error
+
ENOMEM
+
std::bad_alloc
+
+
+
The choice to refer to POSIX errno values above reflects the matching algorithm.
+As
+std::errc
+ exactly maps POSIX errno, on all platforms
+
+std::generic_category
+ error codes are matched by this function.
+Only on POSIX platforms only are
+std::system_category
+ error codes
+also matched by this function.
Evaluate within a coroutine an expression which results in an understood type, assigning T to a variable called var if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.
Evaluate from within a coroutine an expression which results in an understood type, continuing execution if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.
Evaluate from within a coroutine an expression which results in an understood type, continuing execution if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.
Evaluate from within a coroutine an expression which results in an understood type, emitting the T if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.
Evaluate from within a coroutine an expression which results in an understood type, emitting the T if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.
Evaluate within a coroutine an expression which results in an understood type, assigning T to a variable called var if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.
Evaluate an expression which results in an understood type, assigning T to a variable called var if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.
Evaluate an expression which results in an understood type, continuing execution if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.
Evaluate an expression which results in an understood type, continuing execution if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.
Evaluate an expression which results in an understood type, emitting the T if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.
Evaluate an expression which results in an understood type, emitting the T if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.
Evaluate an expression which results in an understood type, assigning T to a variable called var if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.
Evaluate within a coroutine an expression which results in a type matching the following customisation points, assigning T to a variable called var if successful, immediately returning try_operation_return_as(X)
+ from the calling function if unsuccessful:
If successful, an auto &&var is initialised to the expression result’s .assume_value() if available, else to its .value(). This binds a reference possibly to the T stored inside the bound result of the expression, but possibly also to a temporary emitted from the value observer function.
Evaluate within a coroutine an expression which results in a type matching the following customisation points, assigning T to a variable called var if successful, immediately returning try_operation_return_as(X)
+ from the calling function if unsuccessful:
Hints are given to the compiler that the expression will be unsuccessful. If you expect success, you should use BOOST_OUTCOME_CO_TRY(var, expr)
+ instead.
If successful, an auto &&var is initialised to the expression result’s .assume_value() if available, else to its .value(). This binds a reference possibly to the T stored inside the bound result of the expression, but possibly also to a temporary emitted from the value observer function.
Evaluate from within a coroutine an expression which results in a type matching the following customisation points, continuing execution if successful, immediately returning try_operation_return_as(X)
+ from the calling function if unsuccessful:
The difference between the BOOST_OUTCOME_CO_TRYV(expr) and BOOST_OUTCOME_CO_TRY(expr) editions is that the latter will set a variable if two or more macro arguments are present (see BOOST_OUTCOME_CO_TRY(var, expr)
+). The former requires the T to be void.
Definition: Firstly the expression’s temporary is bound to a uniquely named, stack allocated, auto &&. If that reference’s bound object’s try_operation_has_value() is false, immediately execute return try_operation_return_as(propagated unique reference);, propagating the rvalue/lvalue/etc-ness of the original expression.
Evaluate from within a coroutine an expression which results in a type matching the following customisation points, continuing execution if successful, immediately returning try_operation_return_as(X)
+ from the calling function if unsuccessful:
The difference between the BOOST_OUTCOME_CO_TRYV(expr) and BOOST_OUTCOME_CO_TRY(expr) editions is that the latter will set a variable if two or more macro arguments are present (see BOOST_OUTCOME_CO_TRY(var, expr)
+). The former requires the T to be void.
+
+
Hints are given to the compiler that the expression will be unsuccessful. If you expect success, you should use BOOST_OUTCOME_CO_TRYV(expr)
+ instead.
+
+
Overridable: Not overridable.
+
+
Definition: Firstly the expression’s temporary is bound to a uniquely named, stack allocated, auto &&. If that reference’s bound object’s try_operation_has_value() is false, immediately execute return try_operation_return_as(propagated unique reference);, propagating the rvalue/lvalue/etc-ness of the original expression.
Evaluate within a coroutine an expression which results in a type matching the following customisation points, emitting the T if successful, immediately returning try_operation_return_as(X)
+ from the calling function if unsuccessful:
This macro makes use of a proprietary extension in GCC and clang to emit the T from a successful expression. You can thus use BOOST_OUTCOME_CO_TRYX(expr) directly in expressions e.g. auto x = y + BOOST_OUTCOME_CO_TRYX(foo(z));.
+
+
Be aware there are compiler quirks in preserving the rvalue/lvalue/etc-ness of emitted T’s, specifically copy or move constructors may be called unexpectedly and/or copy elision not work as expected. If these prove to be problematic, use BOOST_OUTCOME_CO_TRY(var, expr)
+ instead.
Evaluate within a coroutine an expression which results in a type matching the following customisation points, emitting the T if successful, immediately returning try_operation_return_as(X)
+ from the calling function if unsuccessful:
This macro makes use of a proprietary extension in GCC and clang to emit the T from a successful expression. You can thus use BOOST_OUTCOME_CO_TRYX(expr) directly in expressions e.g. auto x = y + BOOST_OUTCOME_CO_TRYX(foo(z));.
+
+
Be aware there are compiler quirks in preserving the rvalue/lvalue/etc-ness of emitted T’s, specifically copy or move constructors may be called unexpectedly and/or copy elision not work as expected. If these prove to be problematic, use BOOST_OUTCOME_CO_TRY(var, expr)
+ instead.
If defined, disables the use of the <execinfo.h> header (or the win32 emulation).
+
+
Some embedded Linux toolchains do not define <execinfo.h>, thus disabling C++ exceptions on those toolchains produces a failure to find this file. Avoid that problem by defining this macro to disable stack backtrace support entirely.
+
+
Overridable: Define before inclusion.
+
+
Default: Defined if __ANDROID__ is defined, else undefined.
If set to 1, the <utility> header is included, and std::in_place_type_t<T>
+is aliased into BOOST_OUTCOME_V2_NAMESPACE::in_place_type_t<T> along with
+std::in_place_type<T>.
+
+
If set to 0, a local emulation is used.
+
+
Overridable: Define before inclusion.
+
+
Default: If the current compiler implements C++ 17 or later, if unset
+this macro is defaulted to 1, otherwise it is defaulted to 0.
Compiler-specific markup used to tell the compiler than the return value of a function should not be discarded without examining it.
+
+
Overridable: Define before inclusion.
+
+
Default: To [[nodiscard]] if on C++ 17 or higher, __attribute__((warn_unused_result)) if on clang, SAL _Must_inspect_result_ if on MSVC, otherwise nothing.
Compiler-specific markup used to mark throwable types as always having default ELF symbol visibility, without which it will be impossible to catch throws of such types across shared library boundaries on ELF only.
+
+
Overridable: Define before inclusion.
+
+
Default:
+
Standalone Outcome:
+
To __attribute__((visibility("default")) on GCC and clang when targeting ELF, otherwise nothing.
+
Overridable: All of the following macros are overridable, define before inclusion.
+
+
Header: <boost/outcome/config.hpp>
+
+
These macros expand into either the syntax for directly specifying constrained templates in C++ 20, or into a SFINAE based emulation for earlier C++ versions. Form of usage looks as follows:
+
BOOST_OUTCOME_TEMPLATE(classErrorCondEnum)
+ BOOST_OUTCOME_TREQUIRES(
+ // If this is a valid expression
+BOOST_OUTCOME_TEXPR(error_type(make_error_code(ErrorCondEnum()))),
+ // If this predicate is true
+BOOST_OUTCOME_TPRED(predicate::templateenable_error_condition_converting_constructor<ErrorCondEnum>)
+ // Any additional requirements follow here ...
+)
+ constexprbasic_result(ErrorCondEnum&&t,error_condition_converting_constructor_tag/*unused*/={});
+
+
Be aware that slightly different semantics occur for real C++ 20 constrained templates than for the SFINAE emulation.
+
+
+
BOOST_OUTCOME_TEMPLATE(template args ...)
+
+
Begins a constrained template declaration.
+
+
BOOST_OUTCOME_TREQUIRES(requirements ...)
+
+
Specifies the requirements for the constrained template to be available for selection by the compiler.
+
+
BOOST_OUTCOME_TEXPR(expression)
+
+
A requirement that the given expression is valid.
+
+
BOOST_OUTCOME_TPRED(boolean)
+
+
A requirement that the given constant time expression is true.
Compiler-specific markup used to mark variables as having thread local storage duration.
+
+
+
note
+
This isn’t used inside Outcome, but is used by its unit test suite.
+
+
+
+
+
Overridable: Define before inclusion.
+
+
Default: To thread_local if the compiler implements C++ 11 thread_local, else __thread for the one supported compiler (older Mac OS XCode) which does not.
To BOOST_OUTCOME_V2_NAMESPACE::detail::do_fatal_exit(#expr) which is a function which prints a useful error message including a stack backtrace (where available) to stderr before calling abort().
+
Evaluate an expression which results in a type matching the following customisation points, assigning T to a variable called var if successful, immediately returning try_operation_return_as(X)
+ from the calling function if unsuccessful:
If successful, an auto &&var is initialised to the expression result’s .assume_value() if available, else to its .value(). This binds a reference possibly to the T stored inside the bound result of the expression, but possibly also to a temporary emitted from the value observer function.
Evaluate an expression which results in a type matching the following customisation points, assigning T to a variable called var if successful, immediately returning try_operation_return_as(X)
+ from the calling function if unsuccessful:
Hints are given to the compiler that the expression will be unsuccessful. If you expect success, you should use BOOST_OUTCOME_TRY(var, expr)
+ instead.
If successful, an auto &&var is initialised to the expression result’s .assume_value() if available, else to its .value(). This binds a reference possibly to the T stored inside the bound result of the expression, but possibly also to a temporary emitted from the value observer function.
Evaluate an expression which results in a type matching the following customisation points, continuing execution if successful, immediately returning try_operation_return_as(X)
+ from the calling function if unsuccessful:
The difference between the BOOST_OUTCOME_TRYV(expr) and BOOST_OUTCOME_TRY(expr) editions is that the latter will set a variable if two or more macro arguments are present (see BOOST_OUTCOME_TRY(var, expr)
+). The former requires the T to be void.
+
+
Hints are given to the compiler that the expression will be successful. If you expect failure, you should use BOOST_OUTCOME_TRYV_FAILURE_LIKELY(expr)
+ instead.
+
+
Overridable: Not overridable.
+
+
Definition: Firstly the expression’s temporary is bound to a uniquely named, stack allocated, auto &&. If that reference’s bound object’s try_operation_has_value() is false, immediately execute return try_operation_return_as(propagated unique reference);, propagating the rvalue/lvalue/etc-ness of the original expression.
Evaluate an expression which results in a type matching the following customisation points, continuing execution if successful, immediately returning try_operation_return_as(X)
+ from the calling function if unsuccessful:
The difference between the BOOST_OUTCOME_TRYV(expr) and BOOST_OUTCOME_TRY(expr) editions is that the latter will set a variable if two or more macro arguments are present (see BOOST_OUTCOME_TRY(var, expr)
+). The former requires the T to be void.
+
+
Hints are given to the compiler that the expression will be unsuccessful. If you expect success, you should use BOOST_OUTCOME_TRYV(expr)
+ instead.
+
+
Overridable: Not overridable.
+
+
Definition: Firstly the expression’s temporary is bound to a uniquely named, stack allocated, auto &&. If that reference’s bound object’s try_operation_has_value() is false, immediately execute return try_operation_return_as(propagated unique reference);, propagating the rvalue/lvalue/etc-ness of the original expression.
Evaluate an expression which results in a type matching the following customisation points, emitting the T if successful, immediately returning try_operation_return_as(X)
+ from the calling function if unsuccessful:
Hints are given to the compiler that the expression will be successful. If you expect failure, you should use BOOST_OUTCOME_TRYX_FAILURE_LIKELY(expr)
+ instead.
+
+
Availability: GCC and clang only. Use #ifdef BOOST_OUTCOME_TRYX to determine if available.
This macro makes use of a proprietary extension in GCC and clang to emit the T from a successful expression. You can thus use BOOST_OUTCOME_TRYX(expr) directly in expressions e.g. auto x = y + BOOST_OUTCOME_TRYX(foo(z));.
+
+
Be aware there are compiler quirks in preserving the rvalue/lvalue/etc-ness of emitted T’s, specifically copy or move constructors may be called unexpectedly and/or copy elision not work as expected. If these prove to be problematic, use BOOST_OUTCOME_TRY(var, expr)
+ instead.
Evaluate an expression which results in a type matching the following customisation points, emitting the T if successful, immediately returning try_operation_return_as(X)
+ from the calling function if unsuccessful:
This macro makes use of a proprietary extension in GCC and clang to emit the T from a successful expression. You can thus use BOOST_OUTCOME_TRYX(expr) directly in expressions e.g. auto x = y + BOOST_OUTCOME_TRYX(foo(z));.
+
+
Be aware there are compiler quirks in preserving the rvalue/lvalue/etc-ness of emitted T’s, specifically copy or move constructors may be called unexpectedly and/or copy elision not work as expected. If these prove to be problematic, use BOOST_OUTCOME_TRY(var, expr)
+ instead.
Overridable: None of the following macros are overridable.
+
+
Header: <boost/outcome/config.hpp>
+
+
+
BOOST_OUTCOME_VERSION_MAJOR <number>
+
+
Major version for cmake and DLL version stamping.
+
+
BOOST_OUTCOME_VERSION_MINOR <number>
+
+
Minor version for cmake and DLL version stamping.
+
+
BOOST_OUTCOME_VERSION_PATCH <number>
+
+
Patch version for cmake and DLL version stamping.
+
+
BOOST_OUTCOME_VERSION_REVISION <number>
+
+
Revision version for cmake and DLL version stamping.
+
+
BOOST_OUTCOME_UNSTABLE_VERSION <number>
+
+
Defined between stable releases of Outcome. It means the inline namespace will be permuted per-commit to ensure ABI uniqueness such that multiple versions of Outcome in a single process space cannot collide.
+
+
BOOST_OUTCOME_V2 <tokens>
+
+
The namespace configuration of this Outcome v2. Consists of a sequence of bracketed tokens later fused by the preprocessor into namespace and C++ module names.
+
+
BOOST_OUTCOME_V2_NAMESPACE <identifier>
+
+
The Outcome namespace, which may be permuted per SHA commit. This is not fully qualified.
+
+
BOOST_OUTCOME_V2_NAMESPACE_BEGIN <keywords and identifiers>
+
+
Expands into the appropriate namespace markup to enter the Outcome v2 namespace.
+
+
BOOST_OUTCOME_V2_NAMESPACE_EXPORT_BEGIN <keywords and identifiers>
+
+
Expands into the appropriate namespace markup to enter the C++ module exported Outcome v2 namespace.
+
+
BOOST_OUTCOME_V2_NAMESPACE_END <keywords and identifiers>
+
+
Expands into the appropriate namespace markup to exit the Outcome v2 namespace.
Policy class defining that hard undefined behaviour should occur on incorrect narrow and wide value, error or exception observation. Inherits publicly from base.
Policy class defining that EP ought to be rethrown if possible, then the ADL discovered free function outcome_throw_as_system_error_with_payload() should be called on incorrect wide value observation. Inherits publicly from base. Can only be used with basic_outcome.
Policy class defining that the ADL discovered free function outcome_throw_as_system_error_with_payload() should be called on incorrect wide value observation. Inherits publicly from base. Can only be used with basic_result.
Policy class defining that the ADL discovered free function rethrow_exception() should be called on incorrect wide value observation. Inherits publicly from base. Can only be used with basic_outcome.
Policy class defining that the ADL discovered free function rethrow_exception() should be called on incorrect wide value observation. Inherits publicly from base. Can only be used with basic_result.
Policy class defining that a static assertion should occur upon compilation of the wide value, error or exception observation. Inherits publicly from base.
Sets whether the implementation’s error code has a domain or category matching that of POSIX errno by setting or clearing the relevant bit in the flags. Constexpr where possible.
This is a special function which does compiler-specific stuff to tell the compiler that this function can never, ever, ever be executed. The compiler’s optimiser will hard assume that this function can never be executed, and will prune the possibility of it being executed completely. Generally this means that the code path stops dead, and if execution does proceed down this path, it will run off the end of a branch which doesn’t go anywhere. Your program will have lost known state, and usually it will trash memory and registers and crash.
+
+
This may seem highly undesirable. However, it also means that the optimiser can optimise more strongly, and so long as you never actually do execute this branch, you do get higher quality code generation.
+
+
If the NDEBUG macro is not defined, an assert(false) is present. This will cause attempts to execute this function to fail in a very obvious way, but it also generates runtime code to trigger the obvious failure.
+
+
If the NDEBUG macro is defined, and the program is compiled with the undefined behaviour sanitiser, attempts to execute this function will trigger an undefined behaviour sanitiser action.
+
+
Requires: Always available.
+
+
Complexity: Zero runtime overhead if NDEBUG is defined, guaranteed. If this function returns, your program is now in hard loss of known program state. Usually, but not always, it will crash at some point later. Rarely it will corrupt registers and memory, and keep going.
Policy class defining that on incorrect wide value observation, EP ought to be rethrown if possible, then the ADL discovered free function outcome_throw_as_system_error_with_payload(impl.assume_error()) should be called. Some precanned overloads of that function are listed here.
Policy class defining that the ADL discovered free function outcome_throw_as_system_error_with_payload(impl.assume_error()) should be called on incorrect wide value observation. Some precanned overloads of that function are listed here.
Note: This policy class specialisation can only be used with basic_outcome, not basic_result. Use exception_ptr_rethrow<T, EC, void>
+ with basic_result.
+
+
Policy class defining that the ADL discovered free function rethrow_exception(impl.assume_exception()) if possible, followed by rethrow_exception(impl.assume_error()) should be called on incorrect wide value observation. Generally this will ADL discover
+std::rethrow_exception()
+ or boost::rethrow_exception() depending on the EC type.
Note: This policy class specialisation can only be used with basic_result, not basic_outcome. Use exception_ptr_rethrow<T, EC, EP>
+ with basic_outcome.
+
+
Policy class defining that the ADL discovered free function rethrow_exception(impl.assume_error()) should be called on incorrect wide value observation. Generally this will ADL discover
+std::rethrow_exception()
+ or boost::rethrow_exception() depending on the EC type.
Upon attempting to compile the wide observer policy functions, the following static assertion occurs which fails the build:
+
+
+
Attempt to wide observe value, error or exception for a result/outcome given an EC or E type which is not void, and for whom trait::has_error_code_v, trait::has_exception_ptr_v, and trait::has_exception_ptr_v are all false. Please specify a NoValuePolicy to tell result/outcome what to do, or else use a more specific convenience type alias such as unchecked to indicate you want the wide observers to be narrow, or checked to indicate you always want an exception throw etc.
+
+
+
This failure to compile was introduced after the Boost peer review of v2.0 of Outcome due to feedback that users were too often surprised by the default selection of the all_narrow
+ policy if the types were unrecognised. It was felt this introduced too much danger in the default configuration, so to ensure that existing code based on Outcome broke very loudly after an upgrade, the above very verbose static assertion was implemented.
Policy class defining that bad_result_access_with<EC>
+ should be thrown on incorrect wide value observation. The primary purpose of this policy is to enable standing in for
+ P0323 std::expected<T, E>
+ which throws a bad_expected_access<E> on incorrect wide value observation. This is why it is only ever EC which is thrown with bad_result_access_with<EC> on value observation only, and only when there is an error available.
+
+
If used in basic_outcome, and the outcome is exceptioned and so no error is available, incorrect wide value observation performs instead:
::value is true if an error code can be constructed from a T e.g. if there exists an ADL discovered free function make_error_code(T).
+::type is the type that would result if ::value is true, else void.
+
+
Overridable: By template specialisation into the trait namespace.
+
+
Default: True if T is an error code, else to metaprogramming which performs the ADL discovery of make_error_code(T). Note that the STL defines multiple overloads of an ADL discovered free function
+std::make_error_code(T)
+ for its error enumerations, as does Boost.System for the Boost error enumerations. Thus this trait will pick up those free functions for those error types.
A customisable integral constant type true for E types which are to receive
+error throwing no-value policies. Special weakened implicit construction enable
+is available for integral T types when combined with E types in this
+whitelist – this permits boost_result<int, boost::system::errc::errc_t to
+retain its implicit constructors, despite the fact that errc_t as a C enum
+has an implicit conversion to int.
+
+
Overridable: By template specialisation into the trait namespace.
+
+
Default: False. Specialisations to true exist for:
::value is true if an exception ptr can be constructed from a T e.g. if there exists an ADL discovered free function make_exception_ptr(T).
+::type is the type that would result if ::value is true, else void.
+
+
Overridable: By template specialisation into the trait namespace.
+
+
Default: True if T is an exception ptr, else to metaprogramming which performs the ADL discovery of make_exception_ptr(T). Note that the STL defines an ADL discovered free function
+std::make_exception_ptr(T)
+. Thus this trait will pick up that free function.
A type carrying one of (i) a successful T (ii) a disappointment EC (iii) a failure EP (iv) both a disappointment EC and a failure EP, with NoValuePolicy specifying what to do if one tries to read state which isn’t there.
Disabling catchall constructor used to give useful diagnostic error when trying to use non-inplace constructors when predicate::constructors_enabled is false.
Disabling implicit constructor used to give useful diagnostic error when trying to use implicit constructors when predicate::implicit_constructors_enabled is false.
Implicit value_type constructor. Available if predicate::enable_value_converting_constructor<R> is true. Constexpr, triviality and noexcept propagating.
Implicit error_type constructor. Available if predicate::enable_error_converting_constructor<S> is true. Constexpr, triviality and noexcept propagating.
Implicit error_type from ErrorCondEnum constructor. Available if predicate::enable_error_condition_converting_constructor<ErrorCondEnum> is true. Constexpr, triviality and noexcept propagating.
Implicit exception_type constructor. Available if predicate::enable_exception_converting_constructor<P> is true. Constexpr, triviality and noexcept propagating.
Implicit error_type + exception_type constructor. Available if predicate::enable_error_exception_converting_constructor<S, P> is true. Constexpr, triviality and noexcept propagating.
Explicit converting constructor from ValueOrError<T, E> concept matching types. Available if convert::value_or_error<> permits it. Constexpr, triviality and noexcept propagating.
Explicit converting copy constructor from compatible basic_outcome. Available if predicate::enable_compatible_conversion<A, B, C, D> is true. Constexpr, triviality and noexcept propagating.
Explicit converting move constructor from compatible basic_outcome. Available if predicate::enable_compatible_conversion<A, B, C, D> is true. Constexpr, triviality and noexcept propagating.
Explicit converting copy constructor from compatible basic_result. Available if predicate::enable_compatible_conversion<A, B, void, C> is true. Constexpr, triviality and noexcept propagating.
Explicit converting move constructor from compatible basic_result. Available if predicate::enable_compatible_conversion<A, B, void, C> is true. Constexpr, triviality and noexcept propagating.
Explicit converting copy constructor from compatible basic_result. Available if predicate::enable_make_error_code_compatible_conversion<A, B, void, C> is true. Constexpr, triviality and noexcept propagating.
Explicit converting move constructor from compatible basic_result. Available if predicate::enable_make_error_code_compatible_conversion<A, B, void, C> is true. Constexpr, triviality and noexcept propagating.
Explicit inplace value constructor. Available if predicate::enable_inplace_value_constructor<Args ...> is true. Constexpr, triviality and noexcept propagating.
Explicit inplace value constructor. Available if predicate::enable_inplace_value_constructor<std::initializer_list<U>, Args ...> is true. Constexpr, triviality and noexcept propagating.
Explicit inplace error constructor. Available if predicate::enable_inplace_error_constructor<Args ...> is true. Constexpr, triviality and noexcept propagating.
Explicit inplace error constructor. Available if predicate::enable_inplace_error_constructor<std::initializer_list<U>, Args ...> is true. Constexpr, triviality and noexcept propagating.
Explicit inplace exception constructor. Available if predicate::enable_inplace_exception_constructor<Args ...> is true. Constexpr, triviality and noexcept propagating.
Explicit inplace exception constructor. Available if predicate::enable_inplace_exception_constructor<std::initializer_list<U>, Args ...> is true. Constexpr, triviality and noexcept propagating.
Implicit inplace value or error or exception constructor. Available if predicate::enable_inplace_value_error_exception_constructor<A1, A2, Args ...> is true. Constexpr, triviality and noexcept propagating.
Implicit value-from-success-type-sugar copy constructor. Available if predicate::enable_compatible_conversion<T, void, void> is true, or T is void. Constexpr, triviality and noexcept propagating.
Implicit value-from-success-type-sugar move constructor. Available if predicate::enable_compatible_conversion<T, void, void> is true, or T is void. Constexpr, triviality and noexcept propagating.
Implicit error-from-failure-type-sugar copy constructor. Available if predicate::enable_compatible_conversion<void, EC, void, void> is true. Constexpr, triviality and noexcept propagating.
Implicit error-from-failure-type-sugar move constructor. Available if predicate::enable_compatible_conversion<void, EC, void, void> is true. Constexpr, triviality and noexcept propagating.
Implicit error-from-failure-type-sugar copy constructor. Available if predicate::enable_make_error_code_compatible_conversion<void, EC, void, void> is true. Constexpr, triviality and noexcept propagating.
Implicit error-from-failure-type-sugar move constructor. Available if predicate::enable_make_error_code_compatible_conversion<void, EC, void, void> is true. Constexpr, triviality and noexcept propagating.
Implicit exception-from-failure-type-sugar copy constructor. Available if predicate::enable_compatible_conversion<void, void, EP, void> is true. Constexpr, triviality and noexcept propagating.
Implicit exception-from-failure-type-sugar move constructor. Available if predicate::enable_compatible_conversion<void, void, EP, void> is true. Constexpr, triviality and noexcept propagating.
Implicit error-and-exception-from-failure-type-sugar copy constructor. Available if predicate::enable_compatible_conversion<void, EC, EP, void> is true. Constexpr, triviality and noexcept propagating.
Implicit error-and-exception-from-failure-type-sugar move constructor. Available if predicate::enable_compatible_conversion<void, EC, EP, void> is true. Constexpr, triviality and noexcept propagating.
Synthesising observer of the stored exception or error. Available if the traits is_error_code_available<T> and is_exception_ptr_available<T> are both true. Never throws.
A sum type carrying either a successful T, or a disappointment E, with NoValuePolicy specifying what to do if one tries to read state which isn’t there.
Disabling catchall constructor used to give useful diagnostic error when trying to use non-inplace constructors when predicate::constructors_enabled is false.
Disabling implicit constructor used to give useful diagnostic error when trying to use implicit constructors when predicate::implicit_constructors_enabled is false.
Implicit value_type constructor. Available if predicate::enable_value_converting_constructor<R> is true. Constexpr, triviality and noexcept propagating.
Implicit error_type constructor. Available if predicate::enable_error_converting_constructor<S> is true. Constexpr, triviality and noexcept propagating.
Implicit error_type from ErrorCondEnum constructor. Available if predicate::enable_error_condition_converting_constructor<ErrorCondEnum> is true. Constexpr, triviality and noexcept propagating.
Explicit converting constructor from ValueOrError<T, E> concept matching types. Available if convert::value_or_error<> permits it. Constexpr, triviality and noexcept propagating.
Explicit converting copy constructor from compatible basic_result. Available if predicate::enable_compatible_conversion<R, S, P> is true. Constexpr, triviality and noexcept propagating.
Explicit converting move constructor from compatible basic_result. Available if predicate::enable_compatible_conversion<R, S, P> is true. Constexpr, triviality and noexcept propagating.
Explicit converting copy constructor from compatible basic_result. Available if predicate::enable_make_error_code_compatible_conversion<R, S, P> is true. Constexpr, triviality and noexcept propagating.
Explicit converting move constructor from compatible basic_result. Available if predicate::enable_make_error_code_compatible_conversion<R, S, P> is true. Constexpr, triviality and noexcept propagating.
Explicit converting copy constructor from compatible basic_result. Available if predicate::enable_make_exception_ptr_compatible_conversion<R, S, P> is true. Constexpr, triviality and noexcept propagating.
Explicit converting move constructor from compatible basic_result. Available if predicate::enable_make_exception_ptr_compatible_conversion<R, S, P> is true. Constexpr, triviality and noexcept propagating.
Explicit inplace value constructor. Available if predicate::enable_inplace_value_constructor<Args ...> is true. Constexpr, triviality and noexcept propagating.
Explicit inplace value constructor. Available if predicate::enable_inplace_value_constructor<std::initializer_list<U>, Args ...> is true. Constexpr, triviality and noexcept propagating.
Explicit inplace error constructor. Available if predicate::enable_inplace_error_constructor<Args ...> is true. Constexpr, triviality and noexcept propagating.
Explicit inplace error constructor. Available if predicate::enable_inplace_error_constructor<std::initializer_list<U>, Args ...> is true. Constexpr, triviality and noexcept propagating.
Implicit inplace value or error constructor. Available if predicate::enable_inplace_value_error_constructor<A1, A2, Args ...> is true. Constexpr, triviality and noexcept propagating.
Implicit value-from-success-type-sugar copy constructor. Available if predicate::enable_compatible_conversion<T, void, void> is true, or T is void. Constexpr, triviality and noexcept propagating.
Implicit value-from-success-type-sugar move constructor. Available if predicate::enable_compatible_conversion<T, void, void> is true, or T is void. Constexpr, triviality and noexcept propagating.
Implicit error-from-failure-type-sugar copy constructor. Available if predicate::enable_compatible_conversion<void, T, void> is true, or T is void. Constexpr, triviality and noexcept propagating.
Implicit error-from-failure-type-sugar move constructor. Available if predicate::enable_compatible_conversion<void, T, void> is true, or T is void. Constexpr, triviality and noexcept propagating.
Implicit error-from-failure-type-sugar copy constructor. Available if predicate::enable_make_error_code_compatible_conversion<void, T, void> is true, or T is void. Constexpr, triviality and noexcept propagating.
Implicit error-from-failure-type-sugar move constructor. Available if predicate::enable_make_error_code_compatible_conversion<void, T, void> is true, or T is void. Constexpr, triviality and noexcept propagating.
Implicit error-from-failure-type-sugar copy constructor. Available if predicate::enable_make_exception_ptr_compatible_conversion<void, T, void> is true, or T is void. Constexpr, triviality and noexcept propagating.
Implicit error-from-failure-type-sugar move constructor. Available if predicate::enable_make_exception_ptr_compatible_conversion<void, T, void> is true, or T is void. Constexpr, triviality and noexcept propagating.
Exception type publicly inheriting from bad_result_access
+, and thus also
+std::logic_error
+, indicating an incorrect observation of value occurred. The error value at the time of the exception throw is moved or copied into this type, and is available using the .error() observer which comes in lvalue ref, const lvalue ref, rvalue ref, and const rvalue ref overloads.
+
+
The primary purpose of this exception type is to enable standing in for
+ P0323 std::expected<T, E>
+’s bad_expected_access<E> which is thrown on incorrect wide value observation. This is why it is only ever EC which is thrown with bad_result_access_with<EC> on value observation only, and only when there is an error available. See the throw_bad_result_access<EC>
+ policy for more information.
A type carrying one of (i) a successful T (ii) a disappointment EC (iii) a failure EP (iv) both a disappointment EC and a failure EP, with NoValuePolicy specifying what to do if one tries to read state which isn’t there. Any one, two, or all of T, EC and EP can be void to indicate no value for that state is present. Detectable using is_basic_outcome<T>
+.
+
+
Requires: Concept requirements if C++ 20, else static asserted:
If C++ exceptions disabled and BOOST_OUTCOME_DISABLE_EXECINFO undefined only (used to print stack backtraces on “exception throw”):
+
+
+
<sal.h> (Windows only)
+
<stddef.h> (Windows only)
+
<string.h> (Windows only)
+
<execinfo.h> (POSIX only)
+
+
<cstdio>
+
<cstdlib>
+
<cassert>
+
+
+
This very light weight set of inclusion dependencies makes basic outcome suitable for use in global header files of very large C++ codebases.
+
+
Design rationale
+
+
basic_outcome extends basic_result<T, E, NoValuePolicy>
+ with a third state to transport,
+conventionally (but not necessarily) some sort of “abort” or “exceptional” state which a function can
+return to indicate that not only did the operation fail, but it did so catastrophically i.e. please
+abort any attempt to retry the operation.
+
+
A perfect alternative is to throw a C++ exception for the abort code path, and indeed most programs
+ought to do exactly that instead of using basic_outcome. However there are a number of use cases
+where choosing basic_outcome shines:
+
+
+
Where C++ exceptions or RTTI is not available, but the ability to fail catastrophically without
+terminating the program is important.
+
Where deterministic behaviour is required even in the catastrophic failure situation.
+
In unit test suites of code using Outcome it is extremely convenient to accumulate test failures
+into a basic_outcome 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.
+
Where a function is “dual use deterministic” i.e. it can be used deterministically, in which case
+one switches control flow based on .error(), or it can be used non-deterministically by throwing
+an exception perhaps carrying a custom payload.
+
+
+
Public member type aliases
+
+
+
value_type is T.
+
error_type is EC.
+
exception_type is EP.
+
value_type_if_enabled is T if construction from T is available, else it is a usefully named unusable internal type.
+
error_type_if_enabled is EC if construction from EC is available, else it is a usefully named unusable internal type.
+
exception_type_if_enabled is EP if construction from EP is available, else it is a usefully named unusable internal type.
+
rebind<A, B = EC, C = EP, D = NoValuePolicy> is basic_outcome<A, B, C, D>.
+
+
+
Protected member predicate booleans
+
+
+
predicate::constructors_enabled is constexpr boolean true if:
+
+
+
Decayed value_type and decayed error_type are not the same type, or both are void.
+
Decayed value_type and decayed exception_type are not the same type, or both are void.
+
Decayed error_type and decayed exception_type are not the same type, or both are void.
+
+
+
predicate::implicit_constructors_enabled is constexpr boolean true if:
+
+
+
predicate::constructors_enabled is true.
+
Trait is_error_type<E>
+ is not true for both decayed value_type and decayed error_type at the same time.
+
value_type is not implicitly constructible from error_type and error_type is not implicitly constructible from value_type. OR trait is_error_type<E>
+ is true for decayed error_type and error_type is not implicitly constructible from value_type and value_type is an integral type.
+
value_type is not implicitly constructible from exception_type.
+
error_type is not implicitly constructible from exception_type.
+
exception_type is not implicitly constructible from value_type.
+
exception_type is not implicitly constructible from error_type.
+
+
+
predicate::enable_value_converting_constructor<A> is constexpr boolean true if:
value_type is implicitly constructible from A and error_type is not implicitly constructible from A. OR value_type is the exact same type as decayed A and value_type is implicitly constructible from A.
+
exception_type is not implicitly constructible from A.
+
+
+
predicate::enable_error_converting_constructor<A> is constexpr boolean true if:
value_type is not implicitly constructible from A and error_type is implicitly constructible from A. OR error_type is the exact same type as decayed A and error_type is implicitly constructible from A.
+
exception_type is not implicitly constructible from A.
+
+
+
predicate::enable_error_condition_converting_constructor<ErrorCondEnum> is constexpr boolean true if:
+
+
+
predicate::constructors_enabled is true.
+
Decayed ErrorCondEnum is not this basic_outcome type.
exception_type is not implicitly constructible from ErrorCondEnum.
+
+
+
predicate::enable_exception_converting_constructor<A> is constexpr boolean true if:
+
+
+
predicate::constructors_enabled is true.
+
Decayed A is not this basic_outcome type.
+
predicate::implicit_constructors_enabled is true.
+
Decayed A is not an in_place_type_t.
+
value_type is not implicitly constructible from A.
+
error_type is not implicitly constructible from A.
+
exception_type is implicitly constructible from A.
+
+
+
predicate::enable_error_exception_converting_constructor<A, B> is constexpr boolean true if:
+
+
+
predicate::constructors_enabled is true.
+
Decayed A is not this basic_outcome type.
+
predicate::implicit_constructors_enabled is true.
+
Decayed A is not an in_place_type_t.
+
value_type is not implicitly constructible from A.
+
error_type is implicitly constructible from A.
+
value_type is not implicitly constructible from B.
+
exception_type is implicitly constructible from B.
+
+
+
predicate::enable_compatible_conversion<A, B, C, D> is constexpr boolean true if:
+
+
+
predicate::constructors_enabled is true.
+
basic_outcome<A, B, C, D> is not this basic_outcome type.
+
A is void OR value_type is explicitly constructible from A.
+
B is void OR error_type is explicitly constructible from B.
+
C is void OR exception_type is explicitly constructible from C.
+
+
+
predicate::enable_make_error_code_compatible_conversion<A, B, C, D> is constexpr boolean true if:
+
+
+
predicate::constructors_enabled is true.
+
basic_outcome<A, B, C, D> is not this basic_outcome type.
+
Trait "/home/travis/build/ned14/boost-outcome/doc/src/content/reference/types/basic_outcome/_index.md:138:14": API reference page for 'is_error_code_available<E>' not found, please use an identifier wholly contained in a page title
+ API NOT FOUND IN DOCS is_error_code_available<E>
+ is true for decayed error_type.
+
predicate::enable_compatible_conversion<A, B, C, D> is not true.
+
A is void OR value_type is explicitly constructible from A.
+
error_type is explicitly constructible from make_error_code(B).
+
C is void OR exception_type is explicitly constructible from C.
+
+
+
predicate::enable_inplace_value_constructor<Args...> is constexpr boolean true if:
+
+
+
predicate::constructors_enabled is true.
+
value_type is void OR value_type is explicitly constructible from Args....
+
+
+
predicate::enable_inplace_error_constructor<Args...> is constexpr boolean true if:
+
+
+
predicate::constructors_enabled is true.
+
error_type is void OR error_type is explicitly constructible from Args....
+
+
+
predicate::enable_inplace_exception_constructor<Args...> is constexpr boolean true if:
+
+
+
predicate::constructors_enabled is true.
+
exception_type is void OR exception_type is explicitly constructible from Args....
+
+
+
predicate::enable_inplace_value_error_exception_constructor<Args...> is constexpr boolean true if:
+
+
+
predicate::constructors_enabled is true.
+
predicate::implicit_constructors_enabled is true.
+
Exactly one of value_type is explicitly constructible from Args..., or error_type is explicitly constructible from Args..., or exception_type is explicitly constructible
+from Args....
DefaultConstructible, always deleted to force user to choose valued or errored or excepted for every outcome instanced.
+
MoveConstructible, if all of value_type, error_type and exception_type implement move constructors.
+
CopyConstructible, if all of value_type, error_type and exception_type implement copy constructors.
+
MoveAssignable, if all of value_type, error_type and exception_type implement move constructors and move assignment.
+
CopyAssignable, if all of value_type, error_type and exception_type implement copy constructors and copy assignment.
+
Destructible.
+
TriviallyCopyable, if all of value_type, error_type and exception_type are trivially copyable.
+
TrivialType, if all of value_type, error_type and exception_type are trivial types.
+
LiteralType, if all of value_type, error_type and exception_type are literal types.
+
+
StandardLayoutType. It is implementation defined if basic_outcome can be used by C.
+However all of the three major compilers MSVC, GCC and clang implement C layout of basic_outcome as follows:
If you choose standard layout value_type, error_type and exception_type, basic_outcome
+works fine from C on MSVC, GCC and clang.
+
+
EqualityComparable, if all of value_type, error_type and exception_type implement equality comparisons with one another.
+
+
LessThanComparable, not implemented due to availability of implicit conversions from value_type, error_type and exception_type, this can cause major surprise (i.e. hard to diagnose bugs), so we don’t implement these at all.
+~ Swappable
+
+
Hash, not implemented as a generic implementation of a unique hash for non-valued items which are unequal would require a dependency on RTTI being enabled.
+
+
+
Thus basic_outcome meets the Regular concept if all of value_type, error_type and exception_type are Regular, except for the lack of a default constructor. Often where one needs a default constructor, wrapping basic_outcome into
+std::optional<T>
+ will suffice.
Disabling catchall constructor used to give useful diagnostic error when trying to use non-inplace constructors when predicate::constructors_enabled is false.
Disabling implicit constructor used to give useful diagnostic error when trying to use implicit constructors when predicate::implicit_constructors_enabled is false.
+
+
Copy and move constructors and assignment, and destructor
Implicit value_type constructor. Available if predicate::enable_value_converting_constructor<R> is true. Constexpr, triviality and noexcept propagating.
Implicit error_type constructor. Available if predicate::enable_error_converting_constructor<S> is true. Constexpr, triviality and noexcept propagating.
Implicit error_type from ErrorCondEnum constructor. Available if predicate::enable_error_condition_converting_constructor<ErrorCondEnum> is true. Constexpr, triviality and noexcept propagating.
Implicit exception_type constructor. Available if predicate::enable_exception_converting_constructor<P> is true. Constexpr, triviality and noexcept propagating.
Implicit error_type + exception_type constructor. Available if predicate::enable_error_exception_converting_constructor<S, P> is true. Constexpr, triviality and noexcept propagating.
Explicit converting constructor from ValueOrError<T, E> concept matching types. Available if convert::value_or_error<> permits it. Constexpr, triviality and noexcept propagating.
Explicit converting copy constructor from compatible basic_outcome. Available if predicate::enable_compatible_conversion<A, B, C, D> is true. Constexpr, triviality and noexcept propagating.
Explicit converting move constructor from compatible basic_outcome. Available if predicate::enable_compatible_conversion<A, B, C, D> is true. Constexpr, triviality and noexcept propagating.
Explicit converting copy constructor from compatible basic_result. Available if predicate::enable_compatible_conversion<A, B, void, C> is true. Constexpr, triviality and noexcept propagating.
Explicit converting move constructor from compatible basic_result. Available if predicate::enable_compatible_conversion<A, B, void, C> is true. Constexpr, triviality and noexcept propagating.
Explicit converting copy constructor from compatible basic_result. Available if predicate::enable_make_error_code_compatible_conversion<A, B, void, C> is true. Constexpr, triviality and noexcept propagating.
Explicit converting move constructor from compatible basic_result. Available if predicate::enable_make_error_code_compatible_conversion<A, B, void, C> is true. Constexpr, triviality and noexcept propagating.
Explicit inplace value constructor. Available if predicate::enable_inplace_value_constructor<Args ...> is true. Constexpr, triviality and noexcept propagating.
Explicit inplace value constructor. Available if predicate::enable_inplace_value_constructor<std::initializer_list<U>, Args ...> is true. Constexpr, triviality and noexcept propagating.
Explicit inplace error constructor. Available if predicate::enable_inplace_error_constructor<Args ...> is true. Constexpr, triviality and noexcept propagating.
Explicit inplace error constructor. Available if predicate::enable_inplace_error_constructor<std::initializer_list<U>, Args ...> is true. Constexpr, triviality and noexcept propagating.
Explicit inplace exception constructor. Available if predicate::enable_inplace_exception_constructor<Args ...> is true. Constexpr, triviality and noexcept propagating.
Explicit inplace exception constructor. Available if predicate::enable_inplace_exception_constructor<std::initializer_list<U>, Args ...> is true. Constexpr, triviality and noexcept propagating.
Implicit inplace value or error or exception constructor. Available if predicate::enable_inplace_value_error_exception_constructor<A1, A2, Args ...> is true. Constexpr, triviality and noexcept propagating.
Implicit value-from-success-type-sugar copy constructor. Available if predicate::enable_compatible_conversion<T, void, void> is true, or T is void. Constexpr, triviality and noexcept propagating.
Implicit value-from-success-type-sugar move constructor. Available if predicate::enable_compatible_conversion<T, void, void> is true, or T is void. Constexpr, triviality and noexcept propagating.
Implicit error-from-failure-type-sugar copy constructor. Available if predicate::enable_compatible_conversion<void, EC, void, void> is true. Constexpr, triviality and noexcept propagating.
Implicit error-from-failure-type-sugar move constructor. Available if predicate::enable_compatible_conversion<void, EC, void, void> is true. Constexpr, triviality and noexcept propagating.
Implicit error-from-failure-type-sugar copy constructor. Available if predicate::enable_make_error_code_compatible_conversion<void, EC, void, void> is true. Constexpr, triviality and noexcept propagating.
Implicit error-from-failure-type-sugar move constructor. Available if predicate::enable_make_error_code_compatible_conversion<void, EC, void, void> is true. Constexpr, triviality and noexcept propagating.
Implicit exception-from-failure-type-sugar copy constructor. Available if predicate::enable_compatible_conversion<void, void, EP, void> is true. Constexpr, triviality and noexcept propagating.
Implicit exception-from-failure-type-sugar move constructor. Available if predicate::enable_compatible_conversion<void, void, EP, void> is true. Constexpr, triviality and noexcept propagating.
Implicit error-and-exception-from-failure-type-sugar copy constructor. Available if predicate::enable_compatible_conversion<void, EC, EP, void> is true. Constexpr, triviality and noexcept propagating.
Implicit error-and-exception-from-failure-type-sugar move constructor. Available if predicate::enable_compatible_conversion<void, EC, EP, void> is true. Constexpr, triviality and noexcept propagating.
Synthesising observer of the stored exception or error. Available if the traits is_error_code_available<T> and is_exception_ptr_available<T> are both true. Never throws.
Return the output from free function auto failure(T &&, ...)
+ containing a move from any errored and/or excepted state, thus leaving the outcome’s error and exception values in a moved-from state. Depending on the choice of error_type and/or exception_type, this function may therefore be destructive. The error and exception states are accessed using error_type &&assume_error() && noexcept
+ and exception_type &&assume_exception() && noexcept
+.
+
+
Requires: Always available.
+
+
Complexity: Whatever that of error_type’s and/or exception_type’s move constructor is.
Narrow contract lvalue reference observer of the stored error. NoValuePolicy::narrow_error_check() is first invoked, then the reference to the error is returned. As a valid default constructed error is always present, no undefined behaviour occurs unless NoValuePolicy::narrow_error_check() does that.
+
+
Note that if error_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::narrow_error_check().
Narrow contract const lvalue reference observer of the stored error. NoValuePolicy::narrow_error_check() is first invoked, then the reference to the error is returned. As a valid default constructed error is always present, no undefined behaviour occurs unless NoValuePolicy::narrow_error_check() does that.
+
+
Note that if error_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::narrow_error_check().
Narrow contract rvalue reference observer of the stored error. NoValuePolicy::narrow_error_check() is first invoked, then the reference to the error is returned. As a valid default constructed error is always present, no undefined behaviour occurs unless NoValuePolicy::narrow_error_check() does that.
+
+
Note that if error_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::narrow_error_check().
Narrow contract const rvalue reference observer of the stored error. NoValuePolicy::narrow_error_check() is first invoked, then the reference to the error is returned. As a valid default constructed error is always present, no undefined behaviour occurs unless NoValuePolicy::narrow_error_check() does that.
+
+
Note that if error_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::narrow_error_check().
Narrow contract lvalue reference observer of the stored exception. NoValuePolicy::narrow_exception_check() is first invoked, then the reference to the exception is returned. As a valid default constructed exception is always present, no undefined behaviour occurs unless NoValuePolicy::narrow_exception_check() does that.
+
+
Note that if exception_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::narrow_exception_check().
Narrow contract const lvalue reference observer of the stored exception. NoValuePolicy::narrow_exception_check() is first invoked, then the reference to the exception is returned. As a valid default constructed exception is always present, no undefined behaviour occurs unless NoValuePolicy::narrow_exception_check() does that.
+
+
Note that if exception_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::narrow_exception_check().
Narrow contract rvalue reference observer of the stored exception. NoValuePolicy::narrow_exception_check() is first invoked, then the reference to the exception is returned. As a valid default constructed exception is always present, no undefined behaviour occurs unless NoValuePolicy::narrow_exception_check() does that.
+
+
Note that if exception_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::narrow_exception_check().
Narrow contract const rvalue reference observer of the stored exception. NoValuePolicy::narrow_exception_check() is first invoked, then the reference to the exception is returned. As a valid default constructed exception is always present, no undefined behaviour occurs unless NoValuePolicy::narrow_exception_check() does that.
+
+
Note that if exception_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::narrow_exception_check().
Narrow contract lvalue reference observer of any value present. NoValuePolicy::narrow_value_check() is first invoked, then the reference to the value is returned. The convention is that hard undefined behaviour occurs if no value is actually present, however NoValuePolicy::narrow_value_check() can do something to avoid that.
+
+
Note that if value_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::narrow_value_check().
Narrow contract const lvalue reference observer of any value present. NoValuePolicy::narrow_value_check() is first invoked, then the reference to the value is returned. The convention is that hard undefined behaviour occurs if no value is actually present, however NoValuePolicy::narrow_value_check() can do something to avoid that.
+
+
Note that if value_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::narrow_value_check().
Narrow contract rvalue reference observer of any value present. NoValuePolicy::narrow_value_check() is first invoked, then the reference to the value is returned. The convention is that hard undefined behaviour occurs if no value is actually present, however NoValuePolicy::narrow_value_check() can do something to avoid that.
+
+
Note that if value_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::narrow_value_check().
Narrow contract const rvalue reference observer of any value present. NoValuePolicy::narrow_value_check() is first invoked, then the reference to the value is returned. The convention is that hard undefined behaviour occurs if no value is actually present, however NoValuePolicy::narrow_value_check() can do something to avoid that.
+
+
Note that if value_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::narrow_value_check().
Requires: that value_type, error_type and exception_type all implement copy assignment.
+
+
Complexity: If the value_type for both is present, uses value_type’s copy assignment operator, else either destructs or copy constructs value_type as appropriate. error_type’s and exception_type’s copy assignment operator is always used. Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the object is left in a partially completed state, as per the normal rules for the same operation on a struct.
Requires: that value_type, error_type and exception_type all implement a copy constructor.
+
+
Complexity: Same as for value_type’s, error_type’s and exception_type’s copy constructors. Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the object is left in a partially completed state, as per the normal rules for the same operation on a struct.
Complexity: Same as for value_type’s, error_type’s and exception_type’s destructors. Constexpr, triviality and noexcept of underlying operations is propagated.
Disabling catchall constructor used to give useful diagnostic error when trying to use non-inplace constructors when predicate::constructors_enabled is false.
+
+
Requires: predicate::constructors_enabled is false.
Disabling implicit constructor used to give useful diagnostic error when trying to use implicit constructors when predicate::implicit_constructors_enabled is false.
+
+
Requires: predicate::implicit_constructors_enabled is false.
Returns true if this outcome compares equal to the other outcome. Comparison is done using operator== on value_type or error_type and/or exception_type if the currently chosen state is the same for both outcomes, otherwise false is returned.
+
+
Requires: operator== must be a valid expression between value_type and A, and between error_type and B, and between exception_type and C. If value_type is void, then so must be A; similarly for error_type and B; similarly for exception_type and C.
+
+
Complexity: Whatever the underlying operator== have. Constexpr and noexcept of underlying operations is propagated.
Returns true if this outcome compares equal to the other result. Comparison is done using operator== on value_type or error_type if the currently chosen state is the same for both outcome and result, otherwise false is returned. Note that if the outcome is excepted, it will never compare equal to a result.
+
+
Requires: operator== must be a valid expression between value_type and A, and between error_type and B. If value_type is void, then so must be A; similarly for error_type and B.
+
+
Complexity: Whatever the underlying operator== have. Constexpr and noexcept of underlying operations is propagated.
Returns true if this outcome is unsuccessful and its error compares equal to the error in the failure type sugar. Comparison is done using operator== on error_type and A and on exception_type and B.
+
+
Requires: operator== must be a valid expression between error_type and A, or A is void; operator== must be a valid expression between exception_type and B, or B is void. If error_type is void, then so must be A; if exception_type is void, then so must be B.
+
+
Complexity: Whatever the underlying operator== has. Constexpr and noexcept of underlying operations is propagated.
Returns true if this outcome is not successful or its value does not compares equal to the value in the success type sugar. Comparison is done using operator!= on value_type and A. If A is void, this call aliases bool has_error() const noexcept
+.
+
+
Requires: operator!= must be a valid expression between value_type and A, or A is void. If value_type is void, then so must be A.
+
+
Complexity: Whatever the underlying operator!= has. Constexpr and noexcept of underlying operations is propagated.
Wide contract lvalue reference observer of the stored error. NoValuePolicy::wide_error_check() is first invoked, then the reference to the error is returned. As a valid default constructed error is always present, no undefined behaviour occurs if NoValuePolicy::wide_error_check() returns.
+
+
Note that if error_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::wide_error_check().
Wide contract const lvalue reference observer of the stored error. NoValuePolicy::wide_error_check() is first invoked, then the reference to the error is returned. As a valid default constructed error is always present, no undefined behaviour occurs if NoValuePolicy::wide_error_check() returns.
+
+
Note that if error_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::wide_error_check().
Wide contract rvalue reference observer of the stored error. NoValuePolicy::wide_error_check() is first invoked, then the reference to the error is returned. As a valid default constructed error is always present, no undefined behaviour occurs if NoValuePolicy::wide_error_check() returns.
+
+
Note that if error_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::wide_error_check().
Wide contract const rvalue reference observer of the stored error. NoValuePolicy::wide_error_check() is first invoked, then the reference to the error is returned. As a valid default constructed error is always present, no undefined behaviour occurs if NoValuePolicy::wide_error_check() returns.
+
+
Note that if error_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::wide_error_check().
Wide contract lvalue reference observer of the stored exception. NoValuePolicy::wide_exception_check() is first invoked, then the reference to the exception is returned. As a valid default constructed exception is always present, no undefined behaviour occurs if NoValuePolicy::wide_exception_check() returns.
+
+
Note that if exception_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::wide_exception_check().
Wide contract const lvalue reference observer of the stored exception. NoValuePolicy::wide_exception_check() is first invoked, then the reference to the exception is returned. As a valid default constructed exception is always present, no undefined behaviour occurs if NoValuePolicy::wide_exception_check() returns.
+
+
Note that if exception_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::wide_exception_check().
Wide contract rvalue reference observer of the stored exception. NoValuePolicy::wide_exception_check() is first invoked, then the reference to the exception is returned. As a valid default constructed exception is always present, no undefined behaviour occurs if NoValuePolicy::wide_exception_check() returns.
+
+
Note that if exception_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::wide_exception_check().
Wide contract const rvalue reference observer of the stored exception. NoValuePolicy::wide_exception_check() is first invoked, then the reference to the exception is returned. As a valid default constructed exception is always present, no undefined behaviour occurs if NoValuePolicy::wide_exception_check() returns.
+
+
Note that if exception_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::wide_exception_check().
Requires: predicate::enable_compatible_conversion<A, B, C, D> is true.
+
+
Complexity: Same as for the copy constructors of the underlying types. Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the object is left in a partially completed state, as per the normal rules for the same operation on a struct.
Requires: predicate::enable_inplace_error_constructor<std::initializer_list<U>, Args ...> is true.
+
+
Complexity: Same as for the error_type constructor which accepts std::initializer_list<U>, Args .... Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the state of the Args is left indeterminate.
Requires: predicate::enable_inplace_exception_constructor<Args ...> is true.
+
+
Complexity: Same as for the exception_type constructor which accepts Args .... Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the state of the Args is left indeterminate.
Requires: predicate::enable_inplace_exception_constructor<std::initializer_list<U>, Args ...> is true.
+
+
Complexity: Same as for the exception_type constructor which accepts std::initializer_list<U>, Args .... Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the state of the Args is left indeterminate.
Requires: predicate::enable_inplace_value_constructor<std::initializer_list<U>, Args ...> is true.
+
+
Complexity: Same as for the value_type constructor which accepts std::initializer_list<U>, Args .... Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the state of the Args is left indeterminate.
Requires: predicate::enable_compatible_conversion<A, B, C, D> is true.
+
+
Complexity: Same as for the move constructors of the underlying types. Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the object is left in a partially completed state, as per the normal rules for the same operation on a struct.
Requires: predicate::enable_compatible_conversion<A, B, void, C> is true.
+
+
Complexity: Same as for the copy constructors of the underlying types. Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the object is left in a partially completed state, as per the normal rules for the same operation on a struct.
Requires: predicate::enable_make_error_code_compatible_conversion<A, B, void, C> is true.
+
+
Complexity: Same as for the copy constructors of the underlying types. Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the object is left in a partially completed state, as per the normal rules for the same operation on a struct.
Requires: predicate::enable_make_error_code_compatible_conversion<A, B, void, C> is true.
+
+
Complexity: Same as for the move constructors of the underlying types. Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the object is left in a partially completed state, as per the normal rules for the same operation on a struct.
Requires: predicate::enable_compatible_conversion<A, B, void, C> is true.
+
+
Complexity: Same as for the move constructors of the underlying types. Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the object is left in a partially completed state, as per the normal rules for the same operation on a struct.
Requires: convert::value_or_error<T, U>
+ has an available call operator, and if the input is a basic_result or basic_outcome, then convert::value_or_error<> has enabled those inputs for that convert::value_or_error<> specialisation.
+
+
Complexity: Same as for the copy or move constructor from the input’s .value() or .error() respectively. Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the object is left in a partially completed state, as per the normal rules for the same operation on a struct.
Synthesising observer of the stored exception or error. If an exception is available,
+returns a copy of that directly. If an error is available, and not an exception, an
+ADL discovered free function auto basic_outcome_failure_exception_from_error(const EC &)
+
+is invoked. Default overloads for this function are defined in Outcome for
+std::error_code
+
+and boost::system::error_code, these return std::make_exception_ptr(std::system_error(ec))
+and boost::copy_exception(boost::system::system_error(ec)) respectively.
Complexity: Depends on basic_outcome_failure_exception_from_error(const EC &).
+
+
Guarantees: Never throws. If an exception is thrown during the copy of the exception,
+that exception (from std::current_exception()) is returned instead.
Requires: predicate::enable_error_condition_converting_constructor<R> is true.
+
+
Complexity: Same as for error_type’s copy or move constructor from the result of make_error_code(ErrorCondEnum). Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the state of the input is left indeterminate.
Requires: predicate::enable_error_exception_converting_constructor<S, P> is true.
+
+
Complexity: Same as for error_type’s and exception_type’s copy or move constructor. Constexpr, triviality and noexcept of underlying operations is propagated.
Implicit error-and-exception-from-failure-type-sugar copy constructor used to disambiguate the construction of the error + exception types.
+Calls void hook_outcome_copy_construction(T *, U &&, V &&) noexcept
+ with this, const failure_type<EC> & and const failure_type<EP> &.
+
+
Requires: predicate::enable_compatible_conversion<void, EC, EP, void> is true.
+
+
Complexity: Same as for the error_type and exception_type constructors which accept EC and EP. Constexpr, triviality and noexcept of underlying operations is propagated.
Implicit error-and-exception-from-failure-type-sugar move constructor used to disambiguate the construction of the error + exception types.
+Calls void hook_outcome_move_construction(T *, U &&, V &&) noexcept
+ with this, failure_type<EC> && and failure_type<EP> &&.
+
+
Requires: predicate::enable_compatible_conversion<void, EC, EP, void> is true.
+
+
Complexity: Same as for the error_type and exception_type constructors which accept EC and EP. Constexpr, triviality and noexcept of underlying operations is propagated.
Implicit exception-from-failure-type-sugar copy constructor used to disambiguate the construction of the exception type.
+Calls void hook_outcome_copy_construction(T *, U &&) noexcept
+ with this and const failure_type<EP> &.
+
+
Requires: predicate::enable_compatible_conversion<void, void, EP, void> is true.
+
+
Complexity: Same as for the exception_type constructor which accepts EP. Constexpr, triviality and noexcept of underlying operations is propagated.
Implicit exception-from-failure-type-sugar move constructor used to disambiguate the construction of the exception type.
+Calls void hook_outcome_move_construction(T *, U &&) noexcept
+ with this and failure_type<EP> &&.
+
+
Requires: predicate::enable_compatible_conversion<void, void, EP, void> is true.
+
+
Complexity: Same as for the exception_type constructor which accepts EP. Constexpr, triviality and noexcept of underlying operations is propagated.
Implicit inplace value or error or exception constructor. Delegates to an appropriate explicit inplace constructor depending on input.
+
+
Requires: predicate::enable_inplace_value_error_exception_constructor` is true.
+
+
Complexity: Same as for the value_type or error_type or exception_type constructor which accepts A1, A2, Args .... Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the state of the Args is left indeterminate.
Implicit value-from-success-type-sugar copy constructor used to disambiguate the construction of the value type.
+Note that if T = void, value_type will be default constructed. Calls void hook_outcome_copy_construction(T *, U &&) noexcept
+ with this and const success_type<T> &.
+
+
Requires: predicate::enable_compatible_conversion<T, void, void> is true, or T is void.
+
+
Complexity: Same as for the value_type constructor which accepts T, or the value_type default constructor if T is void. Constexpr, triviality and noexcept of underlying operations is propagated.
Implicit value-from-success-type-sugar move constructor used to disambiguate the construction of the value type.
+Note that if T = void, value_type will be default constructed. Calls void hook_outcome_move_construction(T *, U &&) noexcept
+ with this and success_type<T> &&.
+
+
Requires: predicate::enable_compatible_conversion<T, void, void> is true, or T is void.
+
+
Complexity: Same as for the value_type constructor which accepts T, or the value_type default constructor if T is void. Constexpr, triviality and noexcept of underlying operations is propagated.
Returns true if this outcome does not compare equal to the other outcome. Comparison is done using operator!= on value_type, error_type and/or exception_type if the currently chosen state is the same for both outcomes, otherwise true is returned.
+
+
Requires: operator!= must be a valid expression between value_type and A, and between error_type and B, and between exception_type and C. If value_type is void, then so must be A; similarly for error_type and B; similarly for exception_type and C.
+
+
Complexity: Whatever the underlying operator!= have. Constexpr and noexcept of underlying operations is propagated.
Returns true if this outcome does not compare equal to the other result. Comparison is done using operator!= on value_type or error_type if the currently chosen state is the same for both outcome and result, otherwise true is returned. Note that an excepted outcome is always unequal to a result.
+
+
Requires: operator!= must be a valid expression between value_type and A, and between error_type and B. If value_type is void, then so must be A; similarly for error_type and B.
+
+
Complexity: Whatever the underlying operator!= have. Constexpr and noexcept of underlying operations is propagated.
Returns true if this outcome is successful or its error or exception does not compare equal to the error in the failure type sugar. Comparison is done using operator!= on error_type and A and on exception_type and B.
+
+
Requires: operator!= must be a valid expression between error_type and A, or A is void; operator!= must be a valid expression between exception_type and B, or B is void. If error_type is void, then so must be A; if exception_type is void, then so must be B.
+
+
Complexity: Whatever the underlying operator!= has. Constexpr and noexcept of underlying operations is propagated.
Returns true if this result is successful and its value compares equal to the value in the success type sugar. Comparison is done using operator== on value_type and A. If A is void, this call aliases bool has_value() const noexcept
+.
+
+
Requires: operator== must be a valid expression between value_type and A, or A is void. If value_type is void, then so must be A.
+
+
Complexity: Whatever the underlying operator== has. Constexpr and noexcept of underlying operations is propagated.
Requires: that value_type, error_type and exception_type all implement move assignment.
+
+
Complexity: If the value_type for both is present, uses value_type’s move assignment operator, else either destructs or move constructs value_type as appropriate. error_type’s and exception_type’s move assignment operator are always used. Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the object is left in a partially completed state, as per the normal rules for the same operation on a struct.
Requires: that value_type, error_type and exception_type all implement a move constructor.
+
+
Complexity: Same as for value_type’s, error_type’s and exception_type’s move constructors. Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the object is left in a partially completed state, as per the normal rules for the same operation on a struct.
Swap one basic_outcome with another, with the strong guarantee. Constexpr if move constructors and move assignments of value_type, error_type and exception_type are noexcept.
+
+
Requires: Always available.
+
+
Complexity: If the move constructor and move assignment for value_type, error_type and exception_type are noexcept, the complexity is the same as for the swap() implementations of the value_type, error_type and exception_type. Otherwise, complexity is not preserved, as strong_swap(bool &all_good, T &a, T &b)
+ is used instead of swap(). This function defaults to using one move construction and two assignments, and it will attempt extra move assignments in order to restore the state upon entry if a failure occurs.
+
+
Guarantees: If an exception is thrown during the swap operation, the state of all three operands on entry is attempted to be restored, in order to implement the strong guarantee. If that too fails, the flag bits are forced to something consistent such that there can be no simultaneously valued and errored/excepted state, or valueless and errorless/exceptionless. The flag has_lost_consistency()
+ becomes true for both operands, which are now likely in an inconsistent state.
Wide contract lvalue reference observer of any value present. NoValuePolicy::wide_value_check() is first invoked, then the reference to the value is returned.
+
+
Note that if value_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::wide_value_check().
Wide contract const lvalue reference observer of any value present. NoValuePolicy::wide_value_check() is first invoked, then the reference to the value is returned.
+
+
Note that if value_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::wide_value_check().
Wide contract rvalue reference observer of any value present. NoValuePolicy::wide_value_check() is first invoked, then the reference to the value is returned.
+
+
Note that if value_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::wide_value_check().
Wide contract const rvalue reference observer of any value present. NoValuePolicy::wide_value_check() is first invoked, then the reference to the value is returned.
+
+
Note that if value_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::wide_value_check().
A sum type carrying either a T or an E, with NoValuePolicy specifying what to do if one tries to read state which isn’t there. Either or both of T and E can be void to indicate no value for that state is present. Note that E = void makes basic result into effectively an optional<T>, but with NoValuePolicy configurable behaviour. Detectable using is_basic_result<T>
+.
+
+
Requires: Concept requirements if C++ 20, else static asserted:
If C++ exceptions disabled and BOOST_OUTCOME_DISABLE_EXECINFO undefined only (used to print stack backtraces on “exception throw”):
+
+
+
<sal.h> (Windows only)
+
<stddef.h> (Windows only)
+
<string.h> (Windows only)
+
<execinfo.h> (POSIX only)
+
+
<cstdio>
+
<cstdlib>
+
<cassert>
+
+
+
This very light weight set of inclusion dependencies makes basic result suitable for use in global header files of very large C++ codebases.
+
+
Design rationale
+
+
The basic result type is the main workhorse type of the Outcome library, providing a simple sum type with optional values representing success or disappointment. Unlike
+ P0323 std::expected<T, E>
+, Outcome’s result type is designed specifically for convenience when implementing failure handling across very large codebases, and it has a number of API differences to facilitate that.
+
+
The first major design difference is that basic result models its constructor design on
+std::variant<...>
+, rather than modelling
+std::optional<T>
+’s constructor design like std::expected<T, E> does. This means that basic result will implicitly construct either a T or an E if doing so is unambiguous, same as variant does. Where implicit construction is ambiguous, the implicit constructors disable and a T or E can be specified via in_place_type_t<T>
+, or via success_type<T>
+ or failure_type<T>
+. We implement a subset of variant’s constructors for improved compile time impact, so the implicit and explicit constructor design is split into fixed subsets to reduce SFINAE execution.
+
+
The second major design difference is that union storage is NOT used, as it is assumed that sizeof(E) will be small for failure handling. This very considerably reduces load on the compiler, and substantially improves compile times in very large C++ 14 codebases, because copies and moves do not need to jump through complex ceremony in order to implement the never-empty guarantees which would be required in a union storage based implementation (C++ 17 onwards does far fewer copy and move constructor instantiations, but it all adds up – work avoided is always the fastest).
+
+
Public member type aliases
+
+
+
value_type is T.
+
error_type is E.
+
value_type_if_enabled is T if construction from T is available, else it is a usefully named unusable internal type.
+
error_type_if_enabled is E if construction from E is available, else it is a usefully named unusable internal type.
+
rebind<A, B = E, C = NoValuePolicy> is basic_result<A, B, C>.
+
+
+
Protected member predicate booleans
+
+
+
predicate::constructors_enabled is constexpr boolean true if decayed value_type and decayed error_type are not the same type.
+
+
predicate::implicit_constructors_enabled is constexpr boolean true if:
+
+
+
predicate::constructors_enabled is true.
+
Trait is_error_type<E>
+ is not true for both decayed value_type and decayed error_type at the same time.
+
value_type is not implicitly constructible from error_type and error_type is not implicitly constructible from value_type. OR trait is_error_type<E>
+ is true for decayed error_type and error_type is not implicitly constructible from value_type and value_type is an integral type.
+
+
+
predicate::enable_value_converting_constructor<A> is constexpr boolean true if:
value_type is implicitly constructible from A and error_type is not implicitly constructible from A. OR value_type is the exact same type as decayed A and value_type is implicitly constructible from A.
+
+
+
predicate::enable_error_converting_constructor<A> is constexpr boolean true if:
value_type is not implicitly constructible from A and error_type is implicitly constructible from A. OR error_type is the exact same type as decayed A and error_type is implicitly constructible from A.
+
+
+
predicate::enable_error_condition_converting_constructor<ErrorCondEnum> is constexpr boolean true if:
+
+
+
predicate::constructors_enabled is true.
+
Decayed ErrorCondEnum is not this basic_result type.
predicate::enable_compatible_conversion<A, B, C> is constexpr boolean true if:
+
+
+
predicate::constructors_enabled is true.
+
basic_result<A, B, C> is not this basic_result type.
+
A is void OR value_type is explicitly constructible from A.
+
B is void OR error_type is explicitly constructible from B.
+
+
+
predicate::enable_make_error_code_compatible_conversion<A, B, C> is constexpr boolean true if:
+
+
+
predicate::constructors_enabled is true.
+
basic_result<A, B, C> is not this basic_result type.
+
Trait "/home/travis/build/ned14/boost-outcome/doc/src/content/reference/types/basic_result/_index.md:92:14": API reference page for 'is_error_code_available<E>' not found, please use an identifier wholly contained in a page title
+ API NOT FOUND IN DOCS is_error_code_available<E>
+ is true for decayed error_type.
+
predicate::enable_compatible_conversion<A, B, C> is not true.
+
A is void OR value_type is explicitly constructible from A.
+
error_type is explicitly constructible from make_error_code(B).
+
+
+
predicate::enable_make_exception_ptr_compatible_conversion<A, B, C> is constexpr boolean true if:
+
+
+
predicate::constructors_enabled is true.
+
basic_result<A, B, C> is not this basic_result type.
+
Trait "/home/travis/build/ned14/boost-outcome/doc/src/content/reference/types/basic_result/_index.md:100:14": API reference page for 'is_exception_ptr_available<E>' not found, please use an identifier wholly contained in a page title
+ API NOT FOUND IN DOCS is_exception_ptr_available<E>
+ is true for decayed error_type.
+
predicate::enable_compatible_conversion<A, B, C> is not true.
+
A is void OR value_type is explicitly constructible from A.
+
error_type is explicitly constructible from make_exception_ptr(B).
+
+
+
predicate::enable_inplace_value_constructor<Args...> is constexpr boolean true if:
+
+
+
predicate::constructors_enabled is true.
+
value_type is void OR value_type is explicitly constructible from Args....
+
+
+
predicate::enable_inplace_error_constructor<Args...> is constexpr boolean true if:
+
+
+
predicate::constructors_enabled is true.
+
error_type is void OR error_type is explicitly constructible from Args....
+
+
+
predicate::enable_inplace_value_error_constructor<Args...> is constexpr boolean true if:
+
+
+
predicate::constructors_enabled is true.
+
predicate::implicit_constructors_enabled is true.
+
Either, but not both, of value_type is explicitly constructible from Args... or error_type is explicitly constructible from Args....
EqualityComparable, if both value_type and error_type implement equality comparisons with one another.
+
+
LessThanComparable, not implemented due to availability of implicit conversions from value_type and error_type, this can cause major surprise (i.e. hard to diagnose bugs), so we don’t implement these at all.
+~ Swappable
+
+
Hash, not implemented as a generic implementation of a unique hash for non-valued items which are unequal would require a dependency on RTTI being enabled.
+
+
+
Thus basic_result meets the Regular concept if both value_type and error_type are Regular, except for the lack of a default constructor. Often where one needs a default constructor, wrapping basic_result into
+std::optional<T>
+ will suffice.
Disabling catchall constructor used to give useful diagnostic error when trying to use non-inplace constructors when predicate::constructors_enabled is false.
Disabling implicit constructor used to give useful diagnostic error when trying to use implicit constructors when predicate::implicit_constructors_enabled is false.
+
+
Copy and move constructors and assignment, and destructor
Implicit value_type constructor. Available if predicate::enable_value_converting_constructor<R> is true. Constexpr, triviality and noexcept propagating.
Implicit error_type constructor. Available if predicate::enable_error_converting_constructor<S> is true. Constexpr, triviality and noexcept propagating.
Implicit error_type from ErrorCondEnum constructor. Available if predicate::enable_error_condition_converting_constructor<ErrorCondEnum> is true. Constexpr, triviality and noexcept propagating.
Explicit converting constructor from ValueOrError<T, E> concept matching types. Available if convert::value_or_error<> permits it. Constexpr, triviality and noexcept propagating.
Explicit converting copy constructor from compatible basic_result. Available if predicate::enable_compatible_conversion<R, S, P> is true. Constexpr, triviality and noexcept propagating.
Explicit converting move constructor from compatible basic_result. Available if predicate::enable_compatible_conversion<R, S, P> is true. Constexpr, triviality and noexcept propagating.
Explicit converting copy constructor from compatible basic_result. Available if predicate::enable_make_error_code_compatible_conversion<R, S, P> is true. Constexpr, triviality and noexcept propagating.
Explicit converting move constructor from compatible basic_result. Available if predicate::enable_make_error_code_compatible_conversion<R, S, P> is true. Constexpr, triviality and noexcept propagating.
Explicit converting copy constructor from compatible basic_result. Available if predicate::enable_make_exception_ptr_compatible_conversion<R, S, P> is true. Constexpr, triviality and noexcept propagating.
Explicit converting move constructor from compatible basic_result. Available if predicate::enable_make_exception_ptr_compatible_conversion<R, S, P> is true. Constexpr, triviality and noexcept propagating.
Explicit inplace value constructor. Available if predicate::enable_inplace_value_constructor<Args ...> is true. Constexpr, triviality and noexcept propagating.
Explicit inplace value constructor. Available if predicate::enable_inplace_value_constructor<std::initializer_list<U>, Args ...> is true. Constexpr, triviality and noexcept propagating.
Explicit inplace error constructor. Available if predicate::enable_inplace_error_constructor<Args ...> is true. Constexpr, triviality and noexcept propagating.
Explicit inplace error constructor. Available if predicate::enable_inplace_error_constructor<std::initializer_list<U>, Args ...> is true. Constexpr, triviality and noexcept propagating.
Implicit inplace value or error constructor. Available if predicate::enable_inplace_value_error_constructor<A1, A2, Args ...> is true. Constexpr, triviality and noexcept propagating.
Implicit value-from-success-type-sugar copy constructor. Available if predicate::enable_compatible_conversion<T, void, void> is true, or T is void. Constexpr, triviality and noexcept propagating.
Implicit value-from-success-type-sugar move constructor. Available if predicate::enable_compatible_conversion<T, void, void> is true, or T is void. Constexpr, triviality and noexcept propagating.
Implicit error-from-failure-type-sugar copy constructor. Available if predicate::enable_compatible_conversion<void, T, void> is true, or T is void. Constexpr, triviality and noexcept propagating.
Implicit error-from-failure-type-sugar move constructor. Available if predicate::enable_compatible_conversion<void, T, void> is true, or T is void. Constexpr, triviality and noexcept propagating.
Implicit error-from-failure-type-sugar copy constructor. Available if predicate::enable_make_error_code_compatible_conversion<void, T, void> is true, or T is void. Constexpr, triviality and noexcept propagating.
Implicit error-from-failure-type-sugar move constructor. Available if predicate::enable_make_error_code_compatible_conversion<void, T, void> is true, or T is void. Constexpr, triviality and noexcept propagating.
Implicit error-from-failure-type-sugar copy constructor. Available if predicate::enable_make_exception_ptr_compatible_conversion<void, T, void> is true, or T is void. Constexpr, triviality and noexcept propagating.
Implicit error-from-failure-type-sugar move constructor. Available if predicate::enable_make_exception_ptr_compatible_conversion<void, T, void> is true, or T is void. Constexpr, triviality and noexcept propagating.
Return the output from free function auto failure(T &&, ...)
+ containing a move from any errored state, thus leaving the result’s error value in a moved-from state. Depending on the choice of error_type, this function may therefore be destructive. The error state is accessed using error_type &&assume_error() && noexcept
+.
+
+
Requires: Always available.
+
+
Complexity: Whatever that of error_type’s move constructor is.
Narrow contract lvalue reference observer of the stored error. NoValuePolicy::narrow_error_check() is first invoked, then the reference to the error is returned. As a valid default constructed error is always present, no undefined behaviour occurs unless NoValuePolicy::narrow_error_check() does that.
+
+
Note that if error_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::narrow_error_check().
Narrow contract const lvalue reference observer of the stored error. NoValuePolicy::narrow_error_check() is first invoked, then the reference to the error is returned. As a valid default constructed error is always present, no undefined behaviour occurs unless NoValuePolicy::narrow_error_check() does that.
+
+
Note that if error_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::narrow_error_check().
Narrow contract rvalue reference observer of the stored error. NoValuePolicy::narrow_error_check() is first invoked, then the reference to the error is returned. As a valid default constructed error is always present, no undefined behaviour occurs unless NoValuePolicy::narrow_error_check() does that.
+
+
Note that if error_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::narrow_error_check().
Narrow contract const rvalue reference observer of the stored error. NoValuePolicy::narrow_error_check() is first invoked, then the reference to the error is returned. As a valid default constructed error is always present, no undefined behaviour occurs unless NoValuePolicy::narrow_error_check() does that.
+
+
Note that if error_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::narrow_error_check().
Narrow contract lvalue reference observer of any value present. NoValuePolicy::narrow_value_check() is first invoked, then the reference to the value is returned. The convention is that hard undefined behaviour occurs if no value is actually present, however NoValuePolicy::narrow_value_check() can do something to avoid that.
+
+
Note that if value_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::narrow_value_check().
Narrow contract const lvalue reference observer of any value present. NoValuePolicy::narrow_value_check() is first invoked, then the reference to the value is returned. The convention is that hard undefined behaviour occurs if no value is actually present, however NoValuePolicy::narrow_value_check() can do something to avoid that.
+
+
Note that if value_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::narrow_value_check().
Narrow contract rvalue reference observer of any value present. NoValuePolicy::narrow_value_check() is first invoked, then the reference to the value is returned. The convention is that hard undefined behaviour occurs if no value is actually present, however NoValuePolicy::narrow_value_check() can do something to avoid that.
+
+
Note that if value_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::narrow_value_check().
Narrow contract const rvalue reference observer of any value present. NoValuePolicy::narrow_value_check() is first invoked, then the reference to the value is returned. The convention is that hard undefined behaviour occurs if no value is actually present, however NoValuePolicy::narrow_value_check() can do something to avoid that.
+
+
Note that if value_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::narrow_value_check().
Requires: that value_type and error_type both implement copy assignment.
+
+
Complexity: If the value_type for both is present, uses value_type’s copy assignment operator, else either destructs or copy constructs value_type as appropriate. error_type’s copy assignment operator is always used. Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the object is left in a partially completed state, as per the normal rules for the same operation on a struct.
Requires: that value_type and error_type both implement a copy constructor.
+
+
Complexity: Same as for value_type’s and error_type’s copy constructors. Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the object is left in a partially completed state, as per the normal rules for the same operation on a struct.
Disabling catchall constructor used to give useful diagnostic error when trying to use non-inplace constructors when predicate::constructors_enabled is false.
+
+
Requires: predicate::constructors_enabled is false.
Disabling implicit constructor used to give useful diagnostic error when trying to use implicit constructors when predicate::implicit_constructors_enabled is false.
+
+
Requires: predicate::implicit_constructors_enabled is false.
Returns true if this result compares equal to the other result. Comparison is done using operator== on either value_type or error_type if the currently chosen state is the same for both results, otherwise false is returned.
+
+
Requires: operator== must be a valid expression between value_type and A, and between error_type and B. If value_type is void, then so must be A; similarly for error_type and B.
+
+
Complexity: Whatever the underlying operator== have. Constexpr and noexcept of underlying operations is propagated.
+
+
Guarantees: None.
+
+
Free function alias: There is a free function bool operator==(const basic_result<A, B, C> &, const basic_outcome<A, B, C, D> &) which forwards perfectly to this function, by reversing the operands.
Returns true if this result is unsuccessful and its error compares equal to the error in the failure type sugar. Comparison is done using operator== on error_type and A. If A is void, this call aliases bool has_error() const noexcept
+.
+
+
Requires: operator== must be a valid expression between error_type and A, or A is void. If error_type is void, then so must be A.
+
+
Complexity: Whatever the underlying operator== has. Constexpr and noexcept of underlying operations is propagated.
Returns true if this result is not successful or its value does not compares equal to the value in the success type sugar. Comparison is done using operator!= on value_type and A. If A is void, this call aliases bool has_error() const noexcept
+.
+
+
Requires: operator!= must be a valid expression between value_type and A, or A is void. If value_type is void, then so must be A.
+
+
Complexity: Whatever the underlying operator!= has. Constexpr and noexcept of underlying operations is propagated.
Wide contract lvalue reference observer of the stored error. NoValuePolicy::wide_error_check() is first invoked, then the reference to the error is returned. As a valid default constructed error is always present, no undefined behaviour occurs if NoValuePolicy::wide_error_check() returns.
+
+
Note that if error_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::wide_error_check().
Wide contract const lvalue reference observer of the stored error. NoValuePolicy::wide_error_check() is first invoked, then the reference to the error is returned. As a valid default constructed error is always present, no undefined behaviour occurs if NoValuePolicy::wide_error_check() returns.
+
+
Note that if error_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::wide_error_check().
Wide contract rvalue reference observer of the stored error. NoValuePolicy::wide_error_check() is first invoked, then the reference to the error is returned. As a valid default constructed error is always present, no undefined behaviour occurs if NoValuePolicy::wide_error_check() returns.
+
+
Note that if error_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::wide_error_check().
Wide contract const rvalue reference observer of the stored error. NoValuePolicy::wide_error_check() is first invoked, then the reference to the error is returned. As a valid default constructed error is always present, no undefined behaviour occurs if NoValuePolicy::wide_error_check() returns.
+
+
Note that if error_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::wide_error_check().
Requires: predicate::enable_compatible_conversion<R, S, P> is true.
+
+
Complexity: Same as for the copy constructors of the underlying types. Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the object is left in a partially completed state, as per the normal rules for the same operation on a struct.
Requires: predicate::enable_inplace_error_constructor<std::initializer_list<U>, Args ...> is true.
+
+
Complexity: Same as for the error_type constructor which accepts std::initializer_list<U>, Args .... Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the state of the Args is left indeterminate.
Requires: predicate::enable_inplace_value_constructor<std::initializer_list<U>, Args ...> is true.
+
+
Complexity: Same as for the value_type constructor which accepts std::initializer_list<U>, Args .... Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the state of the Args is left indeterminate.
Requires: predicate::enable_make_error_code_compatible_conversion<R, S, P> is true.
+
+
Complexity: Same as for the copy constructors of the underlying types. Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the object is left in a partially completed state, as per the normal rules for the same operation on a struct.
Requires: predicate::enable_make_error_code_compatible_conversion<R, S, P> is true.
+
+
Complexity: Same as for the move constructors of the underlying types. Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the object is left in a partially completed state, as per the normal rules for the same operation on a struct.
Requires: predicate::enable_make_exception_ptr_compatible_conversion<R, S, P> is true.
+
+
Complexity: Same as for the copy constructors of the underlying types. Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the object is left in a partially completed state, as per the normal rules for the same operation on a struct.
Requires: predicate::enable_make_exception_ptr_compatible_conversion<R, S, P> is true.
+
+
Complexity: Same as for the move constructors of the underlying types. Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the object is left in a partially completed state, as per the normal rules for the same operation on a struct.
Requires: predicate::enable_compatible_conversion<R, S, P> is true.
+
+
Complexity: Same as for the move constructors of the underlying types. Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the object is left in a partially completed state, as per the normal rules for the same operation on a struct.
Explicit converting constructor from ValueOrError<T, E>
+ concept matching types. Delegates to the basic_result move constructor.
+
+
Requires: convert::value_or_error<T, U>
+ has an available call operator, and if the input is a basic_result or basic_outcome, then convert::value_or_error<> has enabled those inputs for that convert::value_or_error<> specialisation.
+
+
Complexity: Same as for the copy or move constructor from the input’s .value() or .error() respectively. Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the object is left in a partially completed state, as per the normal rules for the same operation on a struct.
Requires: predicate::enable_error_condition_converting_constructor<R> is true.
+
+
Complexity: Same as for error_type’s copy or move constructor from the result of make_error_code(ErrorCondEnum). Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the state of the input is left indeterminate.
Implicit error-from-failure-type-sugar copy constructor used to disambiguate the construction of the error type.
+Note that if T = void, error_type will be default constructed. Calls void hook_result_copy_construction(T *, U &&) noexcept
+ with this and const failure_type<T> &.
+
+
Requires: predicate::enable_compatible_conversion<void, T, void> is true, or T is void.
+
+
Complexity: Same as for the error_type constructor which accepts T, or the error_type default constructor if T is void. Constexpr, triviality and noexcept of underlying operations is propagated.
Implicit error-from-failure-type-sugar copy constructor used to disambiguate the construction of the error type.
+Note that if T = void, error_type will be default constructed. Calls void hook_result_copy_construction(T *, U &&) noexcept
+ with this and const failure_type<T> &.
+
+
Requires: predicate::enable_make_error_code_compatible_conversion<void, T, void> is true, or T is void.
+
+
Complexity: Same as for the error_type constructor which accepts T, or the error_type default constructor if T is void. Constexpr, triviality and noexcept of underlying operations is propagated.
Implicit error-from-failure-type-sugar move constructor used to disambiguate the construction of the error type.
+Note that if T = void, error_type will be default constructed. Calls void hook_result_move_construction(T *, U &&) noexcept
+ with this and failure_type<T> &&.
+
+
Requires: predicate::enable_make_error_code_compatible_conversion<void, T, void> is true, or T is void.
+
+
Complexity: Same as for the error_type constructor which accepts T, or the error_type default constructor if T is void. Constexpr, triviality and noexcept of underlying operations is propagated.
Implicit error-from-failure-type-sugar copy constructor used to disambiguate the construction of the error type.
+Note that if T = void, error_type will be default constructed. Calls void hook_result_copy_construction(T *, U &&) noexcept
+ with this and const failure_type<T> &.
+
+
Requires: predicate::enable_make_exception_ptr_compatible_conversion<void, T, void> is true, or T is void.
+
+
Complexity: Same as for the error_type constructor which accepts T, or the error_type default constructor if T is void. Constexpr, triviality and noexcept of underlying operations is propagated.
Implicit error-from-failure-type-sugar move constructor used to disambiguate the construction of the error type.
+Note that if T = void, error_type will be default constructed. Calls void hook_result_move_construction(T *, U &&) noexcept
+ with this and failure_type<T> &&.
+
+
Requires: predicate::enable_make_exception_ptr_compatible_conversion<void, T, void> is true, or T is void.
+
+
Complexity: Same as for the error_type constructor which accepts T, or the error_type default constructor if T is void. Constexpr, triviality and noexcept of underlying operations is propagated.
Implicit error-from-failure-type-sugar move constructor used to disambiguate the construction of the error type.
+Note that if T = void, error_type will be default constructed. Calls void hook_result_move_construction(T *, U &&) noexcept
+ with this and failure_type<T> &&.
+
+
Requires: predicate::enable_compatible_conversion<void, T, void> is true, or T is void.
+
+
Complexity: Same as for the error_type constructor which accepts T, or the error_type default constructor if T is void. Constexpr, triviality and noexcept of underlying operations is propagated.
Implicit inplace value or error constructor. Delegates to an appropriate explicit inplace constructor depending on input.
+
+
Requires: predicate::enable_inplace_value_error_constructor` is true.
+
+
Complexity: Same as for the value_type or error_type constructor which accepts A1, A2, Args .... Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the state of the Args is left indeterminate.
Implicit value-from-success-type-sugar copy constructor used to disambiguate the construction of the value type.
+Note that if T = void, value_type will be default constructed. Calls void hook_result_copy_construction(T *, U &&) noexcept
+ with this and const success_type<T> &.
+
+
Requires: predicate::enable_compatible_conversion<T, void, void> is true, or T is void.
+
+
Complexity: Same as for the value_type constructor which accepts T, or the value_type default constructor if T is void. Constexpr, triviality and noexcept of underlying operations is propagated.
Implicit value-from-success-type-sugar move constructor used to disambiguate the construction of the value type.
+Note that if T = void, value_type will be default constructed. Calls void hook_result_move_construction(T *, U &&) noexcept
+ with this and success_type<T> &&.
+
+
Requires: predicate::enable_compatible_conversion<T, void, void> is true, or T is void.
+
+
Complexity: Same as for the value_type constructor which accepts T, or the value_type default constructor if T is void. Constexpr, triviality and noexcept of underlying operations is propagated.
Returns true if this result does not compare equal to the other result. Comparison is done using operator!= on either value_type or error_type if the currently chosen state is the same for both results, otherwise true is returned.
+
+
Requires: operator!= must be a valid expression between value_type and A, and between error_type and B. If value_type is void, then so must be A; similarly for error_type and B.
+
+
Complexity: Whatever the underlying operator!= have. Constexpr and noexcept of underlying operations is propagated.
+
+
Guarantees: None.
+
+
Free function alias: There is a free function bool operator!=(const basic_result<A, B, C> &, const basic_outcome<A, B, C, D> &) which forwards perfectly to this function, by reversing the operands.
Returns true if this result is successful or its error does not compare equal to the error in the failure type sugar. Comparison is done using operator!= on error_type and A. If A is void, this call aliases bool has_value() const noexcept
+.
+
+
Requires: operator!= must be a valid expression between error_type and A, or A is void. If error_type is void, then so must be A.
+
+
Complexity: Whatever the underlying operator!= has. Constexpr and noexcept of underlying operations is propagated.
Returns true if this result is successful and its value compares equal to the value in the success type sugar. Comparison is done using operator== on value_type and A. If A is void, this call aliases bool has_value() const noexcept
+.
+
+
Requires: operator== must be a valid expression between value_type and A, or A is void. If value_type is void, then so must be A.
+
+
Complexity: Whatever the underlying operator== has. Constexpr and noexcept of underlying operations is propagated.
Requires: that value_type and error_type both implement move assignment.
+
+
Complexity: If the value_type for both is present, uses value_type’s move assignment operator, else either destructs or move constructs value_type as appropriate. error_type’s move assignment operator is always used. Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the object is left in a partially completed state, as per the normal rules for the same operation on a struct.
Requires: that value_type and error_type both implement a move constructor.
+
+
Complexity: Same as for value_type’s and error_type’s move constructors. Constexpr, triviality and noexcept of underlying operations is propagated.
+
+
Guarantees: If an exception is thrown during the operation, the object is left in a partially completed state, as per the normal rules for the same operation on a struct.
Swap one basic_result with another, with the strong guarantee. Constexpr if move constructors and move assignments of value_type and error_type are noexcept.
+
+
Requires: Always available.
+
+
Complexity: If the move constructor and move assignment for value_type and error_type are noexcept, the complexity is the same as for the swap() implementations of the value_type and error_type. Otherwise, complexity is not preserved, as strong_swap(bool &all_good, T &a, T &b)
+ is used instead of swap(). This function defaults to using one move construction and two assignments, and it will attempt extra move assignments in order to restore the state upon entry if a failure occurs.
+
+
Guarantees: If an exception is thrown during the swap operation, the state of both operands on entry is attempted to be restored, in order to implement the strong guarantee. If that too fails, the flag bits are forced to something consistent such that there can be no simultaneously valued and errored state, or valueless and errorless. The flag has_lost_consistency()
+ becomes true for both operands, which are now likely in an inconsistent state.
Wide contract lvalue reference observer of any value present. NoValuePolicy::wide_value_check() is first invoked, then the reference to the value is returned.
+
+
Note that if value_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::wide_value_check().
Wide contract const lvalue reference observer of any value present. NoValuePolicy::wide_value_check() is first invoked, then the reference to the value is returned.
+
+
Note that if value_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::wide_value_check().
Wide contract rvalue reference observer of any value present. NoValuePolicy::wide_value_check() is first invoked, then the reference to the value is returned.
+
+
Note that if value_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::wide_value_check().
Wide contract const rvalue reference observer of any value present. NoValuePolicy::wide_value_check() is first invoked, then the reference to the value is returned.
+
+
Note that if value_type is void, only a const overload returning void is present.
+
+
Requires: Always available.
+
+
Complexity: Depends on NoValuePolicy::wide_value_check().
Type sugar for constructing an unsuccessful result or outcome. Generally not constructed directly, but via the free function failure(T &&, ...)
+. Detectable using is_failure_type<T>
+.
+
+
This is a regular wrapper type, with defaulted default, copy and move constructor, defaulted assignment, and defaulted destructor.
+
+
Member type aliases error_type and exception_type indicate EC and E.
+
+
There is an explicit initialising constructor taking any types U and V which will forward construct the contained error_type and exception_type respectively.
+
+
There are two tagged initialising constructors taking in_place_type_t<error_type> or in_place_type_t<exception_type>, and a U which will forward construct the contained error_type and exception_type respectively.
+
+
There are .error() and .exception() reference observers with the usual constexpr lvalue, const lvalue, rvalue and const rvalue overloads. One can discover which or both of these is valid using the usual .has_error() and .has_exception() observers.
+
+
There are specialisations failure_type<EC, void> and failure_type<void, E> which store nothing for the voided type and do not provide their observer functions.
Type sugar for constructing a successful result or outcome. Generally not constructed directly, but via the free function success(T &&)
+. Detectable using is_success_type<T>
+.
+
+
This is a regular wrapper type, with defaulted default, copy and move constructor, defaulted assignment, and defaulted destructor.
+
+
A member type alias value_type indicates T.
+
+
There is an explicit initialising constructor taking any type U which is not a success_type<T>, and which will forward construct the contained T from that U.
+
+
There is a .value() reference observer with the usual constexpr lvalue, const lvalue, rvalue and const rvalue overloads.
+
+
There is a specialisation success_type<void> which stores nothing and provides no .value() observers.
Outcome is a header-only C++ 14 library known to work well on the latest
+point releases of these compiler-platform combinations or better:
+
+
+
clang 4.0.1 (LLVM) [FreeBSD, Linux, OS X]
+
GCC 6.5 [Linux]
+
Visual Studio 2017.9 [Windows]
+
XCode 9 [MacOS]
+
+
+
It is worth turning on C++ 17 if you can, as there are many usability and
+performance improvements. If your compiler implements the Concepts TS, it
+is worth turning support on. Support is automatically
+detected and used.
+
+
Partially working compilers (this was last updated January 2019):
+
+
+
clang 3.5 - 3.9 can compile varying degrees of the test suite, the
+problem is lack of complete and unbuggy C++ 14 language support.
+
Older point releases of GCCs 7 and 8 have internal compiler error bugs
+in their constexpr implementation which tend to be triggered by using
+Outcome in constexpr. If you don’t use Outcome in constexpr, you won’t
+see these problems. If you need your GCC to not ICE, upgrade to the
+very latest point release, the constexpr ICE has been since fixed.
+
Early editions of Visual Studio 2017 have many corner case problems.
+The latest point release, VS2017.9, only has a few known problems,
+and should be relatively unsurprising for most use cases.
+
+
+
+
+
“C++ 14” compilers which do not work, and will not work until their
+maintainers fix them:
+
+
+
GCC 5, due to a bug in nested template variables parsing which was fixed
+in GCC 6. I appreciate that this upsets a lot of users. Please raise your
+upset at https://gcc.gnu.org/bugzilla/. In the meantime, you can get fairly
+far in Outcome with even clang 3.5.
+
Any compiler which uses the libstdc++ version which comes with GCC 5, as it does
+not implement enough of the C++ 14 standard library for Outcome to compile.
If you have a bit more time, this covers all the time-saving ways you can customise and automate Outcome for various use cases, especially in larger codebases made up of multiple third party libraries.
An oft-asked question during conference talks on Expected/Outcome is how to
+exclusively use result to implement constructor failure. This is asked because
+whilst almost every member function in a class can return a result, constructors
+do not return values and thus cannot return a result. The implication is
+that one cannot avoid throwing C++ exceptions to abort a construction.
+
+
As with most things in C++, one can achieve zero-exception-throw object
+construction using a lot of
+extra typing of boilerplate, and a little bit of simple C++ metaprogramming. This section
+shows you how to implement these for those who are absolutely adverse to ever throwing an exception,
+or cannot because C++ exceptions have been globally disabled.
+
+
The technique described here is not suitable for non-copyable and non-movable
+types. There is also an assumption that moving your type is cheap.
Borrowing from llfio::file_handle
+which uses this design pattern1, here is a simplified file_handle implementation:
+
+
classfile_handle
+{
+ int_fd{-1};// file descriptor
+structstat_stat
+ {
+ 0
+ };// stat of the fd at open
+
+ // Phase 1 private constexpr constructor
+constexprfile_handle(){}
+
+public:
+ usingpath_type=filesystem::path;
+
+ //! The behaviour of the handle: does it read, read and write, or atomic append?
+enumclassmode:unsignedchar// bit 0 set means writable
+{
+ unchanged=0,
+ none=2,//!< No ability to read or write anything, but can synchronise (SYNCHRONIZE or 0)
+attr_read=4,//!< Ability to read attributes (FILE_READ_ATTRIBUTES|SYNCHRONIZE or O_RDONLY)
+attr_write=5,//!< Ability to read and write attributes (FILE_READ_ATTRIBUTES|FILE_WRITE_ATTRIBUTES|SYNCHRONIZE or O_RDONLY)
+read=6,//!< Ability to read (READ_CONTROL|FILE_READ_DATA|FILE_READ_ATTRIBUTES|FILE_READ_EA|SYNCHRONISE or O_RDONLY)
+write=7,//!< Ability to read and write (READ_CONTROL|FILE_READ_DATA|FILE_READ_ATTRIBUTES|FILE_READ_EA|FILE_WRITE_DATA|FILE_WRITE_ATTRIBUTES|FILE_WRITE_EA|FILE_APPEND_DATA|SYNCHRONISE or O_RDWR)
+append=9//!< All mainstream OSs and CIFS guarantee this is atomic with respect to all other appenders (FILE_APPEND_DATA|SYNCHRONISE or O_APPEND)
+};
+
+ // Moves but not copies permitted
+file_handle(constfile_handle&)=delete;
+ file_handle(file_handle&&o)noexcept:_fd(o._fd){o._fd=-1;}
+ file_handle&operator=(constfile_handle&)=delete;
+ file_handle&operator=(file_handle&&o)noexcept
+ {
+ this->~file_handle();
+ new(this)file_handle(std::move(o));
+ return*this;
+ }
+ // Destruction closes the handle
+~file_handle()
+ {
+ if(_fd!=-1)
+ {
+ if(-1==::close(_fd))
+ {
+ inte=errno;
+ std::cerr<<"FATAL: Closing the fd during destruction failed due to "<<strerror(e)<<std::endl;
+ std::terminate();
+ }
+ _fd=-1;
+ }
+ }
+
+ // Phase 2 static member constructor function, which cannot throw
+staticinlineoutcome::result<file_handle>file(path_typepath,modemode=mode::read)noexcept;
+};
+
Note the default member initialisers, these are particularly convenient for
+implementing phase 1 of construction. Note also the constexpr constructor,
+which thanks to the default member initialisers is otherwise empty.
+
+
File handles are very expensive to copy as they involve a syscall to duplicate
+the file descriptor, so we enable moves only.
+
+
The destructor closes the file descriptor if it is not -1, and if the close
+fails, seeing as there is nothing else we can do without leaking the file
+descriptor, we fatal exit the process.
+
+
Finally we declare the phase 2 constructor which is a static member function.
+
+
+
+
+
+
LLFIO uses Outcome “in anger”, both in Standard and Experimental configurations. If you would like a real world user of Outcome to study the source code of, it can be studied at https://github.com/ned14/llfio/.
+ [return]
The eye is immediately drawn to the two-stage invocation pattern, so we are
+constructing a type make<file_handle> using the arguments with which we wish
+to invoke the file_handle constructor with, and then invoking the
+call operator on that make<file_handle> instance to do the
+actual construction.
+
+
It may seem a bit clunky to use brace initialisation for parameters followed
+by a “spurious” set of empty brackets, but we think that this is a better
+approach than alternatives. We shall briefly cover those at the end of this section.
template<classT>structmake
+{
+ outcome::result<T>operator()()constnoexcept
+ {//
+static_assert(!std::is_same<T,T>::value,//
+"make<T>() was not specialised for the type T supplied");
+ }
+};
+
Because this is a struct, we can list initialise make, and use
+default member initialisers to implement default arguments. This can get
+you surprisingly far before you need to start writing custom constructors.
+
+
But in more complex code, you will usually provide all the initialisation overloads that
+you would for the constructors of your main type. You then implement a single phase 2 constructing
+function which accepts make<YOURTYPE> as input, and construct solely from
+that source.
No doubt many will dislike the two-stage invocation pattern i.e.
+
make<file_handle>{"hello"}();
+
+
So let us examine the most obvious alternative: a templated free function make<T>.
+
+
Due to the inability to partially specialise templated functions in C++, you
+need to use tagged overloading e.g.
+
template<class... Args>
+inlineoutcome::result<file_handle>make(std::in_place_type_t<file_handle>,Args&&...args)
+{
+ returnfile_handle::file(std::forward<Args>(args)...);
+}
+...
+// Now you must always write this:
+make(std::in_place_type<file_handle>,"hello");
+
+
Tagged overloading is fine for smaller projects, but for larger code bases:
+
+
+
It takes longer to type make(std::in_place_type<file_handle>, "hello"),
+and is possibly less intuitive to write,
+than it does make<file_handle>{"hello"}().
+
Compiler error messages are enormously clearer if you encode the permitted
+overloads for construction into the make<file_handle> type rather than
+letting a variadic free function fail to resolve an appropriate overload.
+
Resolving variadic free function overloads is not constant time for the compiler,
+whereas resolving the type specialisation for make<file_handle>
+is constant time. In other words, free functions are expensive on build
+times, whereas fully specialised types are not.
+
It actually turns out to be quite useful when writing generic code
+to pass around object constructing factory objects all of which have
+no parameters for their call operator. It becomes, effectively, a
+lazy construction mechanism.
// Phase 2 static member constructor function, which cannot throw
+inlineoutcome::result<file_handle>file_handle::file(file_handle::path_typepath,file_handle::modemode)noexcept
+{
+ // Perform phase 1 of object construction
+file_handleret;
+
+ // Perform phase 2 of object construction
+intflags=0;
+ switch(mode)
+ {
+ casemode::attr_read:
+ casemode::read:
+ flags=O_RDONLY;
+ break;
+ casemode::attr_write:
+ casemode::write:
+ flags=O_RDWR;
+ break;
+ casemode::append:
+ flags=O_APPEND;
+ break;
+ default:
+ returnstd::errc::invalid_argument;
+ }
+ ret._fd=::open(path.u8string().c_str(),flags);
+ if(-1==ret._fd)
+ {
+ // Note that if we bail out here, ~file_handle() will correctly not call ::close()
+return{errno,std::system_category()};
+ }
+ if(-1==::fstat(ret._fd,&ret._stat))
+ {
+ // Note that if we bail out here, ~file_handle() will correctly call ::close()
+return{errno,std::system_category()};
+ }
+
+ // Returning ret directly is an area full of compiler specific behaviour quirks,
+// so be explicit by wrapping into an initialiser list with embedded move.
+return{std::move(ret)};
+}
+
The static member function implementing phase 2 firstly calls phase 1
+which puts the object into a legally destructible state. We then
+proceed to implement phase 2 of construction, filling in the various
+parts as we go, reporting via result any failures.
+
+
+
note
+
Remember that operator new has a non-throwing form, new(std::nothrow).
+
+
+
+
+
For the final return, in theory we could just return ret and
+depending on the C++ version currently in force, it might work
+via move, or via copy, or it might refuse to compile. You can
+of course type lots of boilerplate to be explicit, but this use
+via initialiser list is a reasonable balance of explicitness
+versus brevity, and it should generate minimum overhead code
+irrespective of compiler, C++ version, or any other factor.
The first thing to do is to break your object’s construction into two phases:
+
+
+
Place the object into a state where it can be legally destructed
+without doing any initialisation which could throw an exception (i.e. everything
+done in phase 1 is constexpr). This phase usually involves initialising member
+variables to various default values, most often using default member initialisers.
+Most standard C++ library objects
+and containers have constexpr constructors, and thus can be initialised
+during phase 1. If you need to initialise a member variable without
+a constexpr constructor,
+std::optional<T>
+ is the usual workaround.
+
+
Do the remainder of the construction, the parts which could fail.
+Because phase 1 placed the object into a legally destructible state,
+it is usually the case that one can bail out during phase 2 and the
+destructor will clean things up correctly.
+
+
+
The phase 1 construction will be placed into a privateconstexpr
+constructor so nobody external can call it. The phase 2 construction will be placed into a static
+member initialisation function which returns a result with either
+the successfully constructed object, or the cause of any failure to
+construct the object.
+
+
Finally, as a phase 3,
+some simple metaprogramming will implement a make<T>{Args...}()
+free function which will construct any object T by calling its
+static initialisation function with Args... and returning the
+result returned. This isn’t as nice as calling T(Args...) directly,
+but it’s not too bad in practice. And more importantly, it lets you
+write generic code which can construct any unknown object which
+fails via returning result, completely avoiding C++ exception throws.
Outcome provides multiple methods for user code to intercept various events which occur.
+The deepest method is simply to inherit from basic_result or basic_outcome, and override member functions,
+for which you will need to study the source code as that form of customisation is out of scope for this tutorial.
+
+
Another option is to supply a custom NoValuePolicy which can get you surprisingly
+far into customisation (see preceding section).
+
+
The final option, which this section covers, is to use the ADL discovered event hooks
+which tell you when a namespace-localised basic_outcome or basic_result has been:
One criticism often levelled against library-based exception throw alternatives is that they do
+not provide as rich a set of facilities as C++ exception throws. This section shows
+you how to configure Outcome, using the ADL event hooks, to take a stack backtrace on
+construction of an errored result<T, error_code>,
+and if that result<T, error_code> should ever be converted into an outcome<T, error_code, std::exception_ptr>,
+a custom std::exception_ptr will be just-in-time synthesised consisting of the std::system_error
+for the error code, plus an expanded message string containing the stack backtrace of where
+the error originally occurred.
+
+
One can see the use case for such a configuration where low-level, deterministic,
+fixed latency code is built with result, and it dovetails into higher-level
+application code built with outcome where execution time guarantees are not
+important, and thus where a malloc is okay. One effectively has constructed a
+“lazy indeterminism”, or “just-in-time indeterminism” mechanism for handling
+failure, but with all the rich information of throwing C++ exceptions.
In a previous section, we used the failure_info type to create
+the ADL bridge into the namespace where the ADL discovered outcome_throw_as_system_error_with_payload() function was to be found.
+
+
Here we do the same, but more directly by creating a thin clone of std::error_code
+into the local namespace. This ensures that this namespace will be searched by the
+compiler when discovering the event hooks.
+
+
namespaceerror_code_extended
+{
+ // Use the error_code type as the ADL bridge for the hooks by creating a type here
+// It can be any type that your localised result uses, including the value type but
+// by localising the error code type here you prevent nasty surprises later when the
+// value type you use doesn't trigger the ADL bridge.
+structerror_code:publicstd::error_code
+ {
+ // literally passthrough
+usingstd::error_code::error_code;
+ error_code()=default;
+ error_code(std::error_codeec)
+ :std::error_code(ec)
+ {
+ }
+ };
+
+ // Localise result and outcome to using the local error_code so this namespace gets looked up for the hooks
+template<classR>usingresult=BOOST_OUTCOME_V2_NAMESPACE::result<R,error_code>;
+ template<classR>usingoutcome=BOOST_OUTCOME_V2_NAMESPACE::outcome<R,error_code/*, std::exception_ptr */>;
+}
+
The final step is to add ADL discovered event hooks for the very specific case of
+when our localised outcome is copy or move constructed from our localised result.
+
+
You ought to be very careful that the noexcept-ness of these matches the noexcept-ness
+of the types in the outcome. You may have noticed that poke_exception() creates
+a std::string and appends to it. This can throw an exception. If the copy and/or
+move constructors of T, EC and EP are noexcept, then so will be outcome’s
+copy and/or move constructor. Thus if poke_exception() throws, instant program
+termination would occur, which is bad.
+
+
We avoid that problem in this case by wrapping poke_exception() in a try...catch
+which throws away any exceptions thrown.
+
+
namespaceerror_code_extended
+{
+ // Specialise the outcome copy and move conversion hook for when our localised result
+// is used as the source for copy construction our localised outcome
+template<classT,classU>inlinevoidhook_outcome_copy_construction(outcome<T>*res,constresult<U>&/*unused*/)noexcept
+ {
+ try
+ {
+ // when copy constructing from a result<T>, poke in an exception
+poke_exception(res);
+ }
+ catch(...)
+ {
+ // Do nothing
+}
+ }
+ template<classT,classU>inlinevoidhook_outcome_move_construction(outcome<T>*res,result<U>&&/*unused*/)noexcept
+ {
+ try
+ {
+ // when move constructing from a result<T>, poke in an exception
+poke_exception(res);
+ }
+ catch(...)
+ {
+ // Do nothing
+}
+ }
+}
+
We now tell Outcome that for every instance of our localised result<T>, that
+on failure construction only, we want custom code to be run which increments the current
+slot in TLS storage and writes the current stack backtrace into it.
+
+
namespaceerror_code_extended
+{
+ // Specialise the result construction hook for our localised result
+// We hook any non-copy, non-move, non-inplace construction, capturing a stack backtrace
+// if the result is errored.
+template<classT,classU>inlinevoidhook_result_construction(result<T>*res,U&&/*unused*/)noexcept
+ {
+ if(res->has_error())
+ {
+ // Grab the next extended info slot in the TLS
+extended_error_info&eei=mythreadlocaldata().next();
+
+ // Write the index just grabbed into the spare uint16_t
+BOOST_OUTCOME_V2_NAMESPACE::hooks::set_spare_storage(res,mythreadlocaldata().current-1);
+
+ // Capture a backtrace into my claimed extended info slot in the TLS
+eei.items=::backtrace(eei.backtrace.data(),eei.backtrace.size());
+ }
+ }
+}
+
Both result and outcome keep their internal state metadata in a uint32_t,
+half of which is not used by Outcome. As it can be very useful to keep a small
+unique number attached to any particular result or outcome instance, we
+permit user code to set those sixteen bits to anything they feel like.
+The corresponding function to retrieve those sixteen bits is uint16_t spare_storage(const basic_result|basic_outcome *) noexcept
+.
+
+
The state of the sixteen bits of spare storage are ignored during comparison operations.
+
+
The sixteen bits of spare storage propagate during the following operations:
+
+
+
Copy and move construction between result’s.
+
Copy and move construction between outcome’s.
+
Copy and move construction from a result to an outcome.
+
Converting copy and move constructions for all the above.
+
Assignment for all of the above.
+
+
+
They are NOT propagated in these operations:
+
+
+
Any conversion or translation which goes through a failure_type or success_type.
+
Any conversion or translation which goes through a ValueOrError concept match.
+
Any unpacking or repacking of value/error/exception e.g. a manual repack of an
+outcome into a result.
The first thing we are going to need is somewhere to store the stack backtrace.
+We could take the easier route and simply store it into an allocated block and
+keep the pointer as a custom payload in a result<T, std::pair<error_code, std::unique_ptr<stack_backtrace>>>
+(see previous section on Custom payloads). But let us assume that we care so deeply about bounded execution times
+that ever calling malloc is unacceptable.
+
+
We therefore are going to need some completely static and trivially typed storage
+perhaps kept per-thread to avoid the need to keep mutexes.
+
+
/* Outcome's hook mechanism works vis ADL, so we will need a custom namespace
+to ensure the hooks apply only to the types declared in this namespace only
+*/
+namespaceerror_code_extended
+{
+ // The extra error information we will keep
+structextended_error_info
+ {
+ std::array<void*,16>backtrace;// The backtrace
+size_titems;// Items in backtrace array which are valid
+};
+ structmythreadlocaldata_t
+ {
+ // Keep 16 slots of extended error info as a ringbuffer
+extended_error_infoslots[16];
+ // The current oldest slot
+uint16_tcurrent{0};
+
+ // Return the oldest slot
+extended_error_info&next(){returnslots[(current++)%16];}
+
+ // Retrieve a previously stored slot, detecting if it is stale
+extended_error_info*get(uint16_tidx)
+ {
+ // If the idx is stale, return not found
+if(idx-current>=16)
+ {
+ returnnullptr;
+ }
+ returnslots+(idx%16);
+ }
+ };
+
+ // Meyers' singleton returning a thread local data structure for this thread
+inlinemythreadlocaldata_t&mythreadlocaldata()
+ {
+ staticthread_localmythreadlocaldata_tv;
+ returnv;
+ }
+}
+
The extended error info is kept in a sixteen item long, thread local, ring buffer. We continuously
+increment the current index pointer which is a 16 bit value which will wrap after
+65,535. This lets us detect an attempt to access recycled storage, and thus return
+item-not-found instead of the wrong extended error info.
If you merely want result to capture stack backtraces without calling a memory allocator
+and retaining any triviality of copy which is important for optimisation,
+you already have everything you need.
+
+
But let’s keep going by intercepting any
+construction of our localised outcome from our localised result, retrieving any
+stored backtrace and using it to synthesise an exception ptr with a message text
+including the backtrace. Firstly let us look at the function which synthesises
+the exception ptr:
+
+
namespaceerror_code_extended
+{
+ // Synthesise a custom exception_ptr from the TLS slot and write it into the outcome
+template<classR>inlinevoidpoke_exception(outcome<R>*o)
+ {
+ if(o->has_error())
+ {
+ extended_error_info*eei=mythreadlocaldata().get(BOOST_OUTCOME_V2_NAMESPACE::hooks::spare_storage(o));
+ if(eei!=nullptr)
+ {
+ // Make a custom string for the exception
+std::stringstr(o->error().message());
+ str.append(" [");
+ structunsymbols// RAII cleaner for symbols
+{
+ char**_{nullptr};
+ ~unsymbols(){::free(_);}
+ }symbols{::backtrace_symbols(eei->backtrace.data(),eei->items)};
+ if(symbols._!=nullptr)
+ {
+ for(size_tn=0;n<eei->items;n++)
+ {
+ if(n>0)
+ {
+ str.append("; ");
+ }
+ str.append(symbols._[n]);
+ }
+ }
+ str.append("]");
+
+ // Override the payload/exception member in the outcome with our synthesised exception ptr
+BOOST_OUTCOME_V2_NAMESPACE::hooks::override_outcome_exception(o,std::make_exception_ptr(std::runtime_error(str)));
+ }
+ }
+ }
+}
+
If the localised outcome being constructed is errored, try fetching the TLS slot
+for the unique 16-bit value in its spare storage. If that is valid, symbolise the
+stack backtrace into a string and make an exception ptr with a runtime error with
+that string. Finally, override the payload/exception member in our just-copy-constructed
+localised outcome with the new exception ptr.
In this section, we always synthesise an exception ptr from the stored state and
+error code at the exact point of transition from result based APIs to outcome
+based APIs. This is acceptable only because we know that our code enforces that
+discipline.
+
+
If one were designing a library facility, one could not assume such discipline in the
+library user. One would probably be better off making the exception ptr synthesis
+lazy via a custom no-value policy which generates the stacktrace-containing error
+message only on demand e.g. .exception() observation, or a .value() observation
+where no value is available.
+
+
Such a design is however more indeterminate than the design presented in this section,
+because the indeterminacy is less predictable than in this design. Ultimately which
+strategy you adopt depends on how important absolute determinism is to your Outcome-based
+application.
This is the final section of the tutorial, and it is unavoidably quite lengthy
+as we are going to tie together all of the material covered in the tutorial
+so far into a single, unified, application of Outcome’s facilities.
+
+
One thing which Outcome solves – and which alternatives do not – is how to
+non-intrusively tie together multiple third party libraries, each using
+Outcome – or some other T|E implementatation like
+ P0323 std::expected<T, E>
+
+– with custom incommensurate E types, or indeed arbitrary return
+types which are “split” T|E return types. Solving
+this well is the coup de grâce of Outcome against alternative approaches
+to this problem domain,
+including std::expected<T, E>. It is the major reason why you should
+consider using Outcome over alternatives, including Expected.
+
+
Firstly we shall explore some of the problems faced by the software
+developer when T|E return type based code proliferates at scale,
+where dozens of libraries may be using completely incompatible T|E return types.
+
+
Secondly we shall introduce the ValueOrError concept support in Outcome,
+which implements a subset of the proposed WG21 ValueOrError
+concept framework.
+
+
Finally, we shall then step through a worked example which mocks up a realistic
+situation that the software developer may find themselves in: tying
+together disparate third party libraries, whose source code cannot be
+modified, into an application-wide, mixed-mode T|E and exception
+throwing universal error handling system which is capable of
+accurately representing the original failure, but also propagating it
+in a way that the application can deal with universally.
This is how you might now write application code using these three libraries:
+
+
namespaceapp
+{
+ // A markup function to indicate when we are ValueOrError converting
+template<classT>inlineoutcome<typenameT::value_type>ext(T&&v)
+ {//
+returnoutcome<typenameT::value_type>(std::move(v));
+ }
+
+ outcome<void>go()// NOT noexcept, this can throw STL exceptions e.g. bad_alloc
+{
+ // Note that explicit construction is required when converting between differing types
+// of outcome and result. This makes it explicit what you intend to do as conversion
+// may be a lot more expensive than moves.
+
+ // Try to GET this URL. If an unsuccessful HTTP status is returned, serialise a string
+// containing a description of the HTTP status code and the URL which failed, storing
+// that into a httplib_error exception type which is stored as an exception ptr. The
+// TRY operation below will return that exception ptr to be rethrown in the caller.
+// Otherwise the fetched data is returned in a std::string data.
+BOOST_OUTCOME_TRY(data,ext(httplib::get("http://www.nedproductions.biz/")));
+ string_viewdata_view(data);
+
+ // HTML tidy the fetched data. If the C library fails due to an error corresponding to
+// a standard library exception type, throw that. Otherwise, synthesise an exception
+// ptr of type tidylib_error which stores the error code returned in an error code with
+// generic category (i.e. errno domain).
+// TRY operation below will return that exception ptr to be rethrown in the caller.
+// Otherwise the tidied data is returned into holdmem, with the string view updated to
+// point at the tidied data.
+BOOST_OUTCOME_TRY(holdmem,ext(tidy_html(data_view)));
+
+ // Write the tidied data to some file. If the write fails, synthesise a filesystem_error
+// exception ptr exactly as if one called filelib::write_file(data_view).value().
+BOOST_OUTCOME_TRY(written,ext(filelib::write_file(data_view)));
+ returnsuccess();
+ }
+}// namespace app
+
The curiosity will be surely the ext() markup function, which needs
+explaining. It was felt
+important during Outcome’s design that ValueOrError conversions never
+be implicit, as they almost always represent a transition across an
+ABI or semantic boundary. They are also usually non-trivial to implement
+and compile, and it was felt important that the programmer ought to
+always mark the semantic boundary transition at the point of every use,
+as considerable amounts of code may execute.
+
+
How the end user chooses to mark up their code is up to them, however
+above we use a simple ext() function to mark up that the function
+being called is external to the application. This ticks our box of
+requiring the documentation, at the point of use, of every transition
+in failure handling boundaries.
+
+
Note that we are able to use TRY as normal throughout this function.
+Everything “just works”.
+
+
And most especially note that we never, at any stage, needed to modify
+the source code of httplib, tidylib nor filelib, nor inject
+custom things into their namespaces. This entire worked example was
+achieved solely by app based customisation points, and via convert.
+
+
+
Last revised: February 11, 2019 at 13:38:04 UTC
+
+
+
+
+
+
diff --git a/doc/html/tutorial/advanced/interop/app-map-filelib.html b/doc/html/tutorial/advanced/interop/app-map-filelib.html
new file mode 100644
index 00000000..c213b731
--- /dev/null
+++ b/doc/html/tutorial/advanced/interop/app-map-filelib.html
@@ -0,0 +1,70 @@
+
+
+Mapping the File I/O library into the Application - Boost.Outcome documentation
+
+
+
+
+
+
+
+
+
+
Mapping the File I/O library into the Application
+
To handle the File I/O library, once again we turn to custom ValueOrError
+converters:
+
+
// Inject custom ValueOrError conversion
+BOOST_OUTCOME_V2_NAMESPACE_BEGIN
+namespaceconvert
+{
+ // Provide custom ValueOrError conversion from filelib::result<U>
+// into any app::outcome<T>
+template<classT,classU>//
+structvalue_or_error<app::outcome<T>,filelib::result<U>>
+ {
+ // True to indicate that this converter wants `result`/`outcome`
+// to NOT reject all other `result`
+staticconstexprboolenable_result_inputs=true;
+ // False to indicate that this converter wants `outcome` to NOT
+// reject all other `outcome`
+staticconstexprboolenable_outcome_inputs=true;
+
+ template<classX,//
+typename=std::enable_if_t<std::is_same<filelib::result<U>,std::decay_t<X>>::value//
+&&std::is_constructible<T,U>::value>>//
+constexprapp::outcome<T>operator()(X&&src)
+ {
+ // Forward any successful value
+if(src.has_value())
+ {
+ return{std::forward<X>(src).value()};
+ }
+
+ // Synthesise a filesystem_error, exactly as if someone had
+// called src.value()
+auto&fi=src.error();
+ BOOST_OUTCOME_V2_NAMESPACE::try_throw_std_exception_from_error(fi.ec);// might throw
+return{std::make_exception_ptr(//
+filelib::filesystem_error(fi.ec.message(),std::move(fi.path1),std::move(fi.path2),fi.ec))};
+ }
+ };
+}// namespace convert
+BOOST_OUTCOME_V2_NAMESPACE_END
+
Note that the conversion exactly duplicates the implementation of
+throw_as_system_error_with_payload(failure_info fi) from
+namespace filelib. In a production implementation, you probably
+ought to call that function and catch the exception it throws
+into a pointer, as that would be more long term maintainable.
+
+
+
Last revised: February 11, 2019 at 13:38:04 UTC
+
+
+
+
+
+
diff --git a/doc/html/tutorial/advanced/interop/app-map-httplib1.html b/doc/html/tutorial/advanced/interop/app-map-httplib1.html
new file mode 100644
index 00000000..077a945f
--- /dev/null
+++ b/doc/html/tutorial/advanced/interop/app-map-httplib1.html
@@ -0,0 +1,97 @@
+
+
+Mapping the HTTP library into the Application <sup>1</sup>⁄<sub>2</sub> - Boost.Outcome documentation
+
+
+
+
+
+
+
+
+
+
Mapping the HTTP library into the Application 1/2
+
Firstly, remember that we are the application writer who has the problem of
+integrating three third party libraries into our application’s Outcome-based
+failure handling mechanism. We cannot modify those third party library
+sources; we must be non-intrusive.
+
+
We start by dealing with the HTTP library. We will integrate this
+into our application by wrapping up httplib::failure into a custom
+STL exception type. We then type erase it into an exception_ptr
+instance. Please note that this code is exclusively defined in the app namespace:
Most of the complexity in this code fragment is driven by the need to create
+some sort of descriptive string for std::runtime_error
+so its .what() returns a useful summary of the original failure. This
+is the main purpose of the app::make_httplib_exception() function.
+
+
(Note that if you have Reflection in your C++ compiler, it may be possible to script
+the conversion of enum values to string representations)
+
+
The only real thing to note about app::httplib_error is that it squirrels away
+the original httplib::failure in case that is ever needed.
+
+
+
Last revised: February 11, 2019 at 13:38:04 UTC
+
+
+
+
+
+
diff --git a/doc/html/tutorial/advanced/interop/app-map-httplib2.html b/doc/html/tutorial/advanced/interop/app-map-httplib2.html
new file mode 100644
index 00000000..39ee5787
--- /dev/null
+++ b/doc/html/tutorial/advanced/interop/app-map-httplib2.html
@@ -0,0 +1,94 @@
+
+
+Mapping the HTTP library into the Application <sup>2</sup>⁄<sub>2</sub> - Boost.Outcome documentation
+
+
+
+
+
+
+
+
+
+
Mapping the HTTP library into the Application 2/2
+
If you remember the tutorial section on the ValueOrError Concept,
+this is an example of how to implement a custom ValueOrError Concept converter
+in Outcome:
+
+
// Inject custom ValueOrError conversion
+BOOST_OUTCOME_V2_NAMESPACE_BEGIN
+namespaceconvert
+{
+ // Provide custom ValueOrError conversion from
+// httplib::result<U> into any app::outcome<T>
+template<classT,classU>//
+structvalue_or_error<app::outcome<T>,httplib::result<U>>
+ {
+ // False to indicate that this converter wants `result`/`outcome`
+// to NOT reject all other `result`
+staticconstexprboolenable_result_inputs=true;
+ // False to indicate that this converter wants `outcome` to NOT
+// reject all other `outcome`
+staticconstexprboolenable_outcome_inputs=true;
+
+ template<classX,//
+typename=std::enable_if_t<std::is_same<httplib::result<U>,std::decay_t<X>>::value//
+&&std::is_constructible<T,U>::value>>//
+constexprapp::outcome<T>operator()(X&&src)
+ {
+ // Forward any successful value, else synthesise an exception ptr
+returnsrc.has_value()?//
+app::outcome<T>{std::forward<X>(src).value()}//
+:
+ app::outcome<T>{app::make_httplib_exception(std::forward<X>(src))};
+ }
+ };
+}// namespace convert
+BOOST_OUTCOME_V2_NAMESPACE_END
+
The first thing that you should note is that these custom converters must be injected
+directly into the BOOST_OUTCOME_V2_NAMESPACE::convert namespace, and they must partially
+or completely specialise value_or_error<T, U>
+. Here we specialise the
+converter for ValueOrError conversions from httplib::result<U> to app::outcome<T>
+i.e. from our third party HTTP library’s error type into our application’s outcome
+type (which is unique to our application, as we hard code an app-local error type).
+
+
The second thing to note is that you need to set enable_result_inputs and enable_outcome_inputs
+appropriately, otherwise result and outcome inputs will not be matched by this
+converter1. In this converter, we really do wish to convert other result and
+outcome inputs, so we mark these booleans as true.
+
+
The third thing to note is the requirements on operator(). If the requirements are
+not met, the ValueOrError converting constructor in basic_result and basic_outcome
+disables. Note the requirement that the decayed operator() input X matches
+httplib::result<U>, and that T is constructible from U. This means that the
+explicit basic_result(ValueOrError<T, E> &&)
+ and explicit basic_outcome(ValueOrError<T, E> &&)
+
+constructors are available if, and only if, the input type is a httplib::result<U>,
+and the result’s value type is constructible from the input’s value type.
+
+
If operator() is available, it naturally converts a httplib::result<U> into an
+app::outcome<T> by either forwarding any success as-is, or calling app::make_httplib_exception()
+to type erase the httplib::failure into an app::httplib_error.
+
+
+
+
+
+
Here we refer to result and outcome as defined by this specific Outcome library. If result or outcome from another Outcome implementation is seen, those always must get parsed via the ValueOrError matching conversion framework.
+ [return]
+
+
+
+
+
Last revised: February 11, 2019 at 13:38:04 UTC
+
+
+
+
+
+
diff --git a/doc/html/tutorial/advanced/interop/app-map-tidylib.html b/doc/html/tutorial/advanced/interop/app-map-tidylib.html
new file mode 100644
index 00000000..f782aae6
--- /dev/null
+++ b/doc/html/tutorial/advanced/interop/app-map-tidylib.html
@@ -0,0 +1,66 @@
+
+
+Mapping the HTMLTidy library into the Application - Boost.Outcome documentation
+
+
+
+
+
+
+
+
+
+
Mapping the HTMLTidy library into the Application
+
Once again, we create a custom STL exception type to represent failure
+from the HTMLTidy library. We also create an app namespace wrapper
+for the C tidy_html() function which is more C++ friendly.
+
+
namespaceapp
+{
+ // Specialise an exception type for tidylib errors
+structtidylib_error:std::system_error
+ {
+ // passthrough
+usingstd::system_error::system_error;
+ tidylib_error()=default;
+ explicittidylib_error(intc)
+ :std::system_error(c,std::generic_category())
+ {
+ }
+ };
+
+ // Create a C++ invoking wrapper for the tidylib C API, modifying data with the returned data,
+// returing a unique_ptr to release storage on scope exit.
+structcall_free
+ {
+ template<classT>voidoperator()(T*p){::free(p);}
+ };
+ inlineoutcome<std::unique_ptr<char,call_free>>tidy_html(string_view&data)
+ {
+ char*out=nullptr;
+ size_toutlen=0;
+ interrcode=::tidy_html(&out,&outlen,data.data(),data.size());
+ if(errcode!=0)
+ {
+ // If the error code matches a standard STL exception, throw as that.
+BOOST_OUTCOME_V2_NAMESPACE::try_throw_std_exception_from_error(std::error_code(errcode,std::generic_category()));
+ // Otherwise wrap the error code into a tidylib_error exception throw
+returnstd::make_exception_ptr(tidylib_error(errcode));
+ }
+ // Reset input view to tidied html
+data=string_view(out,outlen);
+ // Return a unique ptr to release storage on scope exit
+returnstd::unique_ptr<char,call_free>(out);
+ }
+}// namespace app
+
The application is of course also based on Outcome, and like the HTTP library
+is also of mixed-failure design in that failure can be returned via error code,
+type erased exception_ptr or indeed a C++ exception throw.
+
+
// This is the namespace of the application which is connecting together the httplib,
+// filelib and tidylib libraries into a solution.
+namespaceapp
+{
+ // Create an ADL bridge so copy/move hooks will be searched for in this namespace
+structerror_code:publicstd::error_code
+ {
+ // passthrough
+usingstd::error_code::error_code;
+ error_code()=default;
+ error_code(std::error_codeec)
+ :std::error_code(ec)
+ {
+ }
+ };
+ // Localise an outcome implementation for this namespace
+template<classT>
+ usingoutcome=//
+BOOST_OUTCOME_V2_NAMESPACE::outcome<T,error_code/*, std::exception_ptr */>;
+ usingBOOST_OUTCOME_V2_NAMESPACE::success;
+}// namespace app
+
The way we are going to configure interop is as follows:
+
+
+
The application shall use error_code for anticipated failure and C++
+exception throws for unanticipated failure.
+
We shall choose the convention that app::outcome with exception ptr
+solely and exclusively represents a type erased failure from a third party
+library.
+
+
+
Thus if one calls .value() on an app::outcome, both anticipated failure
+within the app and type erased failure from a third party library shall be
+converted to a C++ exception throw.
This worked example was in fact excessively complex: a quicker route
+to achieving the same thing would be to add explicit converting constructors
+to app::error_code for each of the third party library E types.
+One then could have saved oneself with having to bother injecting
+custom converters into the BOOST_OUTCOME_V2_NAMESPACE::convert namespace.
+If you control your application’s E type, then that is probably a
+better, and certainly simpler, approach.
+
+
However there are occasions when you don’t have control over the
+implementation of the destination E type e.g. in callbacks. Outcome’s ValueOrError
+infrastructure lets you inject custom interop code for any pair
+of incommensurate third party E types, without needing to modify either’s
+source code.
+
+
This is without doubt a “power users” feature, but
+one which will prove useful as T|E based C++ code proliferates.
// You may remember this from the tutorial section on Custom Payloads
+namespacefilelib
+{
+ // Error code + paths related to a failure. Also causes ADL discovery
+// to check this namespace.
+structfailure_info
+ {
+ std::error_codeec;
+ pathpath1{},path2{};
+ };
+
+ // Tell Outcome that failure_info is to be treated as a std::error_code
+inlineconststd::error_code&make_error_code(constfailure_info&fi){returnfi.ec;}
+
+ // Tell Outcome that no-value observation should throw a custom exception
+inlinevoidoutcome_throw_as_system_error_with_payload(failure_infofi)
+ {
+ // If the error code is not filesystem related e.g. ENOMEM, throw that
+// as a standard STL exception.
+BOOST_OUTCOME_V2_NAMESPACE::try_throw_std_exception_from_error(fi.ec);
+ // Throw the exact same filesystem_error exception which the throwing
+// copy_file() edition does.
+throwfilesystem_error(fi.ec.message(),std::move(fi.path1),std::move(fi.path2),fi.ec);
+ }
+
+ // Localise a result implementation specific to this namespace.
+template<classT>usingresult=BOOST_OUTCOME_V2_NAMESPACE::result<T,failure_info>;
+
+ // Writes a chunk of data to some file. Returns bytes written, or
+// failure_info. Never throws exceptions.
+result<size_t>write_file(string_viewchunk)noexcept;
+}// namespace filelib
+
This uses the advanced Outcome feature of programming the lazy synthesis of
+custom C++ exception throws from a payload carrying E type called failure_info.
+Like the HTTP library, it too template aliases a localised result implementation
+into its namespace with ADL bridging so Outcome customisation points can be
+discovered.
Let us imagine a simple application: it fetches a HTTP page using a HTTP library,
+sends it through HTML tidy via the htmltidy library, and then writes it to disc
+using a filelib library. So three third party libraries, two using Outcome in
+incompatible ways, and the third being a C library just for kicks.
+
+
Let us imagine that the HTTP library has the following public interface:
+
+
// This is some standalone library implementing high level HTTP
+namespacehttplib
+{
+ // These are the error code that this HTTP library can return
+enumclassstatus_code
+ {
+ success=0,// not the HTTP success code of 200
+
+ // A subset of all HTTP status codes for brevity
+bad_request=400,
+ access_denied=401,
+ logon_failed=402,
+ forbidden=403,
+ not_found=404,
+ internal_error=500
+ };
+ // This is the error type that this HTTP library can return
+structfailure
+ {
+ status_codestatus{status_code::success};
+ std::stringurl{};// The failing URL
+};
+ // Localise a result implementation to this library, holding
+// the logic error of incorrect observation to mean program
+// termination.
+template<classT>
+ usingresult=//
+BOOST_OUTCOME_V2_NAMESPACE::result<T,failure,BOOST_OUTCOME_V2_NAMESPACE::policy::terminate>;
+
+ /* Performs a HTTP GET on the url, returning the body if successful,
+ a failure with status_code if unsuccessful at the HTTP level, or a
+ C++ exception throw if something catastrophic happened e.g. bad_alloc
+ */
+ result<std::string>get(std::stringurl);
+}// namespace httplib
+
The HTTP library is a mixed-failure design. Likely failures (HTTP status codes)
+are returned via httplib::failure, unlikely failures (e.g. out of memory)
+are returned via throw of the usual STL exception types.
+
+
The sole API we bother describing is an implementation of HTTP GET. It fetches
+a URL, and either returns the contents or the failure reason why not.
Back in the essential tutorial section on result, we studied a likely very common
+initial choice of E type: a strongly typed enum.
+We saw how by marking up strongly typed enums to tell the C++ standard library
+what they are, they gain implicit convertibility into std::error_code, and we
+then pointed out that you might as well now always set E = std::error_code, as that
+comes with the enormous advantage that you can use the boilerplate saving
+BOOST_OUTCOME_TRY macro when the E type is always the same.
+
+
We thus strongly recommend to users that for any given piece of code, always
+using the same E type across the codebase is very wise, except where you explicitly want
+to prevent implicit propagation of failure up a call stack e.g. local failures in
+some domain specific piece of code.
+
+
However it is unreasonable to expect that any non-trivial codebase can make do
+with E = std::error_code. This is why Outcome allows you to use custom E
+types which carry payload in addition to an error code, yet
+still have that custom type treated as if a std::error_code, including lazy custom exception
+throw synthesis.
+
+
All this is good, but if library A uses result<T, libraryA::failure_info>,
+and library B uses result<T, libraryB::error_info> and so on, there becomes
+a problem for the application writer who is bringing in these third party
+dependencies and tying them together into an application. As a general rule,
+each third party library author will not have built in explicit interoperation
+support for unknown other third party libraries. The problem therefore lands
+with the application writer.
+
+
The application writer has one of three choices:
+
+
+
In the application, the form of result used is result<T, std::variant<E1, E2, ...>>
+where E1, E2 … are the failure types for every third party library
+in use in the application. This has the advantage of preserving the original
+information exactly, but comes with a certain amount of use inconvenience
+and maybe excessive coupling between high level layers and implementation detail.
+
+
One can translate/map the third party’s failure type into the application’s
+failure type at the point of the failure
+exiting the third party library and entering the application. One might do
+this, say, with a C preprocessor macro wrapping every invocation of the third
+party API from the application. This approach may lose the original failure detail,
+or mis-map under certain circumstances if the mapping between the two systems
+is not one-one.
+
+
One can type erase the third party’s failure type into some application
+failure type, which can later be reconstituted if necessary. This is the cleanest
+solution with the least coupling issues and no problems with mis-mapping, but
+it almost certainly requires the use of malloc, which the previous two did not.
+
+
+
Things get even more complicated in the presence of callbacks. If in the
+callback you supply to library A, you call library B, you may need to insert
+switch statement maps or other mechanisms to convert library B’s failures into
+something library A can understand, and then somehow extract that out – preferably
+without loss of original information – into the application’s failure handling
+mechanism if library A subsequently returns failure as well. This implies
+transmitting state by which to track these interrelated pieces of failure data.
+
+
Let us see what Outcome can do to help the application writer address some of these
+issues, next.
// There actually is a library for tidying HTML into XHTML called HTMLTidy
+// See http://www.html-tidy.org/
+// HTMLTidy is actually a great tool for dealing with 1990s-era tag soup
+// HTML, I highly recommend it.
+
+// This isn't the API for Tidy, but let's assume it's a C library returning
+// errno domained error codes. out must be freed with free() after use.
+extern"C"inttidy_html(char**out,size_t*outlen,constchar*in,size_tinlen);
+
A C API may not initially appear to be a T|E based API, but if failure
+returns some domained error code and causes no other effects, and success
+returns some value, then it is effectively a “split” T|E API. The above
+is an example of exactly that form of “split” T|E API.
Outcome’s machinery for implementing ValueOrError conversion is user extensible by injection
+of specialisations of the value_or_error<T, U>
+ type into the BOOST_OUTCOME_V2_NAMESPACE::convert namespace.
+
+
Outcome’s default convert::value_or_error<T, U> implementation explicitly
+excludes Outcome result and outcome types from the default mechanism as
+there is a major gotcha: the ValueOrError matched type’s .value() is often
+not callable in constexpr as it can throw, which makes this conversion mechanism
+pretty much useless for constexpr code. Besides, outcome has a converting
+constructor overload for result inputs which is constexpr capable.
+
+
Note that if you do enable outcome inputs, a result will match an input
+outcome, but silently dropping any exception state. This is probably undesirable.
+
+
Examples of how to implement your own convert::value_or_error<T, U> converter
+is demonstrated in the worked example, next.
So far in this tutorial, type EC in result<T, EC> has always been a
+std::error_code or boost::system::error_code. With NoValuePolicy
+set to default_policy<T, EC, EP>
+, EC needs
+in fact to merely satisfy the trait
+is_error_code_available<T>
+
+for EC to be treated as if an error_code. Outcome specialises that
+trait for std::error_code and boost::system::error_code,
+hence they “just work”.
+
+
If no specialisation exists, trait::is_error_code_available<EC> is true
+if there exists some ADL discovered free function make_error_code(EC).
+
+
Thus, we can in fact use any custom EC type we like, including one carrying additional
+information, or payload. This payload can carry anything you like, and you can tell
+Outcome to do various things with that payload under various circumstances. For example:
+
+
+
If the user tries to observe an unsuccessful result, throw a custom exception
+containing the cause of failure with accompanying context from the payload.
+
If the user ever constructs an outcome from a payload carrying result,
+set the exception ptr in the constructed outcome to a custom exception
+containing the cause of the failure with accompanying context from the payload.
+
Transmit a stack backtrace specifying the exact point at which failure occurred,
+symbolising that backtrace into human readable text at the moment of conversion into human
+readable text.
+
Upon a namespace-localised result from library A being copy/moved into a
+namespace-localised result from C bindings library B, set the C errno if
+the error code and category map onto the errno domain.
+
+
+
There are many, many other options of course. This tutorial can only cover a
+reasonable subset. This section covers Example 1 above, throwing custom exceptions
+with payload upon observation of an unsuccessful result.
Something which has long annoyed the purists in the C++ leadership is the problem of dual
+overloads in error_code capable standard library APIs.
+
+
Consider the
+copy_file()
+API from the Filesystem TS:
+
+
namespacefilesystem
+{
+ /*! Copies the file at path `from` to path `to`.
+ \returns True if file was successfully copied.
+ \throws On failure throws `filesystem_error(ec.message(), from, to, ec)` with
+ `ec` being the error code reported by the operating system.
+ */
+ boolcopy_file(constpath&from,constpath&to);
+
+ /*! Copies the file at path `from` to path `to`.
+ \returns True if file was successfully copied. If false, `ec` is written with
+ the error code reported by the operating system.
+ \throws May throw an exception if there is some "catastrophic" failure
+ e.g. failure to allocate memory.
+ */
+ boolcopy_file(constpath&from,constpath&to,std::error_code&ec);
+}
+
Before Outcome, the common design pattern was to provide throwing and non-throwing overloads
+of every API. As you can see above, the throwing API throws a filesystem::filesystem_error
+exception type which carries additional information, specifically two paths. These paths may
+refer to the files which were the source of any failure. However the non-throwing overload
+does not provide this additional information, which can make it more annoying to use the
+non-throwing overload sometimes.
+
+
What if we could replace these two overloads of every API in the Filesystem TS with a single API,
+and additionally have the non-throwing edition return the exact same additional information
+as the throwing edition?
An Outcome based solution to the dual overload problem is straightforward:
+
+
namespacefilesystem2
+{
+ // Error code + paths related to a failure. Also causes ADL discovery to check this namespace.
+structfailure_info
+ {
+ std::error_codeec;
+ pathpath1,path2;
+ };
+
+ // Tell Outcome that failure_info is to be treated as a std::error_code
+inlineconststd::error_code&make_error_code(constfailure_info&fi){returnfi.ec;}
+
+ // Localise an outcome implementation specific to this namespace. Normally would just
+// be `result`, but for clarity we'll use `fs_result`.
+template<classT>usingfs_result=outcome::result<T,failure_info>;
+
+ /*! Copies the file at path `from` to path `to`.
+ \returns Successful if file was successfully copied, otherwise the error code reported
+ by the operating system plus a payload of the paths involved.
+ \throws Never throws.
+ */
+ fs_result<void>copy_file(constpath&from,constpath&to)noexcept;
+}
+
Starting at the bottom, there is now a single copy_file() function which returns a fs_result<void>.
+As result is either successful or not, there is no longer any point in returning a boolean, so we
+simply return void on success. On failure, as the template alias fs_result<T> above it shows,
+we are returning a failure_info structure containing an error code and the same additional information
+as filesystem_error provides.
+
+
It is important to note that the fact that failure_info is defined in namespace filesystem2 is very
+important. This is because Outcome uses Argument Dependent Lookup (ADL)
+to find the make_error_code()
+function, as well as other customisation point free functions. In other words, only the namespaces as
+defined by ADL are searched when finding a free function telling us what to do for failure_info,
+which includes the namespace failure_info is declared into.
Something not mentioned at all until now (and properly described in the next
+section, Default actions) is that Outcome can be
+programmed take various actions when the user tries to observe .value()
+when there is no value, and so on for the other possible state observations.
+
+
Seeing as we are replacing the throwing overload of copy_file() in the
+Filesystem TS with a result returning edition instead, it would make
+sense if an attempt to observe the value of an unsuccessful fs_result
+threw the exact same filesystem_error as the Filesystem TS does.
+
+
Telling Outcome how to throw a filesystem_error with payload of the
+failing paths is easy:
+
+
namespacefilesystem2
+{
+ // If we would like Outcome to do something other than the default action (see next
+// section), we can declare this ADL discovered free function to customise what
+// to do instead.
+//
+// Note that rvalue semantics are propagated internally by Outcome, so if the user
+// called .value() on a rvalued result, failure_info will be moved rather than
+// copied from the result. That means we can overload once with value semantics,
+// and not need to overload for lvalue and rvalue situations unless we really feel
+// we need to for some reason.
+inlinevoidoutcome_throw_as_system_error_with_payload(failure_infofi)
+ {
+ // If the error code is not filesystem related e.g. ENOMEM, throw that as a
+// standard STL exception.
+outcome::try_throw_std_exception_from_error(fi.ec);
+ // Throw the exact same filesystem_error exception which the throwing copy_file()
+// edition does.
+throwfilesystem_error(fi.ec.message(),std::move(fi.path1),//
+std::move(fi.path2),fi.ec);
+ }
+}
+
On standalone Outcome only, as patches and modifications are applied to this library,
+namespaces get permuted in order to not to cause binary incompatibility. At some point
+namespace outcome_v2 will be defined, and this will be the preferred namespace.
+Until then BOOST_OUTCOME_V2_NAMESPACE denotes the most recently
+updated version, getting closer to outcome_v2.
+
+
On Boost.Outcome only, as Boost provides no binary compatibility across releases,
+BOOST_OUTCOME_V2_NAMESPACE always expands into boost::outcome_v2.
+
+
Online compilers
+
+
If you’ve never used them before, you will find
+Godbolt and Wandbox invaluable.
+These let you play with C++ inside your web browser.
+
+
Most of the source code snippets in Outcome have a link in their top right to
+the original source code on github. You can copy and paste this source code into
+Godbolt (if you wish to study the assembler generated) or Wandbox (if you
+wish to run the program).
+
+
Godbolt
+
+
Godbolt is invaluable for visualising online the assembler generated for a
+piece of C++, for all the major compilers and CPU architectures.
+
+
Standalone Outcome is built into Godbolt! In the right hand pane toolbar, click the
+libraries dropdown (currently third from the right, looks like a book), find
+Outcome and choose the version you want.
+
+
After this is selected, you can #include any of these editions of Outcome:
+
+
+
<outcome-basic.hpp>
+
An inclusion of basic_outcome.hpp + try.hpp which includes as few
+ system headers as possible in order to give an absolute minimum compile time
+ impact edition of Outcome. See https://github.com/ned14/stl-header-heft.
+
+
<outcome-experimental.hpp>
+
An inclusion of experimental/status_outcome.hpp + try.hpp which
+ is the low compile time impact of the basic edition combined with
+ status_code from https://ned14.github.io/status-code/. If you are on an
+ embedded system where binary bloat must be absolutely avoided, and don't
+ mind the potentially unstable status_code, this is definitely the edition
+ for you.
+
+
<outcome.hpp>
+
An inclusion of outcome.hpp which brings in all the specialisations
+ for the std STL types, plus iostreams support. If you don't know which
+ edition to use, you should use this one, it ought to "just work".
Wandbox lets you place a third party header into a separate tab. It also
+comes with a recent Boost libraries. Either technique can be used to
+explore Outcome.
You now know everything you need to get started with using Outcome
+immediately.
+
+
The initial temptation for most beginners will be to use a bespoke
+strongly typed enumeration on a case by case basis i.e. a “once off”
+custom E type. This is usually due to experience in other languages
+with sum types e.g. Rust, Haskell, Swift etc.
+
+
However this is C++! Not Rust, not Swift, not Haskell! I must caution you to always avoid using
+custom E types in public APIs. The reason is that every time
+library A using custom E1 type must interface with library B
+using custom E2 type, you must map between those E1 and E2
+types.
+
+
This is information lossy, i.e. fidelity of failure gets lost
+after multiple translations. It involves writing, and then
+maintaining, a lot of annoying boilerplate. It leaks internal
+implementation detail, and fails to separate concerns. And one
+cannot use BOOST_OUTCOME_TRYV(expr)/BOOST_OUTCOME_TRY(expr)
+
+if there is no convertibility between E types.
+
+
The C++ 11 standard library, and Boost,
+specifically ships <system_error> for the purpose of wrapping up
+individual custom E types into a generic framework, where disparate
+custom E types can discover and interact with one another.
+That ships with every C++ compiler.
+
+
For all these reasons, this is why result and outcome default
+the EC type to error code. You should leave that default alone
+where possible.
In the previous section we have seen that it would be useful if calling member
+function .value() on object of type outcome<T> that did not contain a value,
+would cause an exception to be thrown according to some user-defined policy.
+
+
Let us consider result<T> first. It is an alias to basic_result<T, E, NoValuePolicy>
+,
+where E is the type storing error information and defaulted to
+std::error_code/boost::system::error_code, and NoValuePolicy
+is a no-value policy defaulted to default_policy<T, EC, EP>
+.
+
+
The semantics of basic_result::value() are:
+
+
+
Calls NoValuePolicy::wide_value_check(*this).
+
Return a reference to the contained value. If no value is actually stored,
+your program has entered undefined behaviour.
+
+
+
Thus, the semantics of function .value() depend on the no-value policy. The
+default policy (policy::default_policy<T, EC, void>) for EC of type
+std::error_code1 does the following:
+
+
+
If r.has_value() == false throws exception std::system_error{r.error()},
never use exceptions. Any exception-related logic is provided exclusively
+through no-value policies.
+
+
+
+
+
When designing your own success-or-failure type using templates
+basic_result<> or basic_outcome<> you have to decide what no-value policy
+you want to use. Either create your own, or use one of the predefined policies.
+
+
You can also use one of the two other predefined aliases for basic_result<>:
If there is an observation of a value/error/exception which is not present,
+the program is put into a hard undefined behaviour situation. The
+compiler literally compiles no code for an invalid observation – the
+CPU “runs off” into the unknown.
+
+
As bad as this may sound, it generates the most optimal code, and such
+hard UB is very tool-friendly for detection e.g. undefined behaviour
+sanitiser, valgrind memcheck, etc.
Upon missing value observation throws bad_result_access_with<EC>(ec),
+where ec is the value of the stored error. If error is not stored,
+the behaviour is undefined.
+
+
Upon missing error observation throws bad_result_access("no error").
+
+
This policy can be used with basic_outcome<> instances, where it always
+throws bad_outcome_access for all no-value/error/exception observations.
+
+
Note that checked<T, E = varies>
+ aliases a basic_result
+with the throw_bad_result_access<EC> no-value policy.
If you want your basic_outcome<> or basic_result<> instances to call
+std::abort() whenever .value() is called on an object that does not contain a value, or .error() is called on an object that does not contain an error, you will need to define your own no-value policy as follows:
All policies ought to inherit from base
+ in order to provide your policy implementation with
+the internal policy API for accessing and manipulating result and outcome state.
+
+
Once the policy is defined, you have to specify it when providing your own
+basic_outcome specialization:
Type outcome<T, EC = varies, EP = varies, NoValuePolicy = policy::default_policy<T, EC, EP>>
+ represents either a successfully computed value of type T, or one or two reasons for failure. Failure can be represented by EC, or EP, or both, although usually it will either be an EC or an EP.
+Similarly to result, EC defaults to std::error_code/boost::system::error_code, and EP defaults to std::exception_ptr/boost::exception_ptr.
+
+
The distinction is made into two types, EC and EP:
EP represents an unrecoverable failure where a C++ exception would ordinarily have been thrown. This is usually a pointer to an exception throw.
+
+
+
It should be emphasised that this distinction is by convention only, but it will be confusing to your
+users if you deviate significantly from this convention.
+
+
+
+
Legacy codebases
+
+
outcome is useful for transporting exceptions across layers of the program that were never designed with exception safety in mind.
+
+
Consider a program consisting of three layers:
+
+
+
+
+
The highest-level layer, Layer3, uses exceptions for signalling failures. The middle layer, Layer2_old,
+was not designed with exception safety in mind and functions need to return information about failures in return value.
+But down in the implementation details, in Layer1, another library is used that again throws exceptions. The goal is
+to be able to transfer an exception thrown in Layer1 through Layer2_old, which is not exception-safe,
+and be able to rethrow it in Layer3.
+
+
In Layer1 we have two functions from two libraries: one reports failures by throwing exceptions, the other by returning result<>:
+
+
autof()->int;// throws on failure
+autog()noexcept->outcome::result<int>;
+
In Layer2_old we cannot use exceptions, so its function h uses return type outcome<> to report failures. It is using functions f and g and reports their failures inside outcome<>:
#1. Operator TRY can forward failures encoded in result<T, EC> as outcome<T, EC, EP> without any loss in information. You can also use TRY to forward failure from one outcome<> to another.
+
+
#2. You can store the current exception through std::exception_ptr inside outcome<T, EC, EP> without any loss in information
+ (provided that EP is std::exception_ptr).
Continuing with the previous example, in Layer3 we have function z which again reports failures via exceptions.
+It will call function h from Layer2_old which returns outcome<int> (which may store a double or an std::error_code or an std::exception_ptr).
+The goal is to unpack it to either the successful return value int or to throw an appropriate exception: if we are storing an std::exception_ptr just rethrow it.
+If we are storing an std::error_code throw it as std::system_error, which is designed to store std::error_code’s:
Function has_exception checks if it is EP (std::exception_ptr) that is stored, function exception accesses it. Similarly, function error accesses the EC (std::error_code) if it is stored.
+outcome<> also has a function has_failure to check if either EC or EP is being stored.
+
+
It would seem obvious that the above pattern of “unpacking” outcome<>
+is so common that it ought to be implemented inside function .value(),
+so function z could be written as:
+
returnold::h().value();
+
+
And this is exactly what the aforementioned no-value policy template argument is for, which is described in
+the next section.
+
+
+
Last revised: February 08, 2019 at 22:18:08 UTC
+
+
+
+
+
+
diff --git a/doc/html/tutorial/essential/outcome/layer_chart.gif b/doc/html/tutorial/essential/outcome/layer_chart.gif
new file mode 100644
index 00000000..54bd3fcc
Binary files /dev/null and b/doc/html/tutorial/essential/outcome/layer_chart.gif differ
diff --git a/doc/html/tutorial/essential/result.html b/doc/html/tutorial/essential/result.html
new file mode 100644
index 00000000..f3a40edc
--- /dev/null
+++ b/doc/html/tutorial/essential/result.html
@@ -0,0 +1,119 @@
+
+
+result<> - Boost.Outcome documentation
+
+
+
+
+
+
+
+
+
+
+
result<>
+
We will define a function that converts a std::string to an int. This function can fail for a number of reasons;
+if it does we want to communicate the failure reason.
Template alias result<T, E = varies, NoValuePolicy = policy::default_policy<T, E, void>>
+
+has three template parameters, but the last two have default values. The first
+(T) represents the type of the object returned from the function upon success.
+The second (EC) is the type of object containing information about the reason
+for failure when the function fails. A result object stores either a T or an
+EC at any given moment, and is therefore conceptually similar to variant<T, EC>.
+EC is defaulted to std::error_code in standalone Outcome, or to boost::system::error_code
+in Boost.Outcome1. The third parameter (NoValuePolicy) is called a
+no-value policy. We will cover it later.
+
+
If both T and EC are trivially copyable, result<T, EC, NVP> is also trivially copyable.
+Triviality, complexity and constexpr-ness of each operation (construction, copy construction, assignment,
+destruction etc) is always the intersection of the corresponding operation in T and EC,
+so for example if both T and EC are literal types, so will be result<T, EC, NVP>.
+Additionally, if both T and EC have standard layout, result<T, EC, NVP> has standard layout;
+thus if both T and EC are C-compatible, so will result<T, EC, NVP> be C-compatible.
+
+
Now, we will define an enumeration describing different failure situations during conversion.
+
+
enumclassConversionErrc
+{
+ Success=0,// 0 should not represent an error
+EmptyString=1,// (for rationale, see tutorial on error codes)
+IllegalChar=2,
+ TooLong=3,
+};
+
+// all boilerplate necessary to plug ConversionErrc
+// into std::error_code framework
+
result<T, EC> is convertible from any T2 convertible to T as well as any EC2 convertible to EC,
+provided that there is no constructability possible in either direction between T and EC. If there is,
+all implicit conversion is disabled, and you will need to use one of the tagged constructors:
The type result<void> means that there is no value to be returned upon success, but that the operation might still fail, and we may be interested in inspecting the cause of the failure. The class template result<> is declared with the attribute [[nodiscard]], which means the compiler will warn you if you forget to inspect the returned object (in C++ 17 or later).
+
+
The implementation will do the following: if the integral number can be represented by an int, we will convert to int and use its arithmetical operations. If the number is too large, we will fall back to using a custom BigInt implementation that needs to allocate memory. In the implementation we will use the function convert defined in the previous section.
#1. You test if result<> object represents a successful operation with contextual conversion to bool.
+
+
#2. The function .value() extracts the successfully returned int.
+
+
#3. The function .error() allows you to inspect the error sub-object, representing information about the reason for failure.
+
+
#4. Macro BOOST_OUTCOME_TRY represents a control statement. It implies that the expression in the second argument returns a result<>. The function is defined as:
Our control statement means: if fromString returned failure, this same error information should be returned from print_half, even though the type of result<> is different. If fromString returned success, we create variable i of type BigInt with the value returned from fromString. If control goes to subsequent line, it means fromString succeeded and variable of type BigInt is in scope.
+
+
#5. In the return statement we extract the error information and use it to initialize the return value from print_half. We could have written return r.error(); instead,
+ and it would have the same effect, but r.as_failure() will work when implicit construction from E has been disabled due to T and E having a constructibility relationship.
+
+
#6. Function success() returns an object of type success<void> representing success. This is implicitly converted by
+all result and outcome types into a successful return, default constructing any T if necessary.
The BOOST_OUTCOME_TRY macro uses C macro overloading to select between two implementations based on the number of
+input parameters. If there is exactly one input parameter i.e. without the i, the control statement is
+roughly equivalent to:
So here i as the first C macro parameter is set to the value of any successful result.
+
+
C macro overloads are provided for up to eight arguments. To prevent the
+confounding of the C preprocessor by commas in template specifications causing more than
+eight arguments appearing to the C preprocessor, you should consider wrapping the
+second argument in brackets.
+
+
+
+
Compiler-specific extension: BOOST_OUTCOME_TRYX
+
+
+
note
+
This macro makes use of a proprietary extension in GCC and clang, and is not
+portable. The macro is not made available on unsupported compilers,
+so you can test for its presence using #ifdef BOOST_OUTCOME_TRYX.
+
+
+
+
+
GCC and Clang provide an extension to C++ known as
+statement expressions.
+These make it possible to use a more convenient macro: BOOST_OUTCOME_TRYX, which is an expression. With the above macro, the above declaration of variable i can be rewritten to:
Outcome has been presented at some of the major C++ conferences as it has
+evolved. As the older content is less relevant to Outcome today, this
+list is given in reverse chronological order.
+
+
+
+
Dublin C++ users group 2018 “Deterministic Disappointment”
+
+
Literature review of the WG21 papers relating to deterministically handling failure, and using libraries such as Outcome to implement the same.
+
+
+
+
+
+
+
+
+
+
+
+
Meeting C++ 2017 “Introduction to proposed std::expected<T, E>“
+
+
Literature review of the several WG21 papers relating to std::expected.
+
+
+
+
+
+
+
+
+
+
+
+
ACCU 2017 “Mongrel Monads, Dirty, dirty, dirty”
+
+
Covers the history of error handling in C++, and how the LEWG Expected works.
+
+
(Note that the Expected presented here no longer exists, it was substantially changed
+after the Outcome v1 peer review. Furthermore the Outcome presented here no longer
+exists, the peer review demanded a complete rebuild)
+
+
+
+
+
+
+
+
+
+
+
+
Last revised: September 20, 2018 at 09:21:47 +0100
+ 
+ 
+
+ 
+
+ 
+
+ 
+
+ 1123 commits
+ 
+
+ 45 commits
+ 
+
+ 9 commits
+ 
+
+ 7 commits
+ 
+
+ 2 commits
+ 
+
+ 2 commits
+ 
+
+ 2 commits
+ 
+
+ 1 commits
+ 
+
+ 1 commits
+ 
+
+ 1 commits
+ 
+
+ 1 commits
+ 
+
+ 1 commits
+ 
+
+ 1 commits
+ 
+ 
+ 
+ 