8370 lines
323 KiB
HTML
8370 lines
323 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<meta name="generator" content="Asciidoctor 1.5.8">
|
||
<meta name="author" content="Lightweight Error Augmentation Framework written in C++11 | Emil Dotchevski">
|
||
<title>LEAF</title>
|
||
<link rel="stylesheet" href="./zajo-dark.css">
|
||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
|
||
<meta name="keywords" content="c++,error handling,open source">
|
||
<meta name="description" content="Lightweight Error Augmentation Framework">
|
||
<link rel="stylesheet" href="./zajo-light.css" disabled=true>
|
||
<script>
|
||
function switch_style()
|
||
{
|
||
var i, tag;
|
||
for( i=0, tag=document.getElementsByTagName("link"); i<tag.length; i++ )
|
||
if( tag[i].rel.indexOf("stylesheet")!=-1 && tag[i].href.includes("zajo-") )
|
||
tag[i].disabled = !tag[i].disabled;
|
||
}
|
||
</script>
|
||
</head>
|
||
<body class="article toc2 toc-left">
|
||
<div id="header">
|
||
<h1>LEAF<div style="z-index: 3; bottom:-16px; right:4px; position:fixed"><input width="32" height="32" type="image" alt="Skin" src="./skin.png" onclick="this.blur();switch_style();return false;"/></div></h1>
|
||
<div class="details">
|
||
<span id="author" class="author">Lightweight Error Augmentation Framework written in C++11 | Emil Dotchevski</span><br>
|
||
</div>
|
||
<div id="toc" class="toc2">
|
||
<div id="toctitle"></div>
|
||
<ul class="sectlevel1">
|
||
<li><a href="#_abstract">Abstract</a></li>
|
||
<li><a href="#support">Support</a></li>
|
||
<li><a href="#portability">Portability</a></li>
|
||
<li><a href="#distribution">Distribution</a></li>
|
||
<li><a href="#introduction">Five Minute Introduction</a>
|
||
<ul class="sectlevel2">
|
||
<li><a href="#introduction-result"><code>noexcept</code> API</a></li>
|
||
<li><a href="#introduction-eh">Exception-Handling API</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#tutorial">Tutorial</a>
|
||
<ul class="sectlevel2">
|
||
<li><a href="#tutorial-model">Error Communication Model</a>
|
||
<ul class="sectlevel3">
|
||
<li><a href="#_noexcept_api"><code>noexcept</code> API</a></li>
|
||
<li><a href="#_exception_handling_api">Exception-Handling API</a></li>
|
||
<li><a href="#tutorial-interoperability">Interoperability</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#tutorial-loading">Loading of Error Objects</a></li>
|
||
<li><a href="#tutorial-on_error">Using <code>on_error</code></a></li>
|
||
<li><a href="#tutorial-predicates">Using Predicates to Handle Errors</a></li>
|
||
<li><a href="#tutorial-binding_handlers">Binding Error Handlers in a <code>std::tuple</code></a></li>
|
||
<li><a href="#tutorial-async">Transporting Error Objects Between Threads</a>
|
||
<ul class="sectlevel3">
|
||
<li><a href="#tutorial-async_result">Using <code>result<T></code></a></li>
|
||
<li><a href="#tutorial-async_eh">Using Exception Handling</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#tutorial-classification">Classification of Failures</a></li>
|
||
<li><a href="#tutorial-exception_to_result">Converting Exceptions to <code>result<T></code></a></li>
|
||
<li><a href="#tutorial-on_error_in_c_callbacks">Using <code>error_monitor</code> to Report Arbitrary Errors from C-callbacks</a></li>
|
||
<li><a href="#tutorial-diagnostic_information">Diagnostic Information</a></li>
|
||
<li><a href="#tutorial-std_error_code">Working with <code>std::error_code</code>, <code>std::error_condition</code></a>
|
||
<ul class="sectlevel3">
|
||
<li><a href="#_introduction">Introduction</a></li>
|
||
<li><a href="#_support_in_leaf">Support in LEAF</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#tutorial-boost_exception_integration">Boost Exception Integration</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#examples">Examples</a></li>
|
||
<li><a href="#synopsis">Synopsis</a>
|
||
<ul class="sectlevel2">
|
||
<li><a href="#synopsis-reporting">Error Reporting</a>
|
||
<ul class="sectlevel3">
|
||
<li><a href="#error.hpp"><code>error.hpp</code></a></li>
|
||
<li><a href="#common.hpp"><code>common.hpp</code></a></li>
|
||
<li><a href="#result.hpp"><code>result.hpp</code></a></li>
|
||
<li><a href="#on_error.hpp"><code>on_error.hpp</code></a></li>
|
||
<li><a href="#exception.hpp"><code>exception.hpp</code></a></li>
|
||
<li><a href="#_capture_hpp"><code>capture.hpp</code></a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#tutorial-handling">Error Handling</a>
|
||
<ul class="sectlevel3">
|
||
<li><a href="#context.hpp"><code>context.hpp</code></a></li>
|
||
<li><a href="#handle_errors.hpp"><code>handle_errors.hpp</code></a></li>
|
||
<li><a href="#pred.hpp"><code>pred.hpp</code></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#functions">Reference: Functions</a>
|
||
<ul class="sectlevel2">
|
||
<li><a href="#activate_context"><code>activate_context</code></a></li>
|
||
<li><a href="#capture"><code>capture</code></a></li>
|
||
<li><a href="#context_type_from_handlers"><code>context_type_from_handlers</code></a></li>
|
||
<li><a href="#current_error"><code>current_error</code></a></li>
|
||
<li><a href="#exception"><code>exception</code></a></li>
|
||
<li><a href="#exception_to_result"><code>exception_to_result</code></a></li>
|
||
<li><a href="#make_context"><code>make_context</code></a></li>
|
||
<li><a href="#make_shared_context"><code>make_shared_context</code></a></li>
|
||
<li><a href="#new_error"><code>new_error</code></a></li>
|
||
<li><a href="#on_error"><code>on_error</code></a></li>
|
||
<li><a href="#try_catch"><code>try_catch</code></a></li>
|
||
<li><a href="#try_handle_all"><code>try_handle_all</code></a></li>
|
||
<li><a href="#try_handle_some"><code>try_handle_some</code></a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#types">Reference: Types</a>
|
||
<ul class="sectlevel2">
|
||
<li><a href="#context"><code>context</code></a>
|
||
<ul class="sectlevel3">
|
||
<li><a href="#context::context">Constructors</a></li>
|
||
<li><a href="#context::activate"><code>activate</code></a></li>
|
||
<li><a href="#context::deactivate"><code>deactivate</code></a></li>
|
||
<li><a href="#context::handle_error"><code>handle_error</code></a></li>
|
||
<li><a href="#context::is_active"><code>is_active</code></a></li>
|
||
<li><a href="#context::print"><code>print</code></a></li>
|
||
<li><a href="#context::propagate"><code>propagate</code></a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#context_activator"><code>context_activator</code></a></li>
|
||
<li><a href="#diagnostic_info"><code>diagnostic_info</code></a></li>
|
||
<li><a href="#error_id"><code>error_id</code></a>
|
||
<ul class="sectlevel3">
|
||
<li><a href="#error_id::error_id">Constructors</a></li>
|
||
<li><a href="#is_error_id"><code>is_error_id</code></a></li>
|
||
<li><a href="#error_id::load"><code>load</code></a></li>
|
||
<li><a href="#error_id::comparison_operators"><code>operator==</code>, <code>!=</code>, <code><</code></a></li>
|
||
<li><a href="#error_id::operator_bool"><code>operator bool</code></a></li>
|
||
<li><a href="#error_id::to_error_code"><code>to_error_code</code></a></li>
|
||
<li><a href="#error_id::value"><code>value</code></a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#error_monitor"><code>error_monitor</code></a></li>
|
||
<li><a href="#e_api_function"><code>e_api_function</code></a></li>
|
||
<li><a href="#e_at_line"><code>e_at_line</code></a></li>
|
||
<li><a href="#e_errno"><code>e_errno</code></a></li>
|
||
<li><a href="#e_file_name"><code>e_file_name</code></a></li>
|
||
<li><a href="#e_LastError"><code>e_LastError</code></a></li>
|
||
<li><a href="#e_source_location"><code>e_source_location</code></a></li>
|
||
<li><a href="#e_type_info_name"><code>e_type_info_name</code></a></li>
|
||
<li><a href="#error_info"><code>error_info</code></a></li>
|
||
<li><a href="#polymorphic_context"><code>polymorphic_context</code></a></li>
|
||
<li><a href="#result"><code>result</code></a>
|
||
<ul class="sectlevel3">
|
||
<li><a href="#result::result">Constructors</a></li>
|
||
<li><a href="#result::error"><code>error</code></a></li>
|
||
<li><a href="#result::load"><code>load</code></a></li>
|
||
<li><a href="#result::operator_eq"><code>operator=</code></a></li>
|
||
<li><a href="#result::operator_bool"><code>operator bool</code></a></li>
|
||
<li><a href="#result::value"><code>value</code>, <code>operator*</code>, <code>-></code></a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#verbose_diagnostic_info"><code>verbose_diagnostic_info</code></a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#predicates">Reference: Predicates</a>
|
||
<ul class="sectlevel2">
|
||
<li><a href="#catch_"><code>catch_</code></a></li>
|
||
<li><a href="#if_not"><code>if_not</code></a></li>
|
||
<li><a href="#match"><code>match</code></a></li>
|
||
<li><a href="#match_member"><code>match_member</code></a></li>
|
||
<li><a href="#match_value"><code>match_value</code></a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#traits">Reference: Traits</a>
|
||
<ul class="sectlevel2">
|
||
<li><a href="#is_predicate"><code>is_predicate</code></a></li>
|
||
<li><a href="#is_result_type"><code>is_result_type</code></a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#macros">Reference: Macros</a>
|
||
<ul class="sectlevel2">
|
||
<li><a href="#_boost_leaf"><code>BOOST_LEAF_</code></a>
|
||
<ul class="sectlevel3">
|
||
<li><a href="#BOOST_LEAF_ASSIGN"><code>ASSIGN</code></a></li>
|
||
<li><a href="#BOOST_LEAF_AUTO"><code>AUTO</code></a></li>
|
||
<li><a href="#BOOST_LEAF_CHECK"><code>CHECK</code></a></li>
|
||
<li><a href="#BOOST_LEAF_EXCEPTION"><code>EXCEPTION</code></a></li>
|
||
<li><a href="#BOOST_LEAF_NEW_ERROR"><code>NEW_ERROR</code></a></li>
|
||
<li><a href="#BOOST_LEAF_THROW_EXCEPTION"><code>THROW_EXCEPTION</code></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#rationale">Design</a>
|
||
<ul class="sectlevel2">
|
||
<li><a href="#_rationale">Rationale</a></li>
|
||
<li><a href="#exception_specifications">Critique 1: Error Types Do Not Participate in Function Signatures</a></li>
|
||
<li><a href="#translation">Critique 2: LEAF Does Not Facilitate Mapping Between Different Error Types</a></li>
|
||
<li><a href="#errors_are_not_implementation_details">Critique 3: LEAF Does Not Treat Low Level Error Types as Implementation Details</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#_alternatives_to_leaf">Alternatives to LEAF</a>
|
||
<ul class="sectlevel2">
|
||
<li><a href="#boost_exception">Comparison to Boost Exception</a></li>
|
||
<li><a href="#boost_outcome">Comparison to Boost Outcome</a>
|
||
<ul class="sectlevel3">
|
||
<li><a href="#_design_differences">Design Differences</a></li>
|
||
<li><a href="#interoperability">The Interoperability Problem</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#_benchmark">Benchmark</a></li>
|
||
<li><a href="#_running_the_unit_tests">Running the Unit Tests</a>
|
||
<ul class="sectlevel2">
|
||
<li><a href="#_meson_build">Meson Build</a></li>
|
||
<li><a href="#_boost_build">Boost Build</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#configuration">Configuration Macros</a></li>
|
||
<li><a href="#_limitations">Limitations</a></li>
|
||
<li><a href="#_acknowledgements">Acknowledgements</a></li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
<div id="content">
|
||
<div id="preamble">
|
||
<div class="sectionbody">
|
||
<div class="paragraph text-right">
|
||
<p><a href="https://github.com/boostorg/leaf">GitHub</a> | <a href="https://boostorg.github.io/leaf/leaf.pdf">PDF</a></p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="_abstract">Abstract</h2>
|
||
<div class="sectionbody">
|
||
<div class="paragraph">
|
||
<p>Boost LEAF is a lightweight error handling library for C++11. Features:</p>
|
||
</div>
|
||
<div class="exampleblock">
|
||
<div class="content">
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>Small single-header format, no dependencies.</p>
|
||
</li>
|
||
<li>
|
||
<p>Designed for maximum efficiency ("happy" path and "sad" path).</p>
|
||
</li>
|
||
<li>
|
||
<p>No dynamic memory allocations, even with heavy payloads.</p>
|
||
</li>
|
||
<li>
|
||
<p>O(1) transport of arbitrary error types (independent of call stack depth).</p>
|
||
</li>
|
||
<li>
|
||
<p>Can be used with or without exception handling.</p>
|
||
</li>
|
||
<li>
|
||
<p>Support for multi-thread programming.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<table class="tableblock frame-none grid-none stretch">
|
||
<colgroup>
|
||
<col style="width: 50%;">
|
||
<col style="width: 50%;">
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#introduction">Introduction</a> | <a href="#tutorial">Tutorial</a> | <a href="#synopsis">Synopsis</a> | <a href="https://github.com/boostorg/leaf/blob/master/doc/whitepaper.md">Whitepaper</a> | <a href="https://github.com/boostorg/leaf/blob/master/benchmark/benchmark.md">Benchmark</a></p></td>
|
||
<td class="tableblock halign-right valign-top"><p class="tableblock">Reference: <a href="#functions">Functions</a> | <a href="#types">Types</a> | <a href="#predicates">Predicates</a> | <a href="#traits">Traits</a> | <a href="#macros">Macros</a></p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<div class="paragraph">
|
||
<p>LEAF is designed with a strong bias towards the common use case where callers of functions which may fail check for success and forward errors up the call stack but do not handle them. In this case, only a trivial success-or-failure discriminant is transported. Actual error objects are communicated directly to the error-handling scope, skipping the intermediate check-only frames altogether.</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="support">Support</h2>
|
||
<div class="sectionbody">
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p><a href="https://Cpplang.slack.com">cpplang on Slack</a> (use the <code>#boost</code> channel)</p>
|
||
</li>
|
||
<li>
|
||
<p><a href="https://lists.boost.org/mailman/listinfo.cgi/boost-users">Boost Users Mailing List</a></p>
|
||
</li>
|
||
<li>
|
||
<p><a href="https://lists.boost.org/mailman/listinfo.cgi/boost">Boost Developers Mailing List</a></p>
|
||
</li>
|
||
<li>
|
||
<p><a href="https://github.com/boostorg/leaf/issues">Report an issue</a> on GitHub</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="portability">Portability</h2>
|
||
<div class="sectionbody">
|
||
<div class="paragraph">
|
||
<p>LEAF requires only C++11, but is tested on many compiler versions and C++ standards.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The library uses thread-local storage, except when multi-threading is disabled (e.g. on some embedded platforms). See <a href="#configuration">Configuration Macros</a>.</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="distribution">Distribution</h2>
|
||
<div class="sectionbody">
|
||
<div class="paragraph">
|
||
<p>Copyright © 2018-2021 Emil Dotchevski. Distributed under the <a href="http://www.boost.org/LICENSE_1_0.txt">Boost Software License, Version 1.0</a>.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>There are three distribution channels:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>LEAF is included in official <a href="https://www.boost.org/">Boost</a> releases, starting with Boost 1.75.</p>
|
||
</li>
|
||
<li>
|
||
<p>The source code is hosted on <a href="https://github.com/boostorg/leaf">GitHub</a>.</p>
|
||
</li>
|
||
<li>
|
||
<p>For maximum portability, the library is also available in single-header format: simply download <a href="leaf.hpp">leaf.hpp</a> (direct download link).</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
LEAF does not depend on Boost or other libraries.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="introduction">Five Minute Introduction</h2>
|
||
<div class="sectionbody">
|
||
<div class="paragraph">
|
||
<p>We’ll implement two versions of the same simple program: one using the LEAF <code>noexcept</code> API to handle errors, and another using the exception-handling API.</p>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="introduction-result"><code>noexcept</code> API</h3>
|
||
<div class="paragraph">
|
||
<p>We’ll write a short but complete program that reads a text file in a buffer and prints it to <code>std::cout</code>, using LEAF to handle errors without exception handling.</p>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
LEAF provides an <a href="#introduction-eh">Exception-Handling API</a> as well.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>We’ll skip to the chase and start with the <code>main</code> function: it will try several operations as needed and handle all the errors that occur. Did I say <strong>all</strong> the errors? I did, so we’ll use <code>leaf::try_handle_all</code>. It has the following signature:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">template <class TryBlock, class... Handler>
|
||
<<deduced>> try_handle_all( TryBlock && try_block, Handler && ... handler );</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p><code>TryBlock</code> is a function type, required to return a <code>result<T></code> — for example, <code>leaf::result<T></code> — that holds a value of type <code>T</code> or else indicates a failure.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The first thing <code>try_handle_all</code> does is invoke the <code>try_block</code> function. If the returned object <code>r</code> indicates success, <code>try_handle_all</code> unwraps it, returning the contained <code>r.value()</code>; otherwise it calls the <span class="underline">first suitable</span> error handling function from the <code>handler…​</code> list.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>We’ll see later just what kind of a <code>TryBlock</code> will our <code>main</code> function pass to <code>try_handle_all</code>, but first, let’s look at the juicy error-handling part. In case of an error, LEAF will consider each of the error handlers, <span class="underline">in order</span>, and call the first suitable match:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">int main( int argc, char const * argv[] )
|
||
{
|
||
return leaf::try_handle_all(
|
||
|
||
[&]() -> leaf::result<int>
|
||
{
|
||
// The TryBlock goes here, we'll see it later
|
||
},
|
||
|
||
// Error handlers below:
|
||
|
||
[](leaf::match<error_code, open_error>, leaf::match_value<leaf::e_errno, ENOENT>, leaf::e_file_name const & fn)
|
||
{ <i class="conum" data-value="1"></i><b>(1)</b>
|
||
std::cerr << "File not found: " << fn.value << std::endl;
|
||
return 1;
|
||
},
|
||
|
||
[](leaf::match<error_code, open_error>, leaf::e_errno const & errn, leaf::e_file_name const & fn)
|
||
{ <i class="conum" data-value="2"></i><b>(2)</b>
|
||
std::cerr << "Failed to open " << fn.value << ", errno=" << errn << std::endl;
|
||
return 2;
|
||
},
|
||
|
||
[](leaf::match<error_code, size_error, read_error, eof_error>, leaf::e_errno const * errn, leaf::e_file_name const & fn)
|
||
{ <i class="conum" data-value="3"></i><b>(3)</b>
|
||
std::cerr << "Failed to access " << fn.value;
|
||
if( errn )
|
||
std::cerr << ", errno=" << *errn;
|
||
std::cerr << std::endl;
|
||
return 3;
|
||
},
|
||
|
||
[](leaf::match<error_code, output_error>, leaf::e_errno const & errn)
|
||
{ <i class="conum" data-value="4"></i><b>(4)</b>
|
||
std::cerr << "Output error, errno=" << errn << std::endl;
|
||
return 4;
|
||
},
|
||
|
||
[](leaf::match<error_code, bad_command_line>)
|
||
{ <i class="conum" data-value="5"></i><b>(5)</b>
|
||
std::cout << "Bad command line argument" << std::endl;
|
||
return 5;
|
||
},
|
||
|
||
[](leaf::error_info const & unmatched)
|
||
{ <i class="conum" data-value="6"></i><b>(6)</b>
|
||
std::cerr <<
|
||
"Unknown failure detected" << std::endl <<
|
||
"Cryptic diagnostic information follows" << std::endl <<
|
||
unmatched;
|
||
return 6;
|
||
}
|
||
);
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>This handler will be called if the detected error includes:<br>
|
||
• an object of type <code>enum error_code</code> equal to the value <code>open_error</code>, and<br>
|
||
• an object of type <code>leaf::e_errno</code> that has <code>.value</code> equal to <code>ENOENT</code>, and<br>
|
||
• an object of type <code>leaf::e_file_name</code>.<br>
|
||
In short, it handles "file not found" errors.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>This handler will be called if the detected error includes:<br>
|
||
• an object of type <code>enum error_code</code> equal to <code>open_error</code>, and<br>
|
||
• an object of type <code>leaf::e_errno</code> (regardless of its <code>.value</code>), and<br>
|
||
• an object of type <code>leaf::e_file_name</code>.<br>
|
||
In short, it will handle other "file open" errors.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="3"></i><b>3</b></td>
|
||
<td>This handler will be called if the detected error includes:<br>
|
||
• an object of type <code>enum error_code</code> equal to any of <code>size_error</code>, <code>read_error</code>, <code>eof_error</code>, and<br>
|
||
• an optional object of type <code>leaf::e_errno</code> (regardless of its <code>.value</code>), and<br>
|
||
• an object of type <code>leaf::e_file_name</code>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="4"></i><b>4</b></td>
|
||
<td>This handler will be called if the detected error includes:<br>
|
||
• an object of type <code>enum error_code</code> equal to <code>output_error</code>, and<br>
|
||
• an object of type <code>leaf::e_errno</code> (regardless of its <code>.value</code>),</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="5"></i><b>5</b></td>
|
||
<td>This handler will be called if the detected error includes an object of type <code>enum error_code</code> equal to <code>bad_command_line</code>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="6"></i><b>6</b></td>
|
||
<td>This last handler is a catch-all for any error, in case no other handler could be selected: it prints diagnostic information to help debug logic errors in the program, since it failed to find an appropriate error handler for the error condition it encountered.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="admonitionblock warning">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-warning" title="Warning"></i>
|
||
</td>
|
||
<td class="content">
|
||
It is critical to understand that the error handlers are considered in order, rather than by finding a "best match". No error handler is "better" than the others: LEAF will call the first one for which all of the arguments can be supplied using the available error objects.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Now, reading and printing a file may not seem like a complex job, but let’s split it into several functions, each communicating failures using <code>leaf::result<T></code>:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">leaf::result<char const *> parse_command_line( int argc, char const * argv[] ) noexcept; <i class="conum" data-value="1"></i><b>(1)</b>
|
||
|
||
leaf::result<std::shared_ptr<FILE>> file_open( char const * file_name ) noexcept; <i class="conum" data-value="2"></i><b>(2)</b>
|
||
|
||
leaf::result<int> file_size( FILE & f ) noexcept; <i class="conum" data-value="3"></i><b>(3)</b>
|
||
|
||
leaf::result<void> file_read( FILE & f, void * buf, int size ) noexcept; <i class="conum" data-value="4"></i><b>(4)</b></code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>Parse the command line, return the file name.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>Open a file for reading.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="3"></i><b>3</b></td>
|
||
<td>Return the size of the file.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="4"></i><b>4</b></td>
|
||
<td>Read size bytes from f into buf.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>For example, let’s look at <code>file_open</code>:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">leaf::result<std::shared_ptr<FILE>> file_open( char const * file_name ) noexcept
|
||
{
|
||
if( FILE * f = fopen(file_name,"rb") )
|
||
return std::shared_ptr<FILE>(f,&fclose);
|
||
else
|
||
return leaf::new_error(open_error, leaf::e_errno{errno});
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>If <code>fopen</code> succeeds, we return a <code>shared_ptr</code> which will automatically call <code>fclose</code> as needed. If <code>fopen</code> fails, we report an error by calling <code>new_error</code>, which takes any number of error objects to communicate with the error. In this case we pass the system <code>errno</code> (LEAF defines <code>struct e_errno {int value;}</code>), and our own error code value, <code>open_error</code>.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Here is our complete error code <code>enum</code>:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">enum error_code
|
||
{
|
||
bad_command_line = 1,
|
||
open_error,
|
||
read_error,
|
||
size_error,
|
||
eof_error,
|
||
output_error
|
||
};</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>We’re now ready to look at the <code>TryBlock</code> we’ll pass to <code>try_handle_all</code>. It does all the work, bails out if it encounters an error:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">int main( int argc, char const * argv[] )
|
||
{
|
||
return leaf::try_handle_all(
|
||
|
||
[&]() -> leaf::result<int>
|
||
{
|
||
leaf::result<char const *> file_name = parse_command_line(argc,argv);
|
||
if( !file_name )
|
||
return file_name.error();</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Wait, what’s this, if "error" return "error"? There is a better way: we’ll use <code>BOOST_LEAF_AUTO</code>. It takes a <code>result<T></code> and bails out in case of a failure (control leaves the calling function), otherwise uses the passed variable to access the <code>T</code> value stored in the <code>result</code> object.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>This is what our <code>TryBlock</code> really looks like:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">int main( int argc, char const * argv[] )
|
||
{
|
||
return leaf::try_handle_all(
|
||
|
||
[&]() -> leaf::result<int> <i class="conum" data-value="1"></i><b>(1)</b>
|
||
{
|
||
BOOST_LEAF_AUTO(file_name, parse_command_line(argc,argv)); <i class="conum" data-value="2"></i><b>(2)</b>
|
||
|
||
auto load = leaf::on_error( leaf::e_file_name{file_name} ); <i class="conum" data-value="3"></i><b>(3)</b>
|
||
|
||
BOOST_LEAF_AUTO(f, file_open(file_name)); <i class="conum" data-value="4"></i><b>(4)</b>
|
||
|
||
BOOST_LEAF_AUTO(s, file_size(*f)); <i class="conum" data-value="4"></i><b>(4)</b>
|
||
|
||
std::string buffer( 1 + s, '\0' );
|
||
BOOST_LEAF_CHECK(file_read(*f, &buffer[0], buffer.size()-1)); <i class="conum" data-value="4"></i><b>(4)</b>
|
||
|
||
std::cout << buffer;
|
||
std::cout.flush();
|
||
if( std::cout.fail() )
|
||
return leaf::new_error(output_error, leaf::e_errno{errno});
|
||
|
||
return 0;
|
||
},
|
||
|
||
.... <i class="conum" data-value="5"></i><b>(5)</b>
|
||
|
||
); <i class="conum" data-value="6"></i><b>(6)</b>
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>Our <code>TryBlock</code> returns a <code>result<int></code>. In case of success, it will hold <code>0</code>, which will be returned from <code>main</code> to the OS.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>If <code>parse_command_line</code> returns an error, we forward that error to <code>try_handle_all</code> (which invoked us) verbatim. Otherwise, <code>BOOST_LEAF_AUTO</code> gets us a variable, <code>file_name</code>, to access the parsed string.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="3"></i><b>3</b></td>
|
||
<td>From now on, all errors escaping this scope will automatically communicate the (now successfully parsed from the command line) file name (LEAF defines <code>struct e_file_name {std::string value;}</code>). This is as if every time one of the following functions wants to report an error, <code>on_error</code> says "wait, associate this <code>e_file_name</code> object with the error, it’s important!"</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="4"></i><b>4</b></td>
|
||
<td>Call more functions, forward each failure to the caller.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="5"></i><b>5</b></td>
|
||
<td>List of error handlers goes here (we saw this earlier).</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="6"></i><b>6</b></td>
|
||
<td>This concludes the <code>try_handle_all</code> arguments — as well as our program!</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Nice and simple! Writing the <code>TryBlock</code>, we focus on the "happy" path — if we encounter any error we just return it to <code>try_handle_all</code> for processing. Well, that’s if we’re being good and using RAII for automatic clean-up — which we are, <code>shared_ptr</code> will automatically close the file for us.</p>
|
||
</div>
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
The complete program from this tutorial is available <a href="https://github.com/boostorg/leaf/blob/master/examples/print_file/print_file_result.cpp?ts=4">here</a>. The <a href="https://github.com/boostorg/leaf/blob/master/examples/print_file/print_file_eh.cpp?ts=4">other</a> version of the same program uses exception handling to report errors (see <a href="#introduction-eh">below</a>).
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="introduction-eh">Exception-Handling API</h3>
|
||
<div class="paragraph">
|
||
<p>And now, we’ll write the same program that reads a text file in a buffer and prints it to <code>std::cout</code>, this time using exceptions to report errors. First, we need to define our exception class hierarchy:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">struct bad_command_line: std::exception { };
|
||
struct input_error: std::exception { };
|
||
struct open_error: input_error { };
|
||
struct read_error: input_error { };
|
||
struct size_error: input_error { };
|
||
struct eof_error: input_error { };
|
||
struct output_error: std::exception { };</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>We’ll split the job into several functions, communicating failures by throwing exceptions:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">char const * parse_command_line( int argc, char const * argv[] ); <i class="conum" data-value="1"></i><b>(1)</b>
|
||
|
||
std::shared_ptr<FILE> file_open( char const * file_name ); <i class="conum" data-value="2"></i><b>(2)</b>
|
||
|
||
int file_size( FILE & f ); <i class="conum" data-value="3"></i><b>(3)</b>
|
||
|
||
void file_read( FILE & f, void * buf, int size ); <i class="conum" data-value="4"></i><b>(4)</b></code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>Parse the command line, return the file name.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>Open a file for reading.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="3"></i><b>3</b></td>
|
||
<td>Return the size of the file.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="4"></i><b>4</b></td>
|
||
<td>Read size bytes from f into buf.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The <code>main</code> function brings everything together and handles all the exceptions that are thrown, but instead of using <code>try</code> and <code>catch</code>, it will use the function template <code>leaf::try_catch</code>, which has the following signature:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">template <class TryBlock, class... Handler>
|
||
<<deduced>> try_catch( TryBlock && try_block, Handler && ... handler );</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p><code>TryBlock</code> is a function type that takes no arguments; <code>try_catch</code> simply returns the value returned by the <code>try_block</code>, catching <span class="underline">any</span> exception it throws, in which case it calls the <span class="underline">first</span> suitable error handling function from the <code>handler…​</code> list.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Let’s first look at the <code>TryBlock</code> our <code>main</code> function passes to <code>try_catch</code>:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">int main( int argc, char const * argv[] )
|
||
{
|
||
return leaf::try_catch(
|
||
|
||
[&] <i class="conum" data-value="1"></i><b>(1)</b>
|
||
{
|
||
char const * file_name = parse_command_line(argc,argv); <i class="conum" data-value="2"></i><b>(2)</b>
|
||
|
||
auto load = leaf::on_error( leaf::e_file_name{file_name} ); <i class="conum" data-value="3"></i><b>(3)</b>
|
||
|
||
std::shared_ptr<FILE> f = file_open( file_name ); <i class="conum" data-value="2"></i><b>(2)</b>
|
||
|
||
std::string buffer( 1+file_size(*f), '\0' ); <i class="conum" data-value="2"></i><b>(2)</b>
|
||
file_read(*f, &buffer[0], buffer.size()-1); <i class="conum" data-value="2"></i><b>(2)</b>
|
||
|
||
std::cout << buffer;
|
||
std::cout.flush();
|
||
if( std::cout.fail() )
|
||
throw leaf::exception(output_error{}, leaf::e_errno{errno});
|
||
|
||
return 0;
|
||
},
|
||
|
||
.... <i class="conum" data-value="4"></i><b>(4)</b>
|
||
|
||
); <i class="conum" data-value="5"></i><b>(5)</b>
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>Except if it throws, our <code>TryBlock</code> returns <code>0</code>, which will be returned from <code>main</code> to the OS.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>If any of the functions we call throws, <code>try_catch</code> will find an appropriate handler to invoke (below).</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="3"></i><b>3</b></td>
|
||
<td>From now on, all exceptions escaping this scope will automatically communicate the (now successfully parsed from the command line) file name (LEAF defines <code>struct e_file_name {std::string value;}</code>). This is as if every time one of the following functions wants to throw an exception, <code>on_error</code> says "wait, associate this <code>e_file_name</code> object with the exception, it’s important!"</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="4"></i><b>4</b></td>
|
||
<td>List of error handlers goes here. We’ll see that later.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="5"></i><b>5</b></td>
|
||
<td>This concludes the <code>try_catch</code> arguments — as well as our program!</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>As it is always the case when using exception handling, as long as our <code>TryBlock</code> is exception-safe, we can focus on the "happy" path. Of course, our <code>TryBlock</code> is exception-safe, since <code>shared_ptr</code> will automatically close the file for us in case an exception is thrown.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Now let’s look at the second part of the call to <code>try_catch</code>, which lists the error handlers:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">int main( int argc, char const * argv[] )
|
||
{
|
||
return leaf::try_catch(
|
||
[&]
|
||
{
|
||
// The TryBlock goes here (we saw that earlier)
|
||
},
|
||
|
||
// Error handlers below:
|
||
|
||
[](open_error &, leaf::match_value<leaf::e_errno,ENOENT>, leaf::e_file_name const & fn)
|
||
{ <i class="conum" data-value="1"></i><b>(1)</b>
|
||
std::cerr << "File not found: " << fn.value << std::endl;
|
||
return 1;
|
||
},
|
||
|
||
[](open_error &, leaf::e_file_name const & fn, leaf::e_errno const & errn)
|
||
{ <i class="conum" data-value="2"></i><b>(2)</b>
|
||
std::cerr << "Failed to open " << fn.value << ", errno=" << errn << std::endl;
|
||
return 2;
|
||
},
|
||
|
||
[](input_error &, leaf::e_errno const * errn, leaf::e_file_name const & fn)
|
||
{ <i class="conum" data-value="3"></i><b>(3)</b>
|
||
std::cerr << "Failed to access " << fn.value;
|
||
if( errn )
|
||
std::cerr << ", errno=" << *errn;
|
||
std::cerr << std::endl;
|
||
return 3;
|
||
},
|
||
|
||
[](output_error &, leaf::e_errno const & errn)
|
||
{ <i class="conum" data-value="4"></i><b>(4)</b>
|
||
std::cerr << "Output error, errno=" << errn << std::endl;
|
||
return 4;
|
||
},
|
||
|
||
[](bad_command_line &)
|
||
{ <i class="conum" data-value="5"></i><b>(5)</b>
|
||
std::cout << "Bad command line argument" << std::endl;
|
||
return 5;
|
||
},
|
||
|
||
[](leaf::error_info const & unmatched)
|
||
{ <i class="conum" data-value="6"></i><b>(6)</b>
|
||
std::cerr <<
|
||
"Unknown failure detected" << std::endl <<
|
||
"Cryptic diagnostic information follows" << std::endl <<
|
||
unmatched;
|
||
return 6;
|
||
} );
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>This handler will be called if:<br>
|
||
• an <code>open_error</code> exception was caught, with<br>
|
||
• an object of type <code>leaf::e_errno</code> that has <code>.value</code> equal to <code>ENOENT</code>, and<br>
|
||
• an object of type <code>leaf::e_file_name</code>.<br>
|
||
In short, it handles "file not found" errors.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>This handler will be called if:<br>
|
||
• an <code>open_error</code> exception was caught, with<br>
|
||
• an object of type <code>leaf::e_errno</code> (regardless of its <code>.value</code>), and<br>
|
||
• an object of type <code>leaf::e_file_name</code>.<br>
|
||
In short, it handles other "file open" errors.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="3"></i><b>3</b></td>
|
||
<td>This handler will be called if:<br>
|
||
• an <code>input_error</code> exception was caught (which is a base type), with<br>
|
||
• an optional object of type <code>leaf::e_errno</code> (regardless of its <code>.value</code>), and<br>
|
||
• an object of type <code>leaf::e_file_name</code>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="4"></i><b>4</b></td>
|
||
<td>This handler will be called if:<br>
|
||
• an <code>output_error</code> exception was caught, with<br>
|
||
• an object of type <code>leaf::e_errno</code> (regardless of its <code>.value</code>),</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="5"></i><b>5</b></td>
|
||
<td>This handler will be called if a <code>bad_command_line</code> exception was caught.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="6"></i><b>6</b></td>
|
||
<td>If <code>try_catch</code> fails to find an appropriate handler, it will re-throw the exception. But this is the <code>main</code> function which should handle all exceptions, so this last handler matches any error and prints diagnostic information, to help debug logic errors.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="admonitionblock warning">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-warning" title="Warning"></i>
|
||
</td>
|
||
<td class="content">
|
||
It is critical to understand that the error handlers are considered in order, rather than by finding a "best match". No error handler is "better" than the others: LEAF will call the first one for which all of the arguments can be supplied using the available error objects.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>To conclude this introduction, let’s look at one of the error-reporting functions that our <code>TryBlock</code> calls, for example <code>file_open</code>:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">std::shared_ptr<FILE> file_open( char const * file_name )
|
||
{
|
||
if( FILE * f = fopen(file_name,"rb") )
|
||
return std::shared_ptr<FILE>(f,&fclose);
|
||
else
|
||
throw leaf::exception(open_error{}, leaf::e_errno{errno});
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>If <code>fopen</code> succeeds, it returns a <code>shared_ptr</code> which will automatically call <code>fclose</code> as needed. If <code>fopen</code> fails, we throw the exception object returned by <code>leaf::exception</code>, which in this case is of type that derives from <code>open_error</code>; the passed <code>e_errno</code> object will be associated with the exception.</p>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
<code>try_catch</code> works with any exception, not only exceptions thrown using <code>leaf::exception</code>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
The complete program from this tutorial is available <a href="https://github.com/boostorg/leaf/blob/master/examples/print_file/print_file_eh.cpp?ts=4">here</a>. The <a href="https://github.com/boostorg/leaf/blob/master/examples/print_file/print_file_result.cpp?ts=4">other</a> version of the same program does not use exception handling to report errors (see the <a href="#introduction-result">previous introduction</a>).
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="tutorial">Tutorial</h2>
|
||
<div class="sectionbody">
|
||
<div class="paragraph">
|
||
<p>This section assumes the reader has basic understanding of using LEAF to handle errors; see <a href="#introduction">Five Minute Introduction</a>.</p>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="tutorial-model">Error Communication Model</h3>
|
||
<div class="sect3">
|
||
<h4 id="_noexcept_api"><code>noexcept</code> API</h4>
|
||
<div class="paragraph">
|
||
<p>The following figure illustrates how error objects are transported when using LEAF without exception handling:</p>
|
||
</div>
|
||
<div class="imageblock">
|
||
<div class="content">
|
||
<img src="LEAF-1.png" alt="LEAF 1">
|
||
</div>
|
||
<div class="title">Figure 1. LEAF noexcept Error Communication Model</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The arrows pointing down indicate the call stack order for the functions <code>f1</code> through <code>f5</code>: higher level functions calling lower level functions.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Note the call to <code>on_error</code> in <code>f3</code>: it caches the passed error objects of types <code>E1</code> and <code>E3</code> in the returned object <code>load</code>, where they stay ready to be communicated in case any function downstream from <code>f3</code> reports an error. Presumably these objects are relevant to any such failure, but are conveniently accessible only in this scope.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p><em>Figure 1</em> depicts the condition where <code>f5</code> has detected an error. It calls <code>leaf::new_error</code> to create a new, unique <code>error_id</code>. The passed error object of type <code>E2</code> is immediately loaded in the first active <code>context</code> object that provides static storage for it, found in any calling scope (in this case <code>f1</code>), and is associated with the newly-generated <code>error_id</code> (solid arrow);</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The <code>error_id</code> itself is returned to the immediate caller <code>f4</code>, usually stored in a <code>result<T></code> object <code>r</code>. That object takes the path shown by dashed arrows, as each error-neutral function, unable to handle the failure, forwards it to its immediate caller in the returned value — until an error-handling scope is reached.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>When the destructor of the <code>load</code> object in <code>f3</code> executes, it detects that <code>new_error</code> was invoked after its initialization, loads the cached objects of types <code>E1</code> and <code>E3</code> in the first active <code>context</code> object that provides static storage for them, found in any calling scope (in this case <code>f1</code>), and associates them with the last generated <code>error_id</code> (solid arrow).</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>When the error-handling scope <code>f1</code> is reached, it probes <code>ctx</code> for any error objects associated with the <code>error_id</code> it received from <code>f2</code>, and processes a list of user-provided error handlers, in order, until it finds a handler with arguments that can be supplied using the available (in <code>ctx</code>) error objects. That handler is called to deal with the failure.</p>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="_exception_handling_api">Exception-Handling API</h4>
|
||
<div class="paragraph">
|
||
<p>The following figure illustrates the slightly different error communication model used when errors are reported by throwing exceptions:</p>
|
||
</div>
|
||
<div class="imageblock">
|
||
<div class="content">
|
||
<img src="LEAF-2.png" alt="LEAF 2">
|
||
</div>
|
||
<div class="title">Figure 2. LEAF Error Communication Model Using Exception Handling</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The main difference is that the call to <code>new_error</code> is implicit in the call to the function template <code>leaf::exception</code>, which in this case takes an exception object of type <code>Ex</code>, and returns an exception object of unspecified type that derives publicly from <code>Ex</code>.</p>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="tutorial-interoperability">Interoperability</h4>
|
||
<div class="paragraph">
|
||
<p>Ideally, when an error is detected, a program using LEAF would always call <a href="#new_error"><code>new_error</code></a>, ensuring that each encountered failure is definitely assigned a unique <a href="#error_id"><code>error_id</code></a>, which then is reliably delivered, by an exception or by a <code>result<T></code> object, to the appropriate error-handling scope.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Alas, this is not always possible.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>For example, the error may need to be communicated through uncooperative 3rd-party interfaces. To facilitate this transmission, a error ID may be encoded in a <code>std::error_code</code>. As long as a 3rd-party interface understands <code>std::error_code</code>, it should be compatible with LEAF.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Further, it is sometimes necessary to communicate errors through an interface that does not even use <code>std::error_code</code>. An example of this is when an external lower-level library throws an exception, which is unlikely to be able to carry an <code>error_id</code>.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>To support this tricky use case, LEAF provides the function <a href="#current_error"><code>current_error</code></a>, which returns the error ID returned by the most recent call (from this thread) to <a href="#new_error"><code>new_error</code></a>. One possible approach to solving the problem is to use the following logic (implemented by the <a href="#error_monitor"><code>error_monitor</code></a> type):</p>
|
||
</div>
|
||
<div class="olist arabic">
|
||
<ol class="arabic">
|
||
<li>
|
||
<p>Before calling the uncooperative API, call <a href="#current_error"><code>current_error</code></a> and cache the returned value.</p>
|
||
</li>
|
||
<li>
|
||
<p>Call the API, then call <code>current_error</code> again:</p>
|
||
<div class="olist loweralpha">
|
||
<ol class="loweralpha" type="a">
|
||
<li>
|
||
<p>If this returns the same value as before, pass the error objects to <code>new_error</code> to associate them with a new <code>error_id</code>;</p>
|
||
</li>
|
||
<li>
|
||
<p>else, associate the error objects with the <code>error_id</code> value returned by the second call to <code>current_error</code>.</p>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Note that if the above logic is nested (e.g. one function calling another), <code>new_error</code> will be called only by the inner-most function, because that call guarantees that all calling functions will hit the <code>else</code> branch.</p>
|
||
</div>
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
To avoid ambiguities, whenever possible, use the <a href="#exception"><code>exception</code></a> function template when throwing exceptions to ensure that the exception object transports a unique <code>error_id</code>; better yet, use the <a href="#BOOST_LEAF_THROW_EXCEPTION"><code>THROW_EXCEPTION</code></a> macro, which in addition will capture <code>__FILE__</code> and <code>__LINE__</code>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="tutorial-loading">Loading of Error Objects</h3>
|
||
<div class="paragraph">
|
||
<p>To load an error object is to move it into an active <a href="#context"><code>context</code></a>, usually local to a <a href="#try_handle_some"><code>try_handle_some</code></a>, a <a href="#try_handle_all"><code>try_handle_all</code></a> or a <a href="#try_catch"><code>try_catch</code></a> scope in the calling thread, where it becomes uniquely associated with a specific <a href="#error_id"><code>error_id</code></a> — or discarded if storage is not available.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Various LEAF functions take a list of error objects to load. As an example, if a function <code>copy_file</code> that takes the name of the input file and the name of the output file as its arguments detects a failure, it could communicate an error code <code>ec</code>, plus the two relevant file names using <a href="#new_error"><code>new_error</code></a>:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">return leaf::new_error(ec, e_input_name{n1}, e_output_name{n2});</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Alternatively, error objects may be loaded using a <code>result<T></code> that is already communicating an error. This way they become associated with that error, rather than with a new error:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">leaf::result<int> f() noexcept;
|
||
|
||
leaf::result<void> g( char const * fn ) noexcept
|
||
{
|
||
if( leaf::result<int> r = f() )
|
||
{ <i class="conum" data-value="1"></i><b>(1)</b>
|
||
....;
|
||
return { };
|
||
}
|
||
else
|
||
{
|
||
return r.load( e_file_name{fn} ); <i class="conum" data-value="2"></i><b>(2)</b>
|
||
}
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#result"><code>result</code></a> | <a href="#result::load"><code>load</code></a></p>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>Success! Use <code>r.value()</code>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td><code>f()</code> has failed; here we associate an additional <code>e_file_name</code> with the error. However, this association occurs iff in the call stack leading to <code>g</code> there are error handlers that take an <code>e_file_name</code> argument. Otherwise, the object passed to <code>load</code> is discarded. In other words, the passed objects are loaded iff the program actually uses them to handle errors.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Besides error objects, <code>load</code> can take function arguments:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>If we pass a function that takes no arguments, it is invoked, and the returned error object is loaded.</p>
|
||
<div class="paragraph">
|
||
<p>Consider that if we pass to <code>load</code> an error object that is not needed by any error handler, it will be discarded. If the object is expensive to compute, it would be better if the computation can be skipped as well. Passing a function with no arguments to <code>load</code> is an excellent way to achieve this behavior:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">struct info { .... };
|
||
|
||
info compute_info() noexcept;
|
||
|
||
leaf::result<void> operation( char const * file_name ) noexcept
|
||
{
|
||
if( leaf::result<int> r = try_something() )
|
||
{ <i class="conum" data-value="1"></i><b>(1)</b>
|
||
....
|
||
return { };
|
||
}
|
||
else
|
||
{
|
||
return r.load( <i class="conum" data-value="2"></i><b>(2)</b>
|
||
[&]
|
||
{
|
||
return compute_info();
|
||
} );
|
||
}
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#result"><code>result</code></a> | <a href="#result::load"><code>load</code></a></p>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>Success! Use <code>r.value()</code>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td><code>try_something</code> has failed; <code>compute_info</code> will only be called if an error handler exists which takes a <code>info</code> argument.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</li>
|
||
<li>
|
||
<p>If we pass a function that takes a single argument of type <code>E &</code>, LEAF calls the function with the object of type <code>E</code> currently loaded in an active <code>context</code>, associated with the error. If no such object is available, a new one is default-initialized and then passed to the function.</p>
|
||
<div class="paragraph">
|
||
<p>For example, if an operation that involves many different files fails, a program may provide for collecting all relevant file names in a <code>e_relevant_file_names</code> object:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">struct e_relevant_file_names
|
||
{
|
||
std::vector<std::string> value;
|
||
};
|
||
|
||
leaf::result<void> operation( char const * file_name ) noexcept
|
||
{
|
||
if( leaf::result<int> r = try_something() )
|
||
{ <i class="conum" data-value="1"></i><b>(1)</b>
|
||
....
|
||
return { };
|
||
}
|
||
else
|
||
{
|
||
return r.load( <i class="conum" data-value="2"></i><b>(2)</b>
|
||
[&](e_relevant_file_names & e)
|
||
{
|
||
e.value.push_back(file_name);
|
||
} );
|
||
}
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#result"><code>result</code></a> | <a href="#result::load"><code>load</code></a></p>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>Success! Use <code>r.value()</code>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td><code>try_something</code> has failed — add <code>file_name</code> to the <code>e_relevant_file_names</code> object, associated with the <code>error_id</code> communicated in <code>r</code>. Note, however, that the passed function will only be called iff in the call stack there are error handlers that take an <code>e_relevant_file_names</code> object.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="tutorial-on_error">Using <code>on_error</code></h3>
|
||
<div class="paragraph">
|
||
<p>It is not typical for an error-reporting function to be able to supply all of the data needed by a suitable error-handling function in order to recover from the failure. For example, a function that reports <code>FILE</code> operation failures may not have access to the file name, yet an error handling function needs it in order to print a useful error message.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Of course the file name is typically readily available in the call stack leading to the failed <code>FILE</code> operation. Below, while <code>parse_info</code> can’t report the file name, <code>parse_file</code> can and does:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">leaf::result<info> parse_info( FILE * f ) noexcept; <i class="conum" data-value="1"></i><b>(1)</b>
|
||
|
||
leaf::result<info> parse_file( char const * file_name ) noexcept
|
||
{
|
||
auto load = leaf::on_error(leaf::e_file_name{file_name}); <i class="conum" data-value="2"></i><b>(2)</b>
|
||
|
||
if( FILE * f = fopen(file_name,"r") )
|
||
{
|
||
auto r = parse_info(f);
|
||
fclose(f);
|
||
return r;
|
||
}
|
||
else
|
||
return leaf::new_error( error_enum::file_open_error );
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#result"><code>result</code></a> | <a href="#on_error"><code>on_error</code></a> | <a href="#new_error"><code>new_error</code></a></p>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td><code>parse_info</code> parses <code>f</code>, communicating errors using <code>result<info></code>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>Using <code>on_error</code> ensures that the file name is included with any error reported out of <code>parse_file</code>. All we need to do is hold on to the returned object <code>load</code>; when it expires, if an error is being reported, the passed <code>e_file_name</code> value will be automatically associated with it.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
<code>on_error</code> —  like <code>load</code> — can be passed any number of arguments.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>When we invoke <code>on_error</code>, we can pass three kinds of arguments:</p>
|
||
</div>
|
||
<div class="olist arabic">
|
||
<ol class="arabic">
|
||
<li>
|
||
<p>Actual error objects (like in the example above);</p>
|
||
</li>
|
||
<li>
|
||
<p>Functions that take no arguments and return an error object;</p>
|
||
</li>
|
||
<li>
|
||
<p>Functions that take an error object by mutable reference.</p>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>If we want to use <code>on_error</code> to capture <code>errno</code>, we can’t just pass <a href="#e_errno"><code>e_errno</code></a> to it, because at that time it hasn’t been set (yet). Instead, we’d pass a function that returns it:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">void read_file(FILE * f) {
|
||
|
||
auto load = leaf::on_error([]{ return e_errno{errno}; });
|
||
|
||
....
|
||
size_t nr1=fread(buf1,1,count1,f);
|
||
if( ferror(f) )
|
||
throw leaf::exception();
|
||
|
||
size_t nr2=fread(buf2,1,count2,f);
|
||
if( ferror(f) )
|
||
throw leaf::exception();
|
||
|
||
size_t nr3=fread(buf3,1,count3,f);
|
||
if( ferror(f) )
|
||
throw leaf::exception();
|
||
....
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Above, if a <code>throw</code> statement is reached, LEAF will invoke the function passed to <code>on_error</code> and associate the returned <code>e_errno</code> object with the exception.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The final type of arguments that can be passed to <code>on_error</code> is a function that takes a single mutable error object reference. In this case, <code>on_error</code> uses it similarly to how such functios are used by <code>load</code>; see <a href="#tutorial-loading">Loading of Error Objects</a>.</p>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="tutorial-predicates">Using Predicates to Handle Errors</h3>
|
||
<div class="paragraph">
|
||
<p>Usually, LEAF error handlers are selected based on the type of the arguments they take and the type of the available error objects. When an error handler takes a predicate type as an argument, the <a href="#handler_selection_procedure">handler selection procedure</a> is able to also take into account the <em>value</em> of the available error objects.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Consider this error code enum:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">enum class my_error
|
||
{
|
||
e1=1,
|
||
e2,
|
||
e3
|
||
};</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>We could handle <code>my_error</code> errors like so:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">return leaf::try_handle_some(
|
||
[]
|
||
{
|
||
return f(); // returns leaf::result<T>
|
||
},
|
||
|
||
[]( my_error e )
|
||
{ <i class="conum" data-value="1"></i><b>(1)</b>
|
||
switch(e)
|
||
{
|
||
case my_error::e1:
|
||
....; <i class="conum" data-value="2"></i><b>(2)</b>
|
||
break;
|
||
case my_error::e2:
|
||
case my_error::e3:
|
||
....; <i class="conum" data-value="3"></i><b>(3)</b>
|
||
break;
|
||
default:
|
||
....; <i class="conum" data-value="4"></i><b>(4)</b>
|
||
break;
|
||
} );</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>This handler will be selected if we’ve got a <code>my_error</code> object.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>Handle <code>e1</code> errors.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="3"></i><b>3</b></td>
|
||
<td>Handle <code>e2</code> and <code>e3</code> errors.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="4"></i><b>4</b></td>
|
||
<td>Handle bad <code>my_error</code> values.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>If <code>my_error</code> object is available, LEAF will call our error handler. If not, the failure will be forwarded to our caller.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>This can be rewritten using the <a href="#match"><code>match</code></a> predicate to organize the different cases in different error handlers. The following is equivalent:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">return leaf::try_handle_some(
|
||
[]
|
||
{
|
||
return f(); // returns leaf::result<T>
|
||
},
|
||
|
||
[]( leaf::match<my_error, my_error::e1> m )
|
||
{ <i class="conum" data-value="1"></i><b>(1)</b>
|
||
assert(m.matched == my_error::e1);
|
||
....;
|
||
},
|
||
|
||
[]( leaf::match<my_error, my_error::e2, my_error::e3> m )
|
||
{ <i class="conum" data-value="2"></i><b>(2)</b>
|
||
assert(m.matched == my_error::e2 || m.matched == my_error::e3);
|
||
....;
|
||
},
|
||
|
||
[]( my_error e )
|
||
{ <i class="conum" data-value="3"></i><b>(3)</b>
|
||
....;
|
||
} );</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>We’ve got a <code>my_error</code> object that compares equal to <code>e1</code>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>We`ve got a <code>my_error</code> object that compares equal to either <code>e2</code> or <code>e3</code>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="3"></i><b>3</b></td>
|
||
<td>Handle bad <code>my_error</code> values.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The first argument to the <code>match</code> template generally specifies the type <code>E</code> of the error object <code>e</code> that must be available for the error handler to be considered at all. Typically, the rest of the arguments are values. The error handler to be dropped if <code>e</code> does not compare equal to any of them.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>In particular, <code>match</code> works great with <code>std::error_code</code>. The following handler is designed to handle <code>ENOENT</code> errors:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">[]( leaf::match<std::error_code, std::errc::no_such_file_or_directory> )
|
||
{
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>This, however, requires C++17 or newer, because it is impossible to infer the type of the error enum (in this case, <code>std::errc</code>) from the specified type <code>std::error_code</code>, and C++11 does not allow <code>auto</code> template arguments. LEAF provides the following workaround, compatible with C++11:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">[]( leaf::match<leaf::condition<std::errc>, std::errc::no_such_file_or_directory> )
|
||
{
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>In addition, it is possible to select a handler based on <code>std::error_category</code>. The following handler will match any <code>std::error_code</code> of the <code>std::generic_category</code> (requires C++17 or newer):</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">[]( std::error_code, leaf::category<std::errc>> )
|
||
{
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
See <a href="#match"><code>match</code></a> for more examples.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The following predicates are available:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p><a href="#match"><code>match</code></a>: as described above.</p>
|
||
</li>
|
||
<li>
|
||
<p><a href="#match_value"><code>match_value</code></a>: where <code>match<E, V…​></code> compares the object <code>e</code> of type <code>E</code> with the values <code>V…​</code>, <code>match_value<E, V…​></code> compare <code>e.value</code> with the values <code>V…​</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><a href="#match_member"><code>match_member</code></a>: similar to <code>match_value</code>, but takes a pointer to the data member to compare; that is, <code>match_member<&E::value, V…​></code> is equvialent to <code>match_value<E, V…​></code>. Note, however, that <code>match_member</code> requires C++17 or newer, while <code>match_value</code> does not.</p>
|
||
</li>
|
||
<li>
|
||
<p><code><a href="#catch_">catch_</a><Ex…​></code>: Similar to <code>match</code>, but checks whether the caught <code>std::exception</code> object can be <code>dynamic_cast</code> to any of the <code>Ex</code> types.</p>
|
||
</li>
|
||
<li>
|
||
<p><a href="#if_not"><code>if_not</code></a> is a special predicate that takes any other predicate <code>Pred</code> and requires that an error object of type <code>E</code> is available and that <code>Pred</code> evaluates to <code>false</code>. For example, <code>if_not<match<E, V…​>></code> requires that an object <code>e</code> of type <code>E</code> is available, and that it does not compare equal to any of the specified <code>V…​</code>.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Finally, the predicate system is easily extensible, see <a href="#predicates">Predicates</a>.</p>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
See also <a href="#tutorial-std_error_code">Working with <code>std::error_code</code>, <code>std::error_condition</code></a>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="tutorial-binding_handlers">Binding Error Handlers in a <code>std::tuple</code></h3>
|
||
<div class="paragraph">
|
||
<p>Consider this snippet:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">leaf::try_handle_all(
|
||
[&]
|
||
{
|
||
return f(); // returns leaf::result<T>
|
||
},
|
||
|
||
[](my_error_enum x)
|
||
{
|
||
...
|
||
},
|
||
|
||
[](read_file_error_enum y, e_file_name const & fn)
|
||
{
|
||
...
|
||
},
|
||
|
||
[]
|
||
{
|
||
...
|
||
});</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#try_handle_all"><code>try_handle_all</code></a> | <a href="#e_file_name"><code>e_file_name</code></a></p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Looks pretty simple, but what if we need to attempt a different set of operations yet use the same handlers? We could repeat the same thing with a different function passed as <code>TryBlock</code> for <code>try_handle_all</code>:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">leaf::try_handle_all(
|
||
[&]
|
||
{
|
||
return g(); // returns leaf::result<T>
|
||
},
|
||
|
||
[](my_error_enum x)
|
||
{
|
||
...
|
||
},
|
||
|
||
[](read_file_error_enum y, e_file_name const & fn)
|
||
{
|
||
...
|
||
},
|
||
|
||
[]
|
||
{
|
||
...
|
||
});</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>That works, but it is better to bind our error handlers in a <code>std::tuple</code>:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">auto error_handlers = std::make_tuple(
|
||
[](my_error_enum x)
|
||
{
|
||
...
|
||
},
|
||
|
||
[](read_file_error_enum y, e_file_name const & fn)
|
||
{
|
||
...
|
||
},
|
||
|
||
[]
|
||
{
|
||
...
|
||
});</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The <code>error_handlers</code> tuple can later be used with any error handling function:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">leaf::try_handle_all(
|
||
[&]
|
||
{
|
||
// Operations which may fail <i class="conum" data-value="1"></i><b>(1)</b>
|
||
},
|
||
|
||
error_handlers );
|
||
|
||
leaf::try_handle_all(
|
||
[&]
|
||
{
|
||
// Different operations which may fail <i class="conum" data-value="2"></i><b>(2)</b>
|
||
},
|
||
|
||
error_handlers ); <i class="conum" data-value="3"></i><b>(3)</b></code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#try_handle_all"><code>try_handle_all</code></a> | <a href="#error_info"><code>error_info</code></a></p>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>One set of operations which may fail…​</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>A different set of operations which may fail…​</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="3"></i><b>3</b></td>
|
||
<td>…​ both using the same <code>error_handlers</code>.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Error-handling functions accept a <code>std::tuple</code> of error handlers in place of any error handler. The behavior is as if the tuple is unwrapped in-place.</p>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="tutorial-async">Transporting Error Objects Between Threads</h3>
|
||
<div class="paragraph">
|
||
<p>Error objects are stored on the stack in an instance of the <a href="#context"><code>context</code></a> class template in the scope of e.g. <a href="#try_handle_some"><code>try_handle_some</code></a>, <a href="#try_handle_all"><code>try_handle_all</code></a> or <a href="#try_catch"><code>try_catch</code></a> functions. When using concurrency, we need a mechanism to collect error objects in one thread, then use them to handle errors in another thread.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>LEAF offers two interfaces for this purpose, one using <code>result<T></code>, and another designed for programs that use exception handling.</p>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="tutorial-async_result">Using <code>result<T></code></h4>
|
||
<div class="paragraph">
|
||
<p>Let’s assume we have a <code>task</code> that we want to launch asynchronously, which produces a <code>task_result</code> but could also fail:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">leaf::result<task_result> task();</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Because the task will run asynchronously, in case of a failure we need it to capture the relevant error objects but not handle errors. To this end, in the main thread we bind our error handlers in a <code>std::tuple</code>, which we will later use to handle errors from each completed asynchronous task (see <a href="#tutorial-binding_handlers">tutorial</a>):</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">auto error_handlers = std::make_tuple(
|
||
[](E1 e1, E2 e2)
|
||
{
|
||
//Deal with E1, E2
|
||
....
|
||
return { };
|
||
},
|
||
|
||
[](E3 e3)
|
||
{
|
||
//Deal with E3
|
||
....
|
||
return { };
|
||
} );</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Why did we start with this step? Because we need to create a <a href="#context"><code>context</code></a> object to collect the error objects we need. We could just instantiate the <code>context</code> template with <code>E1</code>, <code>E2</code> and <code>E3</code>, but that would be prone to errors, since it could get out of sync with the handlers we use. Thankfully LEAF can deduce the types we need automatically, we just need to show it our <code>error_handlers</code>:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">std::shared_ptr<leaf::polymorphic_context> ctx = leaf::make_shared_context(error_handlers);</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The <code>polymorphic_context</code> type is an abstract base class that has the same members as any instance of the <code>context</code> class template, allowing us to erase its exact type. In this case what we’re holding in <code>ctx</code> is a <code>context<E1, E2, E3></code>, where <code>E1</code>, <code>E2</code> and <code>E3</code> were deduced automatically from the <code>error_handlers</code> tuple we passed to <code>make_shared_context</code>.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>We’re now ready to launch our asynchronous task:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">std::future<leaf::result<task_result>> launch_task() noexcept
|
||
{
|
||
return std::async(
|
||
std::launch::async,
|
||
[&]
|
||
{
|
||
std::shared_ptr<leaf::polymorphic_context> ctx = leaf::make_shared_context(error_handlers);
|
||
return leaf::capture(ctx, &task);
|
||
} );
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#result"><code>result</code></a> | <a href="#make_shared_context"><code>make_shared_context</code></a> | <a href="#capture"><code>capture</code></a></p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>That’s it! Later when we <code>get</code> the <code>std::future</code>, we can process the returned <code>result<task_result></code> in a call to <a href="#try_handle_some"><code>try_handle_some</code></a>, using the <code>error_handlers</code> tuple we created earlier:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">//std::future<leaf::result<task_result>> fut;
|
||
fut.wait();
|
||
|
||
return leaf::try_handle_some(
|
||
|
||
[&]() -> leaf::result<void>
|
||
{
|
||
BOOST_LEAF_AUTO(r, fut.get());
|
||
//Success!
|
||
return { }
|
||
},
|
||
|
||
error_handlers );</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#try_handle_some"><code>try_handle_some</code></a> | <a href="#result"><code>result</code></a> | <a href="#BOOST_LEAF_AUTO"><code>AUTO</code></a></p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The reason this works is that in case it communicates a failure, <code>leaf::result<T></code> is able to hold a <code>shared_ptr<polymorphic_context></code> object. That is why earlier instead of calling <code>task()</code> directly, we called <code>leaf::capture</code>: it calls the passed function and, in case that fails, it stores the <code>shared_ptr<polymorphic_context></code> we created in the returned <code>result<T></code>, which now doesn’t just communicate the fact that an error has occurred, but also holds the <code>context</code> object that <code>try_handle_some</code> needs in order to supply a suitable handler with arguments.</p>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
Follow this link to see a complete example program: <a href="https://github.com/boostorg/leaf/blob/master/examples/capture_in_result.cpp?ts=4">capture_in_result.cpp</a>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="tutorial-async_eh">Using Exception Handling</h4>
|
||
<div class="paragraph">
|
||
<p>Let’s assume we have an asynchronous <code>task</code> which produces a <code>task_result</code> but could also throw:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">task_result task();</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Just like we saw in <a href="#tutorial-async_result">Using <code>result<T></code></a>, first we will bind our error handlers in a <code>std::tuple</code>:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">auto handle_errors = std::make_tuple(
|
||
{
|
||
[](E1 e1, E2 e2)
|
||
{
|
||
//Deal with E1, E2
|
||
....
|
||
return { };
|
||
},
|
||
|
||
[](E3 e3)
|
||
{
|
||
//Deal with E3
|
||
....
|
||
return { };
|
||
} );</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Launching the task looks the same as before, except that we don’t use <code>result<T></code>:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">std::future<task_result> launch_task()
|
||
{
|
||
return std::async(
|
||
std::launch::async,
|
||
[&]
|
||
{
|
||
std::shared_ptr<leaf::polymorphic_context> ctx = leaf::make_shared_context(&handle_error);
|
||
return leaf::capture(ctx, &task);
|
||
} );
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#make_shared_context"><code>make_shared_context</code></a> | <a href="#capture"><code>capture</code></a></p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>That’s it! Later when we <code>get</code> the <code>std::future</code>, we can process the returned <code>task_result</code> in a call to <a href="#try_catch"><code>try_catch</code></a>, using the <code>error_handlers</code> we saved earlier, as if it was generated locally:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">//std::future<task_result> fut;
|
||
fut.wait();
|
||
|
||
return leaf::try_catch(
|
||
|
||
[&]
|
||
{
|
||
task_result r = fut.get(); // Throws on error
|
||
//Success!
|
||
},
|
||
|
||
error_handlers );</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#try_catch"><code>try_catch</code></a></p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>This works similarly to using <code>result<T></code>, except that the <code>std::shared_ptr<polymorphic_context></code> is transported in an exception object (of unspecified type which <a href="#try_catch"><code>try_catch</code></a> recognizes and then automatically unwraps the original exception).</p>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
Follow this link to see a complete example program: <a href="https://github.com/boostorg/leaf/blob/master/examples/capture_in_exception.cpp?ts=4">capture_in_exception.cpp</a>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="tutorial-classification">Classification of Failures</h3>
|
||
<div class="paragraph">
|
||
<p>It is common for any given interface to define an <code>enum</code> that lists all possible error codes that the API reports. The benefit of this approach is that the list is complete and usually contains comments, so we know where to go for reference.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The disadvantage of such flat enums is that they do not support handling a whole class of failures. Consider this error handler from the <a href="#introduction-result">introduction section</a>:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">....
|
||
[](leaf::match<error_code, size_error, read_error, eof_error>, leaf::e_errno const * errn, leaf::e_file_name const & fn)
|
||
{
|
||
std::cerr << "Failed to access " << fn.value;
|
||
if( errn )
|
||
std::cerr << ", errno=" << *errn;
|
||
std::cerr << std::endl;
|
||
return 3;
|
||
},
|
||
....</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>It will get called if the value of the <code>error_code</code> enum communicated with the failure is one of <code>size_error</code>, <code>read_error</code> or <code>eof_error</code>. In short, the idea is to handle any input error.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>But what if later we add support for detecting and reporting a new type of input error, e.g. <code>permissions_error</code>? It is easy to add that to our <code>error_code</code> enum; but now our input error handler won’t recognize this new input error — and we have a bug.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>If we can use exceptions, the situation is better because exception types can be organized in a hierarchy in order to classify failures:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">struct input_error: std::exception { };
|
||
struct read_error: input_error { };
|
||
struct size_error: input_error { };
|
||
struct eof_error: input_error { };</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>In terms of LEAF, our input error exception handler now looks like this:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">[](input_error &, leaf::e_errno const * errn, leaf::e_file_name const & fn)
|
||
{
|
||
std::cerr << "Failed to access " << fn.value;
|
||
if( errn )
|
||
std::cerr << ", errno=" << *errn;
|
||
std::cerr << std::endl;
|
||
return 3;
|
||
},</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>This is future-proof, but still not ideal, because it is not possible to refine the classification of the failure after the exception object has been thrown.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>LEAF supports a novel style of error handling where the classification of failures does not use error code values or exception type hierarchies. If we go back to the introduction section, instead of defining:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">enum error_code
|
||
{
|
||
....
|
||
read_error,
|
||
size_error,
|
||
eof_error,
|
||
....
|
||
};</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>We could define:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">....
|
||
struct input_error { };
|
||
struct read_error { };
|
||
struct size_error { };
|
||
struct eof_error { };
|
||
....</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>With this in place, <code>file_read</code> from the <a href="https://github.com/boostorg/leaf/blob/master/examples/print_file/print_file_result.cpp?ts=4">print_file_result.cpp</a> example can be rewritten like this:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">leaf::result<void> file_read( FILE & f, void * buf, int size )
|
||
{
|
||
int n = fread(buf, 1, size, &f);
|
||
|
||
if( ferror(&f) )
|
||
return leaf::new_error(input_error{}, read_error{}, leaf::e_errno{errno}); <i class="conum" data-value="1"></i><b>(1)</b>
|
||
|
||
if( n!=size )
|
||
return leaf::new_error(input_error{}, eof_error{}); <i class="conum" data-value="2"></i><b>(2)</b>
|
||
|
||
return { };
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#result"><code>result</code></a> | <a href="#new_error"><code>new_error</code></a> | <a href="#e_errno"><code>e_errno</code></a></p>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>This error is classified as <code>input_error</code> and <code>read_error</code>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>This error is classified as <code>input_error</code> and <code>eof_error</code>.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Or, even better:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">leaf::result<void> file_read( FILE & f, void * buf, int size )
|
||
{
|
||
auto load = leaf::on_error(input_error{}); <i class="conum" data-value="1"></i><b>(1)</b>
|
||
|
||
int n = fread(buf, 1, size, &f);
|
||
|
||
if( ferror(&f) )
|
||
return leaf::new_error(read_error{}, leaf::e_errno{errno}); <i class="conum" data-value="2"></i><b>(2)</b>
|
||
|
||
if( n!=size )
|
||
return leaf::new_error(eof_error{}); <i class="conum" data-value="3"></i><b>(3)</b>
|
||
|
||
return { };
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#result"><code>result</code></a> | <a href="#on_error"><code>on_error</code></a> | <a href="#new_error"><code>new_error</code></a> | <a href="#e_errno"><code>e_errno</code></a></p>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>Any error escaping this scope will be classified as <code>input_error</code></td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>In addition, this error is classified as <code>read_error</code>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="3"></i><b>3</b></td>
|
||
<td>In addition, this error is classified as <code>eof_error</code>.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>This technique works just as well if we choose to use exception handling:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">void file_read( FILE & f, void * buf, int size )
|
||
{
|
||
auto load = leaf::on_error(input_error{});
|
||
|
||
int n = fread(buf, 1, size, &f);
|
||
|
||
if( ferror(&f) )
|
||
throw leaf::exception(read_error{}, leaf::e_errno{errno});
|
||
|
||
if( n!=size )
|
||
throw leaf::exception(eof_error{});
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#on_error"><code>on_error</code></a> | <a href="#exception"><code>exception</code></a> | <a href="#e_errno"><code>e_errno</code></a></p>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
If the type of the first argument passed to <code>leaf::exception</code> derives from <code>std::exception</code>, it will be used to initialize the returned exception object taken by <code>throw</code>. Here this is not the case, so the function returns a default-initialized <code>std::exception</code> object, while the first (and any other) argument is associated with the failure.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>And now we can write a future-proof handler that can handle any <code>input_error</code>:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">....
|
||
[](input_error, leaf::e_errno const * errn, leaf::e_file_name const & fn)
|
||
{
|
||
std::cerr << "Failed to access " << fn.value;
|
||
if( errn )
|
||
std::cerr << ", errno=" << *errn;
|
||
std::cerr << std::endl;
|
||
return 3;
|
||
},
|
||
....</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Remarkably, because the classification of the failure does not depend on error codes or on exception types, this error handler can be used with <code>try_catch</code> if we use exception handling, or with <code>try_handle_some</code>/<code>try_handle_all</code> if we do not. Here is the complete example from the introduction section, rewritten to use this technique:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p><a href="https://github.com/boostorg/leaf/blob/master/examples/print_file/print_file_result_error_tags.cpp?ts=4">print_file_result_error_tags.cpp</a> (using <code>leaf::result<T></code>).</p>
|
||
</li>
|
||
<li>
|
||
<p><a href="https://github.com/boostorg/leaf/blob/master/examples/print_file/print_file_eh_error_tags.cpp?ts=4">print_file_eh_error_tags.cpp</a> (using exception handling).</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="tutorial-exception_to_result">Converting Exceptions to <code>result<T></code></h3>
|
||
<div class="paragraph">
|
||
<p>It is sometimes necessary to catch exceptions thrown by a lower-level library function, and report the error through different means, to a higher-level library which may not use exception handling.</p>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
Understand that error handlers that take arguments of types that derive from <code>std::exception</code> work correctly — regardless of whether the error object itself is thrown as an exception, or <a href="#tutorial-loading">loaded</a> into a <a href="#context"><code>context</code></a>. The technique described here is only needed when the exception must be communicated through functions which are not exception-safe, or are compiled with exception-handling disabled.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Suppose we have an exception type hierarchy and a function <code>compute_answer_throws</code>:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">class error_base: public std::exception { };
|
||
class error_a: public error_base { };
|
||
class error_b: public error_base { };
|
||
class error_c: public error_base { };
|
||
|
||
int compute_answer_throws()
|
||
{
|
||
switch( rand()%4 )
|
||
{
|
||
default: return 42;
|
||
case 1: throw error_a();
|
||
case 2: throw error_b();
|
||
case 3: throw error_c();
|
||
}
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>We can write a simple wrapper using <code>exception_to_result</code>, which calls <code>compute_answer_throws</code> and switches to <code>result<int></code> for error handling:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">leaf::result<int> compute_answer() noexcept
|
||
{
|
||
return leaf::exception_to_result<error_a, error_b>(
|
||
[]
|
||
{
|
||
return compute_answer_throws();
|
||
} );
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#result"><code>result</code></a> | <a href="#exception_to_result"><code>exception_to_result</code></a></p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The <code>exception_to_result</code> template takes any number of exception types. All exception types thrown by the passed function are caught, and an attempt is made to convert the exception object to each of the specified types. Each successfully-converted slice of the caught exception object, as well as the return value of <code>std::current_exception</code>, are copied and <a href="#tutorial-loading">loaded</a>, and in the end the exception is converted to a <code><a href="#result">result</a><T></code> object.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>(In our example, <code>error_a</code> and <code>error_b</code> slices as communicated as error objects, but <code>error_c</code> exceptions will still be captured by <code>std::exception_ptr</code>).</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Here is a simple function which prints successfully computed answers, forwarding any error (originally reported by throwing an exception) to its caller:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">leaf::result<void> print_answer() noexcept
|
||
{
|
||
BOOST_LEAF_AUTO(answer, compute_answer());
|
||
std::cout << "Answer: " << answer << std::endl;
|
||
return { };
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#result"><code>result</code></a> | <a href="#BOOST_LEAF_AUTO"><code>AUTO</code></a></p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Finally, here is a scope that handles the errors — it will work correctly regardless of whether <code>error_a</code> and <code>error_b</code> objects are thrown as exceptions or not.</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">leaf::try_handle_all(
|
||
[]() -> leaf::result<void>
|
||
{
|
||
BOOST_LEAF_CHECK(print_answer());
|
||
return { };
|
||
},
|
||
|
||
[](error_a const & e)
|
||
{
|
||
std::cerr << "Error A!" << std::endl;
|
||
},
|
||
|
||
[](error_b const & e)
|
||
{
|
||
std::cerr << "Error B!" << std::endl;
|
||
},
|
||
|
||
[]
|
||
{
|
||
std::cerr << "Unknown error!" << std::endl;
|
||
} );</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#try_handle_all"><code>try_handle_all</code></a> | <a href="#result"><code>result</code></a> | <a href="#BOOST_LEAF_CHECK"><code>CHECK</code></a></p>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
The complete program illustrating this technique is available <a href="https://github.com/boostorg/leaf/blob/master/examples/exception_to_result.cpp?ts=4">here</a>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="tutorial-on_error_in_c_callbacks">Using <code>error_monitor</code> to Report Arbitrary Errors from C-callbacks</h3>
|
||
<div class="paragraph">
|
||
<p>Communicating information pertaining to a failure detected in a C callback is tricky, because C callbacks are limited to a specific static signature, which may not use C++ types.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>LEAF makes this easy. As an example, we’ll write a program that uses Lua and reports a failure from a C++ function registered as a C callback, called from a Lua program. The failure will be propagated from C++, through the Lua interpreter (written in C), back to the C++ function which called it.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>C/C++ functions designed to be invoked from a Lua program must use the following signature:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c" data-lang="c">int do_work( lua_State * L ) ;</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Arguments are passed on the Lua stack (which is accessible through <code>L</code>). Results too are pushed onto the Lua stack.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>First, let’s initialize the Lua interpreter and register <code>do_work</code> as a C callback, available for Lua programs to call:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">std::shared_ptr<lua_State> init_lua_state() noexcept
|
||
{
|
||
std::shared_ptr<lua_State> L(lua_open(), &lua_close); <i class="conum" data-value="1"></i><b>(1)</b>
|
||
|
||
lua_register(&*L, "do_work", &do_work); <i class="conum" data-value="2"></i><b>(2)</b>
|
||
|
||
luaL_dostring(&*L, "\ <i class="conum" data-value="3"></i><b>(3)</b>
|
||
\n function call_do_work()\
|
||
\n return do_work()\
|
||
\n end");
|
||
|
||
return L;
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>Create a new <code>lua_State</code>. We’ll use <code>std::shared_ptr</code> for automatic cleanup.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>Register the <code>do_work</code> C++ function as a C callback, under the global name <code>do_work</code>. With this, calls from Lua programs to <code>do_work</code> will land in the <code>do_work</code> C++ function.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="3"></i><b>3</b></td>
|
||
<td>Pass some Lua code as a <code>C</code> string literal to Lua. This creates a global Lua function called <code>call_do_work</code>, which we will later ask Lua to execute.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Next, let’s define our <code>enum</code> used to communicate <code>do_work</code> failures:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">enum do_work_error_code
|
||
{
|
||
ec1=1,
|
||
ec2
|
||
};</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>We’re now ready to define the <code>do_work</code> callback function:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">int do_work( lua_State * L ) noexcept
|
||
{
|
||
bool success = rand()%2; <i class="conum" data-value="1"></i><b>(1)</b>
|
||
if( success )
|
||
{
|
||
lua_pushnumber(L, 42); <i class="conum" data-value="2"></i><b>(2)</b>
|
||
return 1;
|
||
}
|
||
else
|
||
{
|
||
leaf::new_error(ec1); <i class="conum" data-value="3"></i><b>(3)</b>
|
||
return luaL_error(L, "do_work_error"); <i class="conum" data-value="4"></i><b>(4)</b>
|
||
}
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#new_error"><code>new_error</code></a> | <a href="#error_id::load"><code>load</code></a></p>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>"Sometimes" <code>do_work</code> fails.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>In case of success, push the result on the Lua stack, return back to Lua.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="3"></i><b>3</b></td>
|
||
<td>Generate a new <code>error_id</code> and associate a <code>do_work_error_code</code> with it. Normally, we’d return this in a <code>leaf::result<T></code>, but the <code>do_work</code> function signature (required by Lua) does not permit this.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="4"></i><b>4</b></td>
|
||
<td>Tell the Lua interpreter to abort the Lua program.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Now we’ll write the function that calls the Lua interpreter to execute the Lua function <code>call_do_work</code>, which in turn calls <code>do_work</code>. We’ll return <code><a href="#result">result</a><int></code>, so that our caller can get the answer in case of success, or an error:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">leaf::result<int> call_lua( lua_State * L )
|
||
{
|
||
lua_getfield(L, LUA_GLOBALSINDEX, "call_do_work");
|
||
|
||
error_monitor cur_err;
|
||
if( int err=lua_pcall(L, 0, 1, 0) ) <i class="conum" data-value="1"></i><b>(1)</b>
|
||
{
|
||
auto load = leaf::on_error(e_lua_error_message{lua_tostring(L,1)}); <i class="conum" data-value="2"></i><b>(2)</b>
|
||
lua_pop(L,1);
|
||
|
||
return cur_err.assigned_error_id().load(e_lua_pcall_error{err}); <i class="conum" data-value="3"></i><b>(3)</b>
|
||
}
|
||
else
|
||
{
|
||
int answer = lua_tonumber(L, -1); <i class="conum" data-value="4"></i><b>(4)</b>
|
||
lua_pop(L, 1);
|
||
return answer;
|
||
}
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#result"><code>result</code></a> | <a href="#on_error"><code>on_error</code></a> | <a href="#error_monitor"><code>error_monitor</code></a></p>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>Ask the Lua interpreter to call the global Lua function <code>call_do_work</code>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td><code>on_error</code> works as usual.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="3"></i><b>3</b></td>
|
||
<td><code>load</code> will use the <code>error_id</code> generated in our Lua callback. This is the same <code>error_id</code> the <code>on_error</code> uses as well.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="4"></i><b>4</b></td>
|
||
<td>Success! Just return the <code>int</code> answer.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Finally, here is the <code>main</code> function which exercises <code>call_lua</code>, each time handling any failure:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">int main() noexcept
|
||
{
|
||
std::shared_ptr<lua_State> L=init_lua_state();
|
||
|
||
for( int i=0; i!=10; ++i )
|
||
{
|
||
leaf::try_handle_all(
|
||
|
||
[&]() -> leaf::result<void>
|
||
{
|
||
BOOST_LEAF_AUTO(answer, call_lua(&*L));
|
||
std::cout << "do_work succeeded, answer=" << answer << '\n'; <i class="conum" data-value="1"></i><b>(1)</b>
|
||
return { };
|
||
},
|
||
|
||
[](do_work_error_code e) <i class="conum" data-value="2"></i><b>(2)</b>
|
||
{
|
||
std::cout << "Got do_work_error_code = " << e << "!\n";
|
||
},
|
||
|
||
[](e_lua_pcall_error const & err, e_lua_error_message const & msg) <i class="conum" data-value="3"></i><b>(3)</b>
|
||
{
|
||
std::cout << "Got e_lua_pcall_error, Lua error code = " << err.value << ", " << msg.value << "\n";
|
||
},
|
||
|
||
[](leaf::error_info const & unmatched)
|
||
{
|
||
std::cerr <<
|
||
"Unknown failure detected" << std::endl <<
|
||
"Cryptic diagnostic information follows" << std::endl <<
|
||
unmatched;
|
||
} );
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#try_handle_all"><code>try_handle_all</code></a> | <a href="#result"><code>result</code></a> | <a href="#BOOST_LEAF_AUTO"><code>AUTO</code></a> | <a href="#error_info"><code>error_info</code></a></p>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>If the call to <code>call_lua</code> succeeded, just print the answer.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>Handle <code>do_work</code> failures.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="3"></i><b>3</b></td>
|
||
<td>Handle all other <code>lua_pcall</code> failures.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
Follow this link to see the complete program: <a href="https://github.com/boostorg/leaf/blob/master/examples/lua_callback_result.cpp?ts=4">lua_callback_result.cpp</a>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
When using Lua with C++, we need to protect the Lua interpreter from exceptions that may be thrown from C++ functions installed as <code>lua_CFunction</code> callbacks. Here is the program from this section rewritten to use a C++ exception to safely communicate errors out of the <code>do_work</code> function: <a href="https://github.com/boostorg/leaf/blob/master/examples/lua_callback_eh.cpp?ts=4">lua_callback_eh.cpp</a>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="tutorial-diagnostic_information">Diagnostic Information</h3>
|
||
<div class="paragraph">
|
||
<p>LEAF is able to automatically generate diagnostic messages that include information about all error objects available to error handlers. For this purpose, it needs to be able to print objects of user-defined error types.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>To do this, LEAF attempts to bind an unqualified call to <code>operator<<</code>, passing a <code>std::ostream</code> and the error object. If that fails, it will also attempt to bind <code>operator<<</code> that takes the <code>.value</code> of the error type. If that also doesn’t compile, the error object value will not appear in diagnostic messages, though LEAF will still print its type.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Even with error types that define a printable <code>.value</code>, the user may still want to overload <code>operator<<</code> for the enclosing <code>struct</code>, e.g.:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">struct e_errno
|
||
{
|
||
int value;
|
||
|
||
friend std::ostream & operator<<( std::ostream & os, e_errno const & e )
|
||
{
|
||
return os << "errno = " << e.value << ", \"" << strerror(e.value) << '"';
|
||
}
|
||
};</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The <code>e_errno</code> type above is designed to hold <code>errno</code> values. The defined <code>operator<<</code> overload will automatically include the output from <code>strerror</code> when <code>e_errno</code> values are printed (LEAF defines <code>e_errno</code> in <code><boost/leaf/common.hpp></code>, together with other commonly-used error types).</p>
|
||
</div>
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
The automatically-generated diagnostic messages are developer-friendly, but not user-friendly. Therefore, <code>operator<<</code> overloads for error types should only print technical information in English, and should not attempt to localize strings or to format a user-friendly message; this should be done in error-handling functions specifically designed for that purpose.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="tutorial-std_error_code">Working with <code>std::error_code</code>, <code>std::error_condition</code></h3>
|
||
<div class="sect3">
|
||
<h4 id="_introduction">Introduction</h4>
|
||
<div class="paragraph">
|
||
<p>The relationship between <code>std::error_code</code> and <code>std::error_condition</code> is not easily understood from reading the standard specifications. This section explains how they’re supposed to be used, and how LEAF interacts with them.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The idea behind <code>std::error_code</code> is to encode both an integer value representing an error code, as well as the domain of that value. The domain is represented by a <code>std::error_category</code> <span class="underline">reference</span>. Conceptually, a <code>std::error_code</code> is like a <code>pair<std::error_category const &, int></code>.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Let’s say we have this <code>enum</code>:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">enum class libfoo_error
|
||
{
|
||
e1 = 1,
|
||
e2,
|
||
e3
|
||
};</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>We want to be able to transport <code>libfoo_error</code> values in <code>std::error_code</code> objects. This erases their static type, which enables them to travel freely across API boundaries. To this end, we must define a <code>std::error_category</code> that represents our <code>libfoo_error</code> type:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">std::error_category const & libfoo_error_category()
|
||
{
|
||
struct category: std::error_category
|
||
{
|
||
char const * name() const noexcept override
|
||
{
|
||
return "libfoo";
|
||
}
|
||
|
||
std::string message(int code) const override
|
||
{
|
||
switch( libfoo_error(code) )
|
||
{
|
||
case libfoo_error::e1: return "e1";
|
||
case libfoo_error::e2: return "e2";
|
||
case libfoo_error::e3: return "e3";
|
||
default: return "error";
|
||
}
|
||
}
|
||
};
|
||
|
||
static category c;
|
||
return c;
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>We also need to inform the standard library that <code>libfoo_error</code> is compatible with <code>std::error_code</code>, and provide a factory function which can be used to make <code>std::error_code</code> objects out of <code>libfoo_error</code> values:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace std
|
||
{
|
||
template <>
|
||
struct is_error_code_enum<libfoo_error>: std::true_type
|
||
{
|
||
};
|
||
}
|
||
|
||
std::error_code make_error_code(libfoo_error e)
|
||
{
|
||
return std::error_code(int(e), libfoo_error_category());
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>With this in place, if we receive a <code>std::error_code</code>, we can easily check if it represents some of the <code>libfoo_error</code> values we’re interested in:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">std::error_code f();
|
||
|
||
....
|
||
auto ec = f();
|
||
if( ec == libfoo_error::e1 || ec == libfoo_error::e2 )
|
||
{
|
||
// We got either a libfoo_error::e1 or a libfoo_error::e2
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>This works because the standard library detects that <code>std::is_error_code_enum<libfoo_error>::value</code> is <code>true</code>, and then uses <code>make_error_code</code> to create a <code>std::error_code</code> object it actually uses to compare to <code>ec</code>.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>So far so good, but remember, the standard library defines another type also, <code>std::error_condition</code>. The first confusing thing is that in terms of its physical representation, <code>std::error_condition</code> is identical to <code>std::error_code</code>; that is, it is also like a pair of <code>std::error_category</code> reference and an <code>int</code>. Why do we need two different types which use identical physical representation?</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The key to answering this question is to understand that <code>std::error_code</code> objects are designed to be returned from functions to indicate failures. In contrast, <code>std::error_condition</code> objects are <span class="underline">never</span> supposed to be communicated; their purpose is to interpret the <code>std::error_code</code> values being communicated. The idea is that in a given program there may be multiple different "physical" (maybe platform-specific) <code>std::error_code</code> values which all indicate the same "logical" <code>std::error_condition</code>.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>This leads us to the second confusing thing about <code>std::error_condition</code>: it uses the same <code>std::error_category</code> type, but for a completely different purpose: to specify what <code>std::error_code</code> values are equivalent to what <code>std::error_condition</code> values.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Let’s say that in addition to <code>libfoo</code>, our program uses another library, <code>libbar</code>, which communicates failures in terms of <code>std::error_code</code> with a different error category. Perhaps <code>libbar_error</code> looks like this:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">enum class libbar_error
|
||
{
|
||
e1 = 1,
|
||
e2,
|
||
e3,
|
||
e4
|
||
};
|
||
|
||
// Boilerplate omitted:
|
||
// - libbar_error_category()
|
||
// - specialization of std::is_error_code_enum
|
||
// - make_error_code factory function for libbar_error.</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>We can now use <code>std::error_condition</code> to define the <em>logical</em> error conditions represented by the <code>std::error_code</code> values communicated by <code>libfoo</code> and <code>libbar</code>:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">enum class my_error_condition <i class="conum" data-value="1"></i><b>(1)</b>
|
||
{
|
||
c1 = 1,
|
||
c2
|
||
};
|
||
|
||
std::error_category const & libfoo_error_category() <i class="conum" data-value="2"></i><b>(2)</b>
|
||
{
|
||
struct category: std::error_category
|
||
{
|
||
char const * name() const noexcept override
|
||
{
|
||
return "my_error_condition";
|
||
}
|
||
|
||
std::string message(int cond) const override
|
||
{
|
||
switch( my_error_condition(code) )
|
||
{
|
||
case my_error_condition::c1: return "c1";
|
||
case my_error_condition::c2: return "c2";
|
||
default: return "error";
|
||
}
|
||
}
|
||
|
||
bool equivalent(std::error_code const & code, int cond) const noexcept
|
||
{
|
||
switch( my_error_condition(cond) )
|
||
{
|
||
case my_error_condition::c1: <i class="conum" data-value="3"></i><b>(3)</b>
|
||
return
|
||
code == libfoo_error::e1 ||
|
||
code == libbar_error::e3 ||
|
||
code == libbar_error::e4;
|
||
case my_error_condition::c2: <i class="conum" data-value="4"></i><b>(4)</b>
|
||
return
|
||
code == libfoo_error::e2 ||
|
||
code == libbar_error::e1 ||
|
||
code == libbar_error::e2;
|
||
default:
|
||
return false;
|
||
}
|
||
}
|
||
};
|
||
|
||
static category c;
|
||
return c;
|
||
}
|
||
|
||
namespace std
|
||
{
|
||
template <> <i class="conum" data-value="5"></i><b>(5)</b>
|
||
class is_error_condition_enum<my_error_condition>: std::true_type
|
||
{
|
||
};
|
||
}
|
||
|
||
std::error_condition make_error_condition(my_error_condition e) <i class="conum" data-value="6"></i><b>(6)</b>
|
||
{
|
||
return std::error_condition(int(e), my_error_condition_error_category());
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>Enumeration of the two logical error conditions, <code>c1</code> and <code>c2</code>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>Define the <code>std::error_category</code> for <code>std::error_condition</code> objects that represent a <code>my_error_condition</code>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="3"></i><b>3</b></td>
|
||
<td>Here we specify that any of <code>libfoo:error::e1</code>, <code>libbar_error::e3</code> and <code>libbar_error::e4</code> are logically equivalent to <code>my_error_condition::c1</code>, and that…​</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="4"></i><b>4</b></td>
|
||
<td>…​any of <code>libfoo:error::e2</code>, <code>libbar_error::e1</code> and <code>libbar_error::e2</code> are logically equivalent to <code>my_error_condition::c2</code>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="5"></i><b>5</b></td>
|
||
<td>This specialization tells the standard library that the <code>my_error_condition</code> enum is designed to be used with <code>std::error_condition</code>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="6"></i><b>6</b></td>
|
||
<td>The factory function to make <code>std::error_condition</code> objects out of <code>my_error_condition</code> values.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Phew!</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Now, if we have a <code>std::error_code</code> object <code>ec</code>, we can easily check if it is equivalent to <code>my_error_condition::c1</code> like so:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">if( ec == my_error_condition::c1 )
|
||
{
|
||
// We have a c1 in our hands
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Again, remember that beyond defining the <code>std::error_category</code> for <code>std::error_condition</code> objects initialized with a <code>my_error_condition</code> value, we don’t need to interact with the actual <code>std::error_condition</code> instances: they’re created when needed to compare to a <code>std::error_code</code>, and that’s pretty much all they’re good for.</p>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="_support_in_leaf">Support in LEAF</h4>
|
||
<div class="paragraph">
|
||
<p>The following support for <code>std::error_code</code> and <code>std::error_condition</code> is available:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>The <a href="#match"><code>match</code></a> template can be used as an argument to a LEAF error handler, so it can be considered based on the value of a communicated <code>std::error_code</code>.</p>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
See <a href="#match"><code>match</code></a> for examples.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</li>
|
||
<li>
|
||
<p>The <a href="#error_id"><code>error_id</code></a> type can be converted to a <code>std::error_code</code>; see <a href="#error_id::to_error_code"><code>to_error_code</code></a>. The returned object encodes the state of the <code>error_id</code> without any loss of information. This is useful if an <code>error_id</code> needs to be communicated through interfaces that support <code>std::error_code</code> but do not use LEAF.</p>
|
||
</li>
|
||
<li>
|
||
<p>The <code>error_id</code> type can be implicitly initialized with a <code>std::error_code</code>. If the <code>std::error_code</code> was created using <code>to_error_code</code>, the original <code>error_id</code> state is restored. Otherwise, the <code>std::error_code</code> is <a href="#tutorial-loading">loaded</a> so it can be used by LEAF error handlers, while the <code>error_id</code> itself is initialized by <a href="#new_error"><code>new_error</code></a>.</p>
|
||
</li>
|
||
<li>
|
||
<p>The <code>leaf::result<T></code> type can be implicitly initialized with an <code>error_id</code>, which means that it can be implicitly initialized with a <code>std::error_code</code>.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="tutorial-boost_exception_integration">Boost Exception Integration</h3>
|
||
<div class="paragraph">
|
||
<p>Instead of the <a href="https://www.boost.org/doc/libs/release/libs/exception/doc/get_error_info.html"><code>boost::get_error_info</code></a> API defined by Boost Exception, it is possible to use LEAF error handlers directly. Consider the following use of <code>boost::get_error_info</code>:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">typedef boost::error_info<struct my_info_, int> my_info;
|
||
|
||
void f(); // Throws using boost::throw_exception
|
||
|
||
void g()
|
||
{
|
||
try
|
||
{
|
||
f();
|
||
},
|
||
catch( boost::exception & e )
|
||
{
|
||
if( int const * x = boost::get_error_info<my_info>(e) )
|
||
std::cerr << "Got my_info with value = " << *x;
|
||
} );
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>We can rewrite <code>g</code> to access <code>my_info</code> using LEAF:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">#include <boost/leaf/handle_errors.hpp>
|
||
|
||
void g()
|
||
{
|
||
leaf::try_catch(
|
||
[]
|
||
{
|
||
f();
|
||
},
|
||
|
||
[]( my_info x )
|
||
{
|
||
std::cerr << "Got my_info with value = " << x.value();
|
||
} );
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#try_catch"><code>try_catch</code></a></p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Taking <code>my_info</code> means that the handler will only be selected if the caught exception object carries <code>my_info</code> (which LEAF accesses via <code>boost::get_error_info</code>).</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The use of <a href="#match"><code>match</code></a> is also supported:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">void g()
|
||
{
|
||
leaf::try_catch(
|
||
[]
|
||
{
|
||
f();
|
||
},
|
||
|
||
[]( leaf::match_value<my_info, 42> )
|
||
{
|
||
std::cerr << "Got my_info with value = 42";
|
||
} );
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Above, the handler will be selected if the caught exception object carries <code>my_info</code> with <code>.value()</code> equal to 42.</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="examples">Examples</h2>
|
||
<div class="sectionbody">
|
||
<div class="paragraph">
|
||
<p>See <a href="https://github.com/boostorg/leaf/tree/master/examples">github</a>.</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="synopsis">Synopsis</h2>
|
||
<div class="sectionbody">
|
||
<div class="paragraph">
|
||
<p>This section lists each public header file in LEAF, documenting the definitions it provides.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>LEAF headers are designed to minimize coupling:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>Headers needed to report or forward but not handle errors are lighter than headers providing error-handling functionality.</p>
|
||
</li>
|
||
<li>
|
||
<p>Headers that provide exception handling or throwing functionality are separate from headers that provide error-handling or reporting but do not use exceptions.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>A standalone single-header option is available; please <code>#include <boost/leaf.hpp></code>.</p>
|
||
</div>
|
||
<hr>
|
||
<div class="sect2">
|
||
<h3 id="synopsis-reporting">Error Reporting</h3>
|
||
<div class="sect3">
|
||
<h4 id="error.hpp"><code>error.hpp</code></h4>
|
||
<div class="exampleblock">
|
||
<div class="content">
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/error.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
class error_id
|
||
{
|
||
public:
|
||
|
||
error_id() noexcept;
|
||
|
||
template <class Enum>
|
||
error_id( Enum e, typename std::enable_if<std::is_error_code_enum<Enum>::value, Enum>::type * = 0 ) noexcept;
|
||
|
||
error_id( std::error_code const & ec ) noexcept;
|
||
|
||
int value() const noexcept;
|
||
explicit operator bool() const noexcept;
|
||
|
||
std::error_code to_error_code() const noexept;
|
||
|
||
friend bool operator==( error_id a, error_id b ) noexcept;
|
||
friend bool operator!=( error_id a, error_id b ) noexcept;
|
||
friend bool operator<( error_id a, error_id b ) noexcept;
|
||
|
||
template <class... Item>
|
||
error_id load( Item && ... item ) const noexcept;
|
||
|
||
friend std::ostream & operator<<( std::ostream & os, error_id x );
|
||
};
|
||
|
||
bool is_error_id( std::error_code const & ec ) noexcept;
|
||
|
||
template <class... Item>
|
||
error_id new_error( Item && ... item ) noexcept;
|
||
|
||
error_id current_error() noexcept;
|
||
|
||
//////////////////////////////////////////
|
||
|
||
class polymorphic_context
|
||
{
|
||
protected:
|
||
|
||
polymorphic_context() noexcept = default;
|
||
~polymorphic_context() noexcept = default;
|
||
|
||
public:
|
||
|
||
virtual void activate() noexcept = 0;
|
||
virtual void deactivate() noexcept = 0;
|
||
virtual bool is_active() const noexcept = 0;
|
||
|
||
virtual void propagate() noexcept = 0;
|
||
|
||
virtual void print( std::ostream & ) const = 0;
|
||
};
|
||
|
||
//////////////////////////////////////////
|
||
|
||
template <class Ctx>
|
||
class context_activator
|
||
{
|
||
context_activator( context_activator const & ) = delete;
|
||
context_activator & operator=( context_activator const & ) = delete;
|
||
|
||
public:
|
||
|
||
explicit context_activator( Ctx & ctx ) noexcept;
|
||
context_activator( context_activator && ) noexcept;
|
||
~context_activator() noexcept;
|
||
};
|
||
|
||
template <class Ctx>
|
||
context_activator<Ctx> activate_context( Ctx & ctx ) noexcept;
|
||
|
||
template <class R>
|
||
struct is_result_type: std::false_type
|
||
{
|
||
};
|
||
|
||
template <class R>
|
||
struct is_result_type<R const>: is_result_type<R>
|
||
{
|
||
};
|
||
|
||
} }
|
||
|
||
#define BOOST_LEAF_ASSIGN(v, r)\
|
||
auto && <<temp>> = r;\
|
||
if( !<<temp>> )\
|
||
return <<temp>>.error();\
|
||
v = std::forward<decltype(<<temp>>)>(<<temp>>).value()
|
||
|
||
#define BOOST_LEAF_AUTO(v, r)\
|
||
BOOST_LEAF_ASSIGN(auto v, r)
|
||
|
||
#define BOOST_LEAF_CHECK(r)\
|
||
auto && <<temp>> = r;\
|
||
if( <<temp>> )\
|
||
;\
|
||
else\
|
||
return <<temp>>.error()
|
||
|
||
#define BOOST_LEAF_NEW_ERROR <<inject e_source_location voodoo>> ::boost::leaf::new_error</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p>Reference: <a href="#error_id"><code>error_id</code></a> | <a href="#is_error_id"><code>is_error_id</code></a> | <a href="#new_error"><code>new_error</code></a> | <a href="#current_error"><code>current_error</code></a> | <a href="#polymorphic_context"><code>polymorphic_context</code></a> | <a href="#context_activator"><code>context_activator</code></a> | <a href="#activate_context"><code>activate_context</code></a> | <a href="#is_result_type"><code>is_result_type</code></a> | <a href="#BOOST_LEAF_ASSIGN"><code>ASSIGN</code></a> | <a href="#BOOST_LEAF_AUTO"><code>AUTO</code></a> | <a href="#BOOST_LEAF_CHECK"><code>CHECK</code></a> | <a href="#BOOST_LEAF_NEW_ERROR"><code>NEW_ERROR</code></a></p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="common.hpp"><code>common.hpp</code></h4>
|
||
<div class="exampleblock">
|
||
<div class="content">
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/common.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
struct e_api_function { char const * value; };
|
||
|
||
struct e_file_name { std::string value; };
|
||
|
||
struct e_type_info_name { char const * value; };
|
||
|
||
struct e_at_line { int value; };
|
||
|
||
struct e_errno
|
||
{
|
||
int value;
|
||
friend std::ostream & operator<<( std::ostream &, e_errno const & );
|
||
};
|
||
|
||
namespace windows
|
||
{
|
||
struct e_LastError
|
||
{
|
||
unsigned value;
|
||
friend std::ostream & operator<<( std::ostream &, e_LastError const & );
|
||
};
|
||
}
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p>Reference: <a href="#e_api_function"><code>e_api_function</code></a> | <a href="#e_file_name"><code>e_file_name</code></a> | <a href="#e_at_line"><code>e_at_line</code></a> | <a href="#e_type_info_name"><code>e_type_info_name</code></a> | <a href="#e_source_location"><code>e_source_location</code></a> | <a href="#e_errno"><code>e_errno</code></a> | <a href="#e_LastError"><code>e_LastError</code></a></p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="result.hpp"><code>result.hpp</code></h4>
|
||
<div class="exampleblock">
|
||
<div class="content">
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/result.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class T>
|
||
class result
|
||
{
|
||
public:
|
||
|
||
result() noexcept;
|
||
result( T && v ) noexcept;
|
||
result( T const & v );
|
||
|
||
template <class U>
|
||
result( U && u, <<enabled_if_T_can_be_inited_with_U>> );
|
||
|
||
result( error_id err ) noexcept;
|
||
result( std::shared_ptr<polymorphic_context> && ctx ) noexcept;
|
||
|
||
template <class Enum>
|
||
result( Enum e, typename std::enable_if<std::is_error_code_enum<Enum>::value, Enum>::type * = 0 ) noexcept;
|
||
|
||
result( std::error_code const & ec ) noexcept;
|
||
|
||
result( result && r ) noexcept;
|
||
|
||
template <class U>
|
||
result( result<U> && r ) noexcept;
|
||
|
||
result & operator=( result && r ) noexcept;
|
||
|
||
template <class U>
|
||
result & operator=( result<U> && r ) noexcept;
|
||
|
||
explicit operator bool() const noexcept;
|
||
|
||
T const & value() const;
|
||
T & value();
|
||
|
||
T const & operator*() const;
|
||
T & operator*();
|
||
|
||
T const * operator->() const;
|
||
T * operator->();
|
||
|
||
<<unspecified-type>> error() noexcept;
|
||
|
||
template <class... Item>
|
||
error_id load( Item && ... item ) noexcept;
|
||
};
|
||
|
||
template <>
|
||
class result<void>
|
||
{
|
||
public:
|
||
|
||
result() noexcept;
|
||
|
||
result( error_id err ) noexcept;
|
||
result( std::shared_ptr<polymorphic_context> && ctx ) noexcept;
|
||
|
||
template <class Enum>
|
||
result( Enum e, typename std::enable_if<std::is_error_code_enum<Enum>::value, Enum>::type * = 0 ) noexcept;
|
||
|
||
result( std::error_code const & ec ) noexcept;
|
||
|
||
result( result && r ) noexcept;
|
||
|
||
template <class U>
|
||
result( result<U> && r ) noexcept;
|
||
|
||
result & operator=( result && r ) noexcept;
|
||
|
||
template <class U>
|
||
result & operator=( result<U> && r ) noexcept;
|
||
|
||
explicit operator bool() const noexcept;
|
||
|
||
void value() const;
|
||
|
||
<<unspecified-type>> error() noexcept;
|
||
|
||
template <class... Item>
|
||
error_id load( Item && ... item ) noexcept;
|
||
};
|
||
|
||
struct bad_result: std::exception { };
|
||
|
||
template <class T>
|
||
struct is_result_type<result<T>>: std::true_type
|
||
{
|
||
};
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p>Reference: <a href="#result"><code>result</code></a> | <a href="#is_result_type"><code>is_result_type</code></a></p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="on_error.hpp"><code>on_error.hpp</code></h4>
|
||
<div class="exampleblock">
|
||
<div class="content">
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/on_error.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class... Item>
|
||
<<unspecified-type>> on_error( Item && ... e ) noexcept;
|
||
|
||
class error_monitor
|
||
{
|
||
public:
|
||
|
||
error_monitor() noexcept;
|
||
|
||
error_id check() const noexcept;
|
||
error_id assigned_error_id() const noexcept;
|
||
};
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p>Reference: <a href="#on_error"><code>on_error</code></a> | <a href="#error_monitor"><code>error_monitor</code></a></p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="exception.hpp"><code>exception.hpp</code></h4>
|
||
<div class="exampleblock">
|
||
<div class="content">
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/exception.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class Ex, class... E> <i class="conum" data-value="1"></i><b>(1)</b>
|
||
<<unspecified-exception-type>> exception( Ex &&, E && ... ) noexcept;
|
||
|
||
template <class E1, class... E> <i class="conum" data-value="2"></i><b>(2)</b>
|
||
<<unspecified-exception-type>> exception( E1 &&, E && ... ) noexcept;
|
||
|
||
<<unspecified-exception-type>> exception() noexcept;
|
||
|
||
template <class Ex, class... E> <i class="conum" data-value="1"></i><b>(1)</b>
|
||
<<unspecified-exception-type>> exception( error_id id, Ex &&, E && ... ) noexcept;
|
||
|
||
template <class E1, class... E> <i class="conum" data-value="2"></i><b>(2)</b>
|
||
<<unspecified-exception-type>> exception( error_id id, E1 &&, E && ... ) noexcept;
|
||
|
||
<<unspecified-exception-type>> exception( error_id id ) noexcept;
|
||
|
||
} }
|
||
|
||
#define BOOST_LEAF_EXCEPTION <<inject e_source_location voodoo>> ::boost::leaf::exception
|
||
|
||
#define BOOST_LEAF_THROW_EXCEPTION <<inject e_source_location + invoke boost::throw_exception voodoo>> ::boost::leaf::exception</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p>Reference: <a href="#exception"><code>exception</code></a> | <a href="#BOOST_LEAF_EXCEPTION"><code>EXCEPTION</code></a> | <a href="#BOOST_LEAF_THROW_EXCEPTION"><code>THROW_EXCEPTION</code></a></p>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>Only enabled if std::is_base_of<std::exception, Ex>::value.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>Only enabled if !std::is_base_of<std::exception, E1>::value.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="_capture_hpp"><code>capture.hpp</code></h4>
|
||
<div class="exampleblock">
|
||
<div class="content">
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/capture_exception.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class F, class... A>
|
||
decltype(std::declval<F>()(std::forward<A>(std::declval<A>())...))
|
||
capture(std::shared_ptr<polymorphic_context> && ctx, F && f, A... a);
|
||
|
||
template <class... Ex, class F>
|
||
<<result<T>-deduced>> exception_to_result( F && f ) noexcept;
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p>Reference: <a href="#capture"><code>capture</code></a> | <a href="#exception_to_result"><code>exception_to_result</code></a></p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="tutorial-handling">Error Handling</h3>
|
||
<div class="sect3">
|
||
<h4 id="context.hpp"><code>context.hpp</code></h4>
|
||
<div class="exampleblock">
|
||
<div class="content">
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/context.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class... E>
|
||
class context
|
||
{
|
||
context( context const & ) = delete;
|
||
context & operator=( context const & ) = delete;
|
||
|
||
public:
|
||
|
||
context() noexcept;
|
||
context( context && x ) noexcept;
|
||
~context() noexcept;
|
||
|
||
void activate() noexcept;
|
||
void deactivate() noexcept;
|
||
bool is_active() const noexcept;
|
||
|
||
void propagate () noexcept;
|
||
|
||
void print( std::ostream & os ) const;
|
||
|
||
template <class R, class... H>
|
||
R handle_error( R &, H && ... ) const;
|
||
};
|
||
|
||
//////////////////////////////////////////
|
||
|
||
template <class... H>
|
||
using context_type_from_handlers = typename <<unspecified>>::type;
|
||
|
||
template <class... H>
|
||
BOOST_LEAF_CONSTEXPR context_type_from_handlers<H...> make_context() noexcept;
|
||
|
||
template <class... H>
|
||
BOOST_LEAF_CONSTEXPR context_type_from_handlers<H...> make_context( H && ... ) noexcept;
|
||
|
||
template <class... H>
|
||
context_ptr make_shared_context() noexcept;
|
||
|
||
template <class... H>
|
||
context_ptr make_shared_context( H && ... ) noexcept;
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p>Reference: <a href="#context"><code>context</code></a> | <a href="#context_type_from_handlers"><code>context_type_from_handlers</code></a> | <a href="#make_context"><code>make_context</code></a> | <a href="#make_shared_context"><code>make_shared_context</code></a></p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="handle_errors.hpp"><code>handle_errors.hpp</code></h4>
|
||
<div class="exampleblock">
|
||
<div class="content">
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/handle_errors.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class TryBlock, class... H>
|
||
typename std::decay<decltype(std::declval<TryBlock>()().value())>::type
|
||
try_handle_all( TryBlock && try_block, H && ... h );
|
||
|
||
template <class TryBlock, class... H>
|
||
typename std::decay<decltype(std::declval<TryBlock>()())>::type
|
||
try_handle_some( TryBlock && try_block, H && ... h );
|
||
|
||
template <class TryBlock, class... H>
|
||
typename std::decay<decltype(std::declval<TryBlock>()())>::type
|
||
try_catch( TryBlock && try_block, H && ... h );
|
||
|
||
//////////////////////////////////////////
|
||
|
||
class error_info
|
||
{
|
||
//No public constructors
|
||
|
||
public:
|
||
|
||
error_id error() const noexcept;
|
||
|
||
bool exception_caught() const noexcept;
|
||
std::exception const * exception() const noexcept;
|
||
|
||
friend std::ostream & operator<<( std::ostream & os, error_info const & x );
|
||
};
|
||
|
||
class diagnostic_info: public error_info
|
||
{
|
||
//No public constructors
|
||
|
||
friend std::ostream & operator<<( std::ostream & os, diagnostic_info const & x );
|
||
};
|
||
|
||
class verbose_diagnostic_info: public error_info
|
||
{
|
||
//No public constructors
|
||
|
||
friend std::ostream & operator<<( std::ostream & os, diagnostic_info const & x );
|
||
};
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p>Reference: <a href="#try_handle_all"><code>try_handle_all</code></a> | <a href="#try_handle_some"><code>try_handle_some</code></a> | <a href="#try_catch"><code>try_catch</code></a> | <a href="#error_info"><code>error_info</code></a> | <a href="#diagnostic_info"><code>diagnostic_info</code></a> | <a href="#verbose_diagnostic_info"><code>verbose_diagnostic_info</code></a></p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="pred.hpp"><code>pred.hpp</code></h4>
|
||
<div class="exampleblock">
|
||
<div class="content">
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/pred.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class T>
|
||
struct is_predicate: std::false_type
|
||
{
|
||
};
|
||
|
||
template <class E, auto... V>
|
||
struct match
|
||
{
|
||
E matched;
|
||
|
||
// Other members not specified
|
||
};
|
||
|
||
template <class E, auto... V>
|
||
struct is_predicate<match<E, V...>>: std::true_type
|
||
{
|
||
};
|
||
|
||
template <class E, auto... V>
|
||
struct match_value
|
||
{
|
||
E matched;
|
||
|
||
// Other members not specified
|
||
};
|
||
|
||
template <class E, auto... V>
|
||
struct is_predicate<match_value<E, V...>>: std::true_type
|
||
{
|
||
};
|
||
|
||
template <auto, auto...>
|
||
struct match_member;
|
||
|
||
template <class E, class T, T E::* P, auto... V>
|
||
struct member<P, V...>
|
||
{
|
||
E matched;
|
||
|
||
// Other members not specified
|
||
};
|
||
|
||
template <auto P, auto... V>
|
||
struct is_predicate<match_member<P, V...>>: std::true_type
|
||
{
|
||
};
|
||
|
||
template <class... Ex>
|
||
struct catch_
|
||
{
|
||
std::exception const & matched;
|
||
|
||
// Other members not specified
|
||
};
|
||
|
||
template <class Ex>
|
||
struct catch_<Ex>
|
||
{
|
||
Ex const & matched;
|
||
|
||
// Other members not specified
|
||
};
|
||
|
||
template <class... Ex>
|
||
struct is_predicate<catch_<Ex...>>: std::true_type
|
||
{
|
||
};
|
||
|
||
template <class Pred>
|
||
struct if_not
|
||
{
|
||
E matched;
|
||
|
||
// Other members not specified
|
||
};
|
||
|
||
template <class Pred>
|
||
struct is_predicate<if_not<Pred>>: std::true_type
|
||
{
|
||
};
|
||
|
||
template <class ErrorCodeEnum>
|
||
bool category( std::error_code const & ec ) noexcept;
|
||
|
||
template <class Enum, class EnumType = Enum>
|
||
struct condition;
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p>Reference: <a href="#match"><code>match</code></a> | <a href="#match_value"><code>match_value</code></a> | <a href="#match_member"><code>match_member</code></a> | <a href="#catch_"><code>catch_</code></a> | <a href="#if_not"><code>if_not</code></a> | <a href="#category"><code>category</code></a> | <a href="#condition"><code>condition</code></a></p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="functions">Reference: Functions</h2>
|
||
<div class="sectionbody">
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
The contents of each Reference section are organized alphabetically.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
<div class="sect2">
|
||
<h3 id="activate_context"><code>activate_context</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/error.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class Ctx>
|
||
context_activator<Ctx> activate_context( Ctx & ctx ) noexcept
|
||
{
|
||
return context_activator<Ctx>(ctx);
|
||
}
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#context_activator"><code>context_activator</code></a></p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="title">Example:</div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">leaf::context<E1, E2, E3> ctx;
|
||
|
||
{
|
||
auto active_context = activate_context(ctx); <i class="conum" data-value="1"></i><b>(1)</b>
|
||
} <i class="conum" data-value="2"></i><b>(2)</b></code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>Activate <code>ctx</code>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>Automatically deactivate <code>ctx</code>.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="capture"><code>capture</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/capture.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class F, class... A>
|
||
decltype(std::declval<F>()(std::forward<A>(std::declval<A>())...))
|
||
capture(std::shared_ptr<polymorphic_context> && ctx, F && f, A... a);
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#polymorphic_context"><code>polymorphic_context</code></a></p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>This function can be used to capture error objects stored in a <a href="#context"><code>context</code></a> in one thread and transport them to a different thread for handling, either in a <code><a href="#result">result</a><T></code> object or in an exception.</p>
|
||
</div>
|
||
<div class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Returns: </dt>
|
||
<dd>
|
||
<p>The same type returned by <code>F</code>.</p>
|
||
</dd>
|
||
<dt class="hdlist1">Effects: </dt>
|
||
<dd>
|
||
<p>Uses an internal <a href="#context_activator"><code>context_activator</code></a> to <a href="#context::activate"><code>activate</code></a> <code>*ctx</code>, then invokes <code>std::forward<F>(f)(std::forward<A>(a)…​)</code>. Then:</p>
|
||
<div class="openblock">
|
||
<div class="content">
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>If the returned value <code>r</code> is not a <code>result<T></code> type (see <a href="#is_result_type"><code>is_result_type</code></a>), it is forwarded to the caller.</p>
|
||
</li>
|
||
<li>
|
||
<p>Otherwise:</p>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>If <code>!r</code>, the return value of <code>capture</code> is initialized with <code>ctx</code>;</p>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
An object of type <code>leaf::<a href="#result">result</a><T></code> can be initialized with a <code>std::shared_ptr<leaf::polymorphic_context></code>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</li>
|
||
<li>
|
||
<p>otherwise, it is initialized with <code>r</code>.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>In case <code>f</code> throws, <code>capture</code> catches the exception in a <code>std::exception_ptr</code>, and throws a different exception of unspecified type that transports both the <code>std::exception_ptr</code> as well as <code>ctx</code>. This exception type is recognized by <a href="#try_catch"><code>try_catch</code></a>, which automatically unpacks the original exception and propagates the contents of <code>*ctx</code> (presumably, in a different thread).</p>
|
||
</div>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
See also <a href="#tutorial-async">Transporting Error Objects Between Threads</a> from the Tutorial.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="context_type_from_handlers"><code>context_type_from_handlers</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/context.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class... H>
|
||
using context_type_from_handlers = typename <<unspecified>>::type;
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="title">Example:</div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">auto error_handlers = std::make_tuple(
|
||
[](e_this const & a, e_that const & b)
|
||
{
|
||
....
|
||
},
|
||
|
||
[](leaf::diagnostic_info const & info)
|
||
{
|
||
....
|
||
},
|
||
.... );
|
||
|
||
leaf::context_type_from_handlers<decltype(error_handlers)> ctx; <i class="conum" data-value="1"></i><b>(1)</b></code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td><code>ctx</code> will be of type <code>context<e_this, e_that></code>, deduced automatically from the specified error handlers.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
Alternatively, a suitable context may be created by calling <a href="#make_context"><code>make_context</code></a>, or allocated dynamically by calling <a href="#make_shared_context"><code>make_shared_context</code></a>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="current_error"><code>current_error</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/error.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
error_id current_error() noexcept;
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Returns: </dt>
|
||
<dd>
|
||
<p>The <code>error_id</code> value returned the last time <a href="#new_error"><code>new_error</code></a> was invoked from the calling thread.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
See also <a href="#on_error"><code>on_error</code></a>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="exception"><code>exception</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/exception.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class Ex, class... E> <i class="conum" data-value="1"></i><b>(1)</b>
|
||
<<unspecified>> exception( Ex && ex, E && ... e ) noexcept;
|
||
|
||
template <class E1, class... E> <i class="conum" data-value="2"></i><b>(2)</b>
|
||
<<unspecified>> exception( E1 && e1, E && ... e ) noexcept;
|
||
|
||
<<unspecified>> exception() noexcept; <i class="conum" data-value="3"></i><b>(3)</b>
|
||
|
||
template <class Ex, class... E> <i class="conum" data-value="4"></i><b>(4)</b>
|
||
<<unspecified>> exception( error_id id, Ex && ex, E && ... e ) noexcept;
|
||
|
||
template <class E1, class... E> <i class="conum" data-value="5"></i><b>(5)</b>
|
||
<<unspecified>> exception( error_id id, E1 && e1, E && ... e ) noexcept;
|
||
|
||
<<unspecified>> exception( error_id id ) noexcept; <i class="conum" data-value="6"></i><b>(6)</b>
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The <code>exception</code> function is overloaded: it can be invoked with no arguments, or else there are several alternatives, selected using <code>std::enable_if</code> based on the type of the passed arguments:</p>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>Selected if the first argument is not of type <code>error_id</code> and is an exception object, that is, iff <code>Ex</code> derives publicly from <code>std::exception</code>. In this case the return value is of unspecified type which derives publicly from <code>Ex</code> <strong>and</strong> from class <a href="#error_id"><code>error_id</code></a>, such that:
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>its <code>Ex</code> subobject is initialized by <code>std::forward<Ex>(ex)</code>;</p>
|
||
</li>
|
||
<li>
|
||
<p>its <code>error_id</code> subobject is initialized by <code><a href="#new_error">new_error</a>(std::forward<E>(e)…​</code>).</p>
|
||
</li>
|
||
</ul>
|
||
</div></td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>Selected if the first argument is not of type <code>error_id</code> and is not an exception object. In this case the return value is of unspecified type which derives publicly from <code>std::exception</code> <strong>and</strong> from class <code>error_id</code>, such that:
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>its <code>std::exception</code> subobject is default-initialized;</p>
|
||
</li>
|
||
<li>
|
||
<p>its <code>error_id</code> subobject is initialized by <code><a href="#new_error">new_error</a>(std::forward<E1>(e1), std::forward<E>(e)…​</code>).</p>
|
||
</li>
|
||
</ul>
|
||
</div></td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="3"></i><b>3</b></td>
|
||
<td>If the fuction is invoked without arguments, the return value is of unspecified type which derives publicly from <code>std::exception</code> <strong>and</strong> from class <code>error_id</code>, such that:
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>its <code>std::exception</code> subobject is default-initialized;</p>
|
||
</li>
|
||
<li>
|
||
<p>its <code>error_id</code> subobject is initialized by <code><a href="#new_error">new_error</a>()</code>.</p>
|
||
</li>
|
||
</ul>
|
||
</div></td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="4"></i><b>4</b></td>
|
||
<td>Selected if the first argument is of type <code>error_id</code> and the second argument is an exception object, that is, iff <code>Ex</code> derives publicly from <code>std::exception</code>. In this case the return value is of unspecified type which derives publicly from <code>Ex</code> <strong>and</strong> from class <a href="#error_id"><code>error_id</code></a>, such that:
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>its <code>Ex</code> subobject is initialized by <code>std::forward<Ex>(ex)</code>;</p>
|
||
</li>
|
||
<li>
|
||
<p>its <code>error_id</code> subobject is initialized by <code>id.<a href="#error_id::load"><code>load</code></a>(std::forward<E>(e)…​)</code>.</p>
|
||
</li>
|
||
</ul>
|
||
</div></td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="5"></i><b>5</b></td>
|
||
<td>Selected if the first argument is of type <code>error_id</code> and the second argument is not an exception object. In this case the return value is of unspecified type which derives publicly from <code>std::exception</code> <strong>and</strong> from class <code>error_id</code>, such that:
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>its <code>std::exception</code> subobject is default-initialized;</p>
|
||
</li>
|
||
<li>
|
||
<p>its <code>error_id</code> subobject is initialized by <code>id.<a href="#error_id::load"><code>load</code></a>(std::forward<E1>(e1), std::forward<E>(e)…​</code>).</p>
|
||
</li>
|
||
</ul>
|
||
</div></td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="6"></i><b>6</b></td>
|
||
<td>If <code>exception</code> is invoked with just an <code>error_id</code> object, the return value is of unspecified type which derives publicly from <code>std::exception</code> <strong>and</strong> from class <code>error_id</code>, such that:
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>its <code>std::exception</code> subobject is default-initialized;</p>
|
||
</li>
|
||
<li>
|
||
<p>its <code>error_id</code> subobject is initialized by copying from <code>id</code>.</p>
|
||
</li>
|
||
</ul>
|
||
</div></td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
The first three overloads return an exception object that is associated with a new <code>error_id</code>. The second three overloads return an exception object that is associated with the specified <code>error_id</code>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="title">Example 1:</div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">struct my_exception: std::exception { };
|
||
|
||
throw leaf::exception(my_exception{}); <i class="conum" data-value="1"></i><b>(1)</b></code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>Throws an exception of a type that derives from <code>error_id</code> and from <code>my_exception</code> (because <code>my_exception</code> derives from <code>std::exception</code>).</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="title">Example 2:</div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">enum class my_error { e1=1, e2, e3 }; <i class="conum" data-value="1"></i><b>(1)</b>
|
||
|
||
throw leaf::exception(my_error::e1);</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>Throws an exception of a type that derives from <code>error_id</code> and from <code>std::exception</code> (because <code>my_error</code> does not derive from <code>std::exception</code>).</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
To automatically capture <code>__FILE__</code>, <code>__LINE__</code> and <code>__FUNCTION__</code> with the returned object, use <a href="#BOOST_LEAF_EXCEPTION"><code>EXCEPTION</code></a> instead of <code>leaf::exception</code>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="exception_to_result"><code>exception_to_result</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/capture.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class... Ex, class F>
|
||
<<result<T>-deduced>> exception_to_result( F && f ) noexcept;
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>This function can be used to catch exceptions from a lower-level library and convert them to <code><a href="#result">result</a><T></code>.</p>
|
||
</div>
|
||
<div class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Returns: </dt>
|
||
<dd>
|
||
<p>Where <code>f</code> returns a type <code>T</code>, <code>exception_to_result</code> returns <code>leaf::result<T></code>.</p>
|
||
</dd>
|
||
<dt class="hdlist1">Effects: </dt>
|
||
<dd>
|
||
<div class="olist arabic">
|
||
<ol class="arabic">
|
||
<li>
|
||
<p>Catches all exceptions, then captures <code>std::current_exception</code> in a <code>std::exception_ptr</code> object, which is <a href="#tutorial-loading">loaded</a> with the returned <code>result<T></code>.</p>
|
||
</li>
|
||
<li>
|
||
<p>Attempts to convert the caught exception, using <code>dynamic_cast</code>, to each type <code>Ex<sub>i</sub></code> in <code>Ex…​</code>. If the cast to <code>Ex<sub>i</sub></code> succeeds, the <code>Ex<sub>i</sub></code> slice of the caught exception is loaded with the returned <code>result<T></code>.</p>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
An error handler that takes an argument of an exception type (that is, of a type that derives from <code>std::exception</code>) will work correctly whether the object is thrown as an exception or communicated via <a href="#new_error"><code>new_error</code></a> (or converted using <code>exception_to_result</code>).
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="title">Example:</div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">int compute_answer_throws();
|
||
|
||
//Call compute_answer, convert exceptions to result<int>
|
||
leaf::result<int> compute_answer()
|
||
{
|
||
return leaf::exception_to_result<ex_type1, ex_type2>(compute_answer_throws());
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>At a later time we can invoke <a href="#try_handle_some"><code>try_handle_some</code></a> / <a href="#try_handle_all"><code>try_handle_all</code></a> as usual, passing handlers that take <code>ex_type1</code> or <code>ex_type2</code>, for example by reference:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">return leaf::try_handle_some(
|
||
|
||
[] -> leaf::result<void>
|
||
{
|
||
BOOST_LEAF_AUTO(answer, compute_answer());
|
||
//Use answer
|
||
....
|
||
return { };
|
||
},
|
||
|
||
[](ex_type1 & ex1)
|
||
{
|
||
//Handle ex_type1
|
||
....
|
||
return { };
|
||
},
|
||
|
||
[](ex_type2 & ex2)
|
||
{
|
||
//Handle ex_type2
|
||
....
|
||
return { };
|
||
},
|
||
|
||
[](std::exception_ptr const & p)
|
||
{
|
||
//Handle any other exception from compute_answer.
|
||
....
|
||
return { };
|
||
} );</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#try_handle_some"><code>try_handle_some</code></a> | <a href="#result"><code>result</code></a> | <a href="#BOOST_LEAF_AUTO"><code>AUTO</code></a></p>
|
||
</div>
|
||
<div class="admonitionblock warning">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-warning" title="Warning"></i>
|
||
</td>
|
||
<td class="content">
|
||
When a handler takes an argument of an exception type (that is, a type that derives from <code>std::exception</code>), if the object is thrown, the argument will be matched dynamically (using <code>dynamic_cast</code>); otherwise (e.g. after being converted by <code>exception_to_result</code>) it will be matched based on its static type only (which is the same behavior used for types that do not derive from <code>std::exception</code>).
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
See also <a href="#tutorial-exception_to_result">Converting Exceptions to <code>result<T></code></a> from the tutorial.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="make_context"><code>make_context</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/context.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class... H>
|
||
context_type_from_handlers<H...> make_context() noexcept
|
||
{
|
||
return { };
|
||
}
|
||
|
||
template <class... H>
|
||
context_type_from_handlers<H...> make_context( H && ... ) noexcept
|
||
{
|
||
return { };
|
||
}
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#context_type_from_handlers"><code>context_type_from_handlers</code></a></p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="title">Example:</div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">auto ctx = leaf::make_context( <i class="conum" data-value="1"></i><b>(1)</b>
|
||
[]( e_this ) { .... },
|
||
[]( e_that ) { .... } );</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td><code>decltype(ctx)</code> is <code>leaf::context<e_this, e_that></code>.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="make_shared_context"><code>make_shared_context</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/context.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class... H>
|
||
context_ptr make_shared_context() noexcept
|
||
{
|
||
return std::make_shared<leaf_detail::polymorphic_context_impl<context_type_from_handlers<H...>>>();
|
||
}
|
||
|
||
template <class... H>
|
||
context_ptr make_shared_context( H && ... ) noexcept
|
||
{
|
||
return std::make_shared<leaf_detail::polymorphic_context_impl<context_type_from_handlers<H...>>>();
|
||
}
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#context_type_from_handlers"><code>context_type_from_handlers</code></a></p>
|
||
</div>
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
See also <a href="#tutorial-async">Transporting Error Objects Between Threads</a> from the tutorial.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="new_error"><code>new_error</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/error.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class... Item>
|
||
error_id new_error(Item && ... item) noexcept;
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Requires: </dt>
|
||
<dd>
|
||
<p>Each of the <code>Item…​</code> types must be no-throw movable.</p>
|
||
</dd>
|
||
<dt class="hdlist1">Effects: </dt>
|
||
<dd>
|
||
<p>As if:</p>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">error_id id = <<generate-new-unique-id>>;
|
||
return id.load(std::forward<Item>(item)...);</code></pre>
|
||
</div>
|
||
</div>
|
||
</dd>
|
||
<dt class="hdlist1">Returns: </dt>
|
||
<dd>
|
||
<p>A new <code>error_id</code> value, which is unique across the entire program.</p>
|
||
</dd>
|
||
<dt class="hdlist1">Ensures: </dt>
|
||
<dd>
|
||
<p><code>id.value()!=0</code>, where <code>id</code> is the returned <code>error_id</code>.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
<code>new_error</code> discards error objects which are not used in any active error-handling calling scope.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="admonitionblock caution">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-caution" title="Caution"></i>
|
||
</td>
|
||
<td class="content">
|
||
When loaded into a <code>context</code>, an error object of a type <code>E</code> will overwrite the previously loaded object of type <code>E</code>, if any.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="on_error"><code>on_error</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/on_error.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class... Item>
|
||
<<unspecified-type>> on_error(Item && ... item) noexcept;
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Requires: </dt>
|
||
<dd>
|
||
<p>Each of the <code>Item…​</code> types must be no-throw movable.</p>
|
||
</dd>
|
||
<dt class="hdlist1">Effects: </dt>
|
||
<dd>
|
||
<p>All <code>item…​</code> objects are forwarded and stored, together with the value returned from <code>std::unhandled_exceptions</code>, into the returned object of unspecified type, which should be captured by <code>auto</code> and kept alive in the calling scope. When that object is destroyed, if an error has occurred since <code>on_error</code> was invoked, LEAF will process the stored items to obtain error objects to be associated with the failure.</p>
|
||
<div class="paragraph">
|
||
<p>On error, LEAF first needs to deduce an <code>error_id</code> value <code>err</code> to associate error objects with. This is done using the following logic:</p>
|
||
</div>
|
||
<div class="openblock">
|
||
<div class="content">
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>If <a href="#new_error"><code>new_error</code></a> was invoked (by the calling thread) since the object returned by <code>on_error</code> was created, <code>err</code> is initialized with the value returned by <a href="#current_error"><code>current_error</code></a>;</p>
|
||
</li>
|
||
<li>
|
||
<p>Otherwise, if <code>std::unhandled_exceptions</code> returns a greater value than it returned during initialization, <code>err</code> is initialized with the value returned by <a href="#new_error"><code>new_error</code></a>;</p>
|
||
</li>
|
||
<li>
|
||
<p>Otherwise, the stored <code>item…​</code> objects are discarded and no further action is taken (no error has occurred).</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Next, LEAF proceeds similarly to:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">err.load(std::forward<Item>(item)...);</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The difference is that unlike <a href="#error_id::load"><code>load</code></a>, <code>on_error</code> will not overwrite any error objects already associated with <code>err</code>.</p>
|
||
</div>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
See <a href="#tutorial-on_error">Using <code>on_error</code></a> from the Tutorial.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="try_catch"><code>try_catch</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/handle_errors.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class TryBlock, class... H>
|
||
typename std::decay<decltype(std::declval<TryBlock>()())>::type
|
||
try_catch( TryBlock && try_block, H && ... h );
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The <code>try_catch</code> function works similarly to <a href="#try_handle_some"><code>try_handle_some</code></a>, except that it does not use or understand the semantics of <code>result<T></code> types; instead:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>It assumes that the <code>try_block</code> throws to indicate a failure, in which case <code>try_catch</code> will attempt to find a suitable handler among <code>h…​</code>;</p>
|
||
</li>
|
||
<li>
|
||
<p>If a suitable handler isn’t found, the original exception is re-thrown using <code>throw;</code>.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
See also Five Minute Introduction <a href="#introduction-eh">Exception-Handling API</a>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="try_handle_all"><code>try_handle_all</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/handle_errors.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class TryBlock, class... H>
|
||
typename std::decay<decltype(std::declval<TryBlock>()().value())>::type
|
||
try_handle_all( TryBlock && try_block, H && ... h );
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The <code>try_handle_all</code> function works similarly to <a href="#try_handle_some"><code>try_handle_some</code></a>, except:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>In addition, it requires that at least one of <code>h…​</code> can be used to handle any error (this requirement is enforced at compile time);</p>
|
||
</li>
|
||
<li>
|
||
<p>If the <code>try_block</code> returns some <code>result<T></code> type, it must be possible to initialize a value of type <code>T</code> with the value returned by each of <code>h…​</code>, and</p>
|
||
</li>
|
||
<li>
|
||
<p>Because it is required to handle all errors, <code>try_handle_all</code> unwraps the <code>result<T></code> object <code>r</code> returned by the <code>try_block</code>, returning <code>r.value()</code> instead of <code>r</code>.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
See also <a href="#introduction-result">Five Minute Introduction</a>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="try_handle_some"><code>try_handle_some</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/handle_errors.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class TryBlock, class... H>
|
||
typename std::decay<decltype(std::declval<TryBlock>()())>::type
|
||
try_handle_some( TryBlock && try_block, H && ... h );
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Requires: </dt>
|
||
<dd>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>The <code>try_block</code> function may not take any arguments.</p>
|
||
</li>
|
||
<li>
|
||
<p>The type <code>R</code> returned by the <code>try_block</code> function must be a <code>result<T></code> type (see <a href="#is_result_type"><code>is_result_type</code></a>). It is valid for the <code>try_block</code> to return <code>leaf::<a href="#result">result</a><T></code>, however this is not a requirement.</p>
|
||
</li>
|
||
<li>
|
||
<p>Each of the <code>h…​</code> functions:</p>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>must return a type that can be used to initialize an object of the type <code>R</code>; in case R is a <code>result<void></code> (that is, in case of success it does not communicate a value), handlers that return <code>void</code> are permitted. If such a handler is selected, the <code>try_handle_some</code> return value is initialized by <code>{}</code>;</p>
|
||
</li>
|
||
<li>
|
||
<p>may take any error objects, by value, by (<code>const</code>) reference, or as pointer (to <code>const</code>);</p>
|
||
</li>
|
||
<li>
|
||
<p>may take arguments, by value, of any predicate type: <a href="#catch_"><code>catch_</code></a>, <a href="#match"><code>match</code></a>, <a href="#match_value"><code>match_value</code></a>, <a href="#match_member"><code>match_member</code></a>, <a href="#if_not"><code>if_not</code></a>, or of any user-defined predicate type <code>Pred</code> for which <code><a href="#is_predicate">is_predicate</a><Pred>::value</code> is <code>true</code>;</p>
|
||
</li>
|
||
<li>
|
||
<p>may take an <a href="#error_info"><code>error_info</code></a> argument by <code>const &</code>;</p>
|
||
</li>
|
||
<li>
|
||
<p>may take a <a href="#diagnostic_info"><code>diagnostic_info</code></a> argument by <code>const &</code>;</p>
|
||
</li>
|
||
<li>
|
||
<p>may take a <a href="#verbose_diagnostic_info"><code>verbose_diagnostic_info</code></a> argument by <code>const &</code>.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</dd>
|
||
<dt class="hdlist1">Effects: </dt>
|
||
<dd>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>Creates a local <code><a href="#context">context</a><E…​></code> object <code>ctx</code>, where the <code>E…​</code> types are automatically deduced from the types of arguments taken by each of <code>h…​</code>, which guarantees that <code>ctx</code> is able to store all of the types required to handle errors.</p>
|
||
</li>
|
||
<li>
|
||
<p>Invokes the <code>try_block</code>:</p>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>if the returned object <code>r</code> indicates success <span class="underline">and</span> the <code>try_block</code> did not throw, <code>r</code> is forwarded to the caller.</p>
|
||
</li>
|
||
<li>
|
||
<p>otherwise, LEAF considers each of the <code>h…​</code> handlers, in order, until it finds one that it can supply with arguments using the error objects currently stored in <code>ctx</code>, associated with <code>r.error()</code>. The first such handler is invoked and its return value is used to initialize the return value of <code>try_handle_some</code>, which can indicate success if the handler was able to handle the error, or failure if it was not.</p>
|
||
</li>
|
||
<li>
|
||
<p>if <code>try_handle_some</code> is unable to find a suitable handler, it returns <code>r</code>.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
<code>try_handle_some</code> is exception-neutral: it does not throw exceptions, however the <code>try_block</code> and any of <code>h…​</code> are permitted to throw.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div id="handler_selection_procedure" class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Handler Selection Procedure: </dt>
|
||
<dd>
|
||
<div class="paragraph">
|
||
<p>A handler <code>h</code> is suitable to handle the failure reported by <code>r</code> iff <code>try_handle_some</code> is able to produce values to pass as its arguments, using the error objects currently available in <code>ctx</code>, associated with the error ID obtained by calling <code>r.error()</code>. As soon as it is determined that an argument value can not be produced, the current handler is dropped and the selection process continues with the next handler, if any.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The return value of <code>r.error()</code> must be implicitly convertible to <a href="#error_id"><code>error_id</code></a>. Naturally, the <code>leaf::result</code> template satisfies this requirement. If an external <code>result</code> type is used instead, usually <code>r.error()</code> would return a <code>std::error_code</code>, which is able to communicate LEAF error IDs; see <a href="#tutorial-interoperability">Interoperability</a>.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>If <code>err</code> is the <code>error_id</code> obtained from <code>r.error()</code>, each argument <code>a<sub>i</sub></code> taken by the handler currently under consideration is produced as follows:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>If <code>a<sub>i</sub></code> is of type <code>A<sub>i</sub></code>, <code>A<sub>i</sub> const&</code> or <code>A<sub>i</sub>&</code>:</p>
|
||
<div class="openblock">
|
||
<div class="content">
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>If an error object of type <code>A<sub>i</sub></code>, associated with <code>err</code>, is currently available in <code>ctx</code>, <code>a<sub>i</sub></code> is initialized with a reference to that object; otherwise</p>
|
||
</li>
|
||
<li>
|
||
<p>If <code>A<sub>i</sub></code> derives from <code>std::exception</code>, and the <code>try_block</code> throws an object <code>ex</code> of type that derives from <code>std::exception</code>, LEAF obtains <code>A<sub>i</sub>* p = dynamic_cast<A<sub>i</sub>*>(&ex)</code>. The handler is dropped if <code>p</code> is null, otherwise <code>a<sub>i</sub></code> is initialized with <code>*p</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p>Otherwise the handler is dropped.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="title">Example:</div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">....
|
||
auto r = leaf::try_handle_some(
|
||
[]() -> leaf::result<int>
|
||
{
|
||
return f();
|
||
},
|
||
|
||
[](leaf::e_file_name const & fn) <i class="conum" data-value="1"></i><b>(1)</b>
|
||
{
|
||
std::cerr << "File Name: \"" << fn.value << '"' << std::endl; <i class="conum" data-value="2"></i><b>(2)</b>
|
||
|
||
return 1;
|
||
} );</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#result"><code>result</code></a> | <a href="#e_file_name"><code>e_file_name</code></a></p>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>In case the <code>try_block</code> indicates a failure, this handler will be selected if <code>ctx</code> stores an <code>e_file_name</code> associated with the error. Because this is the only supplied handler, if an <code>e_file_name</code> is not available, <code>try_handle_some</code> will return the <code>leaf::result<int></code> returned by <code>f</code>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>Print the file name, handle the error.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</li>
|
||
<li>
|
||
<p>If <code>a<sub>i</sub></code> is of type <code>A<sub>i</sub></code> <code>const*</code> or <code>A<sub>i</sub>*</code>, <code>try_handle_some</code> is always able to produce it: first it attempts to produce it as if it is taken by reference; if that fails, rather than dropping the handler, <code>a<sub>i</sub></code> is initialized with <code>0</code>.</p>
|
||
<div class="listingblock">
|
||
<div class="title">Example:</div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">....
|
||
try_handle_some(
|
||
[]() -> leaf::result<int>
|
||
{
|
||
return f();
|
||
},
|
||
|
||
[](leaf::e_file_name const * fn) <i class="conum" data-value="1"></i><b>(1)</b>
|
||
{
|
||
if( fn ) <i class="conum" data-value="2"></i><b>(2)</b>
|
||
std::cerr << "File Name: \"" << fn->value << '"' << std::endl;
|
||
|
||
return 1;
|
||
} );
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#result"><code>result</code></a> | <a href="#e_file_name"><code>e_file_name</code></a></p>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>This handler can be selected to handle any error, because it takes <code>e_file_name</code> as a <code>const *</code> (and nothing else).</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>If an <code>e_file_name</code> is available with the current error, print it.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</li>
|
||
<li>
|
||
<p>If <code>a<sub>i</sub></code> is of a predicate type <code>Pred</code> (for which <code><a href="#is_predicate">is_predicate</a><Pred>::value</code> is <code>true</code>), <code>E</code> is deduced as <code>typename Pred::error_type</code>, and then:</p>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>If <code>E</code> is not <code>void</code>, and an error object <code>e</code> of type <code>E</code>, associated with <code>err</code>, is not currently stored in <code>ctx</code>, the handler is dropped; otherwise the handler is dropped if the expression <code>Pred::evaluate(e)</code> returns <code>false</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p>if <code>E</code> is <code>void</code>, and a <code>std::exception</code> was not caught, the handler is dropped; otherwise the handler is dropped if the expression <code>Pred::evaluate(e)</code>, where <code>e</code> is of type <code>std::exception const &</code>, returns <code>false</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p>To invoke the handler, the <code>Pred</code> argument <code>a<sub>i</sub></code> is initialized with <code>Pred{e}</code>.</p>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
See also: <a href="#predicates">Predicates</a>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</li>
|
||
<li>
|
||
<p>If <code>a<sub>i</sub></code> is of type <code>error_info const &</code>, <code>try_handle_some</code> is always able to produce it.</p>
|
||
<div class="listingblock">
|
||
<div class="title">Example:</div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">....
|
||
try_handle_some(
|
||
[]
|
||
{
|
||
return f(); // returns leaf::result<T>
|
||
},
|
||
|
||
[](leaf::error_info const & info) <i class="conum" data-value="1"></i><b>(1)</b>
|
||
{
|
||
std::cerr << "leaf::error_info:" << std::endl << info; <i class="conum" data-value="2"></i><b>(2)</b>
|
||
return info.error(); <i class="conum" data-value="3"></i><b>(3)</b>
|
||
} );</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#result"><code>result</code></a> | <a href="#error_info"><code>error_info</code></a></p>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>This handler matches any error.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>Print error information.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="3"></i><b>3</b></td>
|
||
<td>Return the original error, which will be returned out of <code>try_handle_some</code>.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</li>
|
||
<li>
|
||
<p>If <code>a<sub>i</sub></code> is of type <code>diagnostic_info const &</code>, <code>try_handle_some</code> is always able to produce it.</p>
|
||
<div class="listingblock">
|
||
<div class="title">Example:</div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">....
|
||
try_handle_some(
|
||
[]
|
||
{
|
||
return f(); // throws
|
||
},
|
||
|
||
[](leaf::diagnostic_info const & info) <i class="conum" data-value="1"></i><b>(1)</b>
|
||
{
|
||
std::cerr << "leaf::diagnostic_information:" << std::endl << info; <i class="conum" data-value="2"></i><b>(2)</b>
|
||
return info.error(); <i class="conum" data-value="3"></i><b>(3)</b>
|
||
} );</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#result"><code>result</code></a> | <a href="#diagnostic_info"><code>diagnostic_info</code></a></p>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>This handler matches any error.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>Print diagnostic information, including limited information about dropped error objects.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="3"></i><b>3</b></td>
|
||
<td>Return the original error, which will be returned out of <code>try_handle_some</code>.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</li>
|
||
<li>
|
||
<p>If <code>a<sub>i</sub></code> is of type <code>verbose_diagnostic_info const &</code>, <code>try_handle_some</code> is always able to produce it.</p>
|
||
<div class="listingblock">
|
||
<div class="title">Example:</div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">....
|
||
try_handle_some(
|
||
[]
|
||
{
|
||
return f(); // throws
|
||
},
|
||
|
||
[](leaf::verbose_diagnostic_info const & info) <i class="conum" data-value="1"></i><b>(1)</b>
|
||
{
|
||
std::cerr << "leaf::verbose_diagnostic_information:" << std::endl << info; <i class="conum" data-value="2"></i><b>(2)</b>
|
||
return info.error(); <i class="conum" data-value="3"></i><b>(3)</b>
|
||
} );</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#result"><code>result</code></a> | <a href="#verbose_diagnostic_info"><code>verbose_diagnostic_info</code></a></p>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>This handler matches any error.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>Print verbose diagnostic information, including values of dropped error objects.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="3"></i><b>3</b></td>
|
||
<td>Return the original error, which will be returned out of <code>try_handle_some</code>.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="types">Reference: Types</h2>
|
||
<div class="sectionbody">
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
The contents of each Reference section are organized alphabetically.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
<div class="sect2">
|
||
<h3 id="context"><code>context</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/context.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class... E>
|
||
class context
|
||
{
|
||
context( context const & ) = delete;
|
||
context & operator=( context const & ) = delete;
|
||
|
||
public:
|
||
|
||
context() noexcept;
|
||
context( context && x ) noexcept;
|
||
~context() noexcept;
|
||
|
||
void activate() noexcept;
|
||
void deactivate() noexcept;
|
||
bool is_active() const noexcept;
|
||
|
||
void propagate() noexcept;
|
||
|
||
void print( std::ostream & os ) const;
|
||
|
||
template <class R, class... H>
|
||
R handle_error( error_id, H && ... ) const;
|
||
|
||
};
|
||
|
||
template <class... H>
|
||
using context_type_from_handlers = typename <<unspecified>>::type;
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#context::context">Constructors</a> | <a href="#context::activate"><code>activate</code></a> | <a href="#context::deactivate"><code>deactivate</code></a> | <a href="#context::is_active"><code>is_active</code></a> | <a href="#context::propagate"><code>propagate</code></a> | <a href="#context::print"><code>print</code></a> | <a href="#context::handle_error"><code>handle_error</code></a> | <a href="#context_type_from_handlers"><code>context_type_from_handlers</code></a></p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The <code>context</code> class template provides storage for each of the specified <code>E…​</code> types. Typically, <code>context</code> objects are not used directly; they’re created internally when the <a href="#try_handle_some"><code>try_handle_some</code></a>, <a href="#try_handle_all"><code>try_handle_all</code></a> or <a href="#try_catch"><code>try_catch</code></a> functions are invoked, instantiated with types that are automatically deduced from the types of the arguments of the passed handlers.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Independently, users can create <code>context</code> objects if they need to capture error objects and then transport them, by moving the <code>context</code> object itself.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Even in that case it is recommended that users do not instantiate the <code>context</code> template by explicitly listing the <code>E…​</code> types they want it to be able to store. Instead, use <a href="#context_type_from_handlers"><code>context_type_from_handlers</code></a> or call the <a href="#make_context"><code>make_context</code></a> function template, which deduce the correct <code>E…​</code> types from a captured list of handler function objects.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>To be able to load up error objects in a <code>context</code> object, it must be activated. Activating a <code>context</code> object <code>ctx</code> binds it to the calling thread, setting thread-local pointers of the stored <code>E…​</code> types to point to the corresponding storage within <code>ctx</code>. It is possible, even likely, to have more than one active <code>context</code> in any given thread. In this case, activation/deactivation must happen in a LIFO manner. For this reason, it is best to use a <a href="#context_activator"><code>context_activator</code></a>, which relies on RAII to activate and deactivate a <code>context</code>.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>When a <code>context</code> is deactivated, it detaches from the calling thread, restoring the thread-local pointers to their pre-<code>activate</code> values. Typically, at this point the stored error objects, if any, are either discarded (by default) or moved to corresponding storage in other <code>context</code> objects active in the calling thread (if available), by calling <a href="#context::propagate"><code>propagate</code></a>.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>While error handling typically uses <a href="#try_handle_some"><code>try_handle_some</code></a>, <a href="#try_handle_all"><code>try_handle_all</code></a> or <a href="#try_catch"><code>try_catch</code></a>, it is also possible to handle errors by calling the member function <a href="#context::handle_error"><code>handle_error</code></a>. It takes an <a href="#error_id"><code>error_id</code></a>, and attempts to select an error handler based on the error objects stored in <code>*this</code>, associated with the passed <code>error_id</code>.</p>
|
||
</div>
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
<code>context</code> objects can be moved, as long as they aren’t active.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="admonitionblock warning">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-warning" title="Warning"></i>
|
||
</td>
|
||
<td class="content">
|
||
Moving an active <code>context</code> results in undefined behavior.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
<div class="sect3">
|
||
<h4 id="context::context">Constructors</h4>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/context.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class... E>
|
||
context<E...>::context() noexcept;
|
||
|
||
template <class... E>
|
||
context<E...>::context( context && x ) noexcept;
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The default constructor initializes an empty <code>context</code> object: it provides storage for, but does not contain any error objects.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The move constructor moves the stored error objects from one <code>context</code> to the other.</p>
|
||
</div>
|
||
<div class="admonitionblock warning">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-warning" title="Warning"></i>
|
||
</td>
|
||
<td class="content">
|
||
Moving an active <code>context</code> object results in undefined behavior.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="context::activate"><code>activate</code></h4>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/context.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class... E>
|
||
void context<E...>::activate() noexcept;
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Requires: </dt>
|
||
<dd>
|
||
<p><code>!<a href="#context::is_active">is_active</a>()</code>.</p>
|
||
</dd>
|
||
<dt class="hdlist1">Effects: </dt>
|
||
<dd>
|
||
<p>Associates <code>*this</code> with the calling thread.</p>
|
||
</dd>
|
||
<dt class="hdlist1">Ensures: </dt>
|
||
<dd>
|
||
<p><code><a href="#context::is_active">is_active</a>()</code>.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>When a context is associated with a thread, thread-local pointers are set to point each <code>E…​</code> type in its store, while the previous value of each such pointer is preserved in the <code>context</code> object, so that the effect of <code>activate</code> can be undone by calling <code>deactivate</code>.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>When an error object is <a href="#tutorial-loading">loaded</a>, it is moved in the last activated (in the calling thread) <code>context</code> object that provides storage for its type (note that this may or may not be the last activated <code>context</code> object). If no such storage is available, the error object is discarded.</p>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="context::deactivate"><code>deactivate</code></h4>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/context.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class... E>
|
||
void context<E...>::deactivate() noexcept;
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Requires: </dt>
|
||
<dd>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p><code><a href="#context::is_active">is_active</a>()</code>;</p>
|
||
</li>
|
||
<li>
|
||
<p><code>*this</code> must be the last activated <code>context</code> object in the calling thread.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</dd>
|
||
<dt class="hdlist1">Effects: </dt>
|
||
<dd>
|
||
<p>Un-associates <code>*this</code> with the calling thread.</p>
|
||
</dd>
|
||
<dt class="hdlist1">Ensures: </dt>
|
||
<dd>
|
||
<p><code>!<a href="#context::is_active">is_active</a>()</code>.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>When a context is deactivated, the thread-local pointers that currently point to each individual error object storage in it are restored to their original value prior to calling <a href="#context::activate"><code>activate</code></a>.</p>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="context::handle_error"><code>handle_error</code></h4>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/handle_errors.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class... E>
|
||
template <class R, class... H>
|
||
R context<E...>::handle_error( error_id err, H && ... h ) const;
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>This function works similarly to <a href="#try_handle_all"><code>try_handle_all</code></a>, but rather than calling a <code>try_block</code> and obtaining the <a href="#error_id"><code>error_id</code></a> from a returned <code>result</code> type, it matches error objects (stored in <code>*this</code>, associated with <code>err</code>) with a suitable error handler from the <code>h…​</code> pack.</p>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
The caller is required to specify the return type <code>R</code>. This is because in general the supplied handlers may return different types (which must all be convertible to <code>R</code>).
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="context::is_active"><code>is_active</code></h4>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/context.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class... E>
|
||
bool context<E...>::is_active() const noexcept;
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Returns: </dt>
|
||
<dd>
|
||
<p><code>true</code> if the <code>*this</code> is active in any thread, <code>false</code> otherwise.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="context::print"><code>print</code></h4>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/context.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class... E>
|
||
void context<E...>::print( std::ostream & os ) const;
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Effects: </dt>
|
||
<dd>
|
||
<p>Prints all error objects currently stored in <code>*this</code>, together with the unique error ID each individual error object is associated with.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="context::propagate"><code>propagate</code></h4>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/context.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class... E>
|
||
void context<E...>::propagate() noexcept;
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Requires: </dt>
|
||
<dd>
|
||
<p><code>!<a href="#context::is_active">is_active</a>()</code>.</p>
|
||
</dd>
|
||
<dt class="hdlist1">Effects: </dt>
|
||
<dd>
|
||
<p>Each stored error object of some type <code>E</code> is moved into another <code>context</code> object active in the call stack that provides storage for objects of type <code>E</code>, if any, or discarded.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="context_activator"><code>context_activator</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/error.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class Ctx>
|
||
class context_activator
|
||
{
|
||
context_activator( context_activator const & ) = delete;
|
||
context_activator & operator=( context_activator const & ) = delete;
|
||
|
||
public:
|
||
|
||
explicit context_activator( Ctx & ctx ) noexcept;
|
||
context_activator( context_activator && ) noexcept;
|
||
~context_activator() noexcept;
|
||
};
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p><code>context_activator</code> is a simple class that activates and deactivates a <a href="#context"><code>context</code></a> using RAII:</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>If <code><a href="#context::is_active">ctx.is_active</a></code>() is <code>true</code> at the time the <code>context_activator</code> is initialized, the constructor and the destructor have no effects. Otherwise:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>The constructor stores a reference to <code>ctx</code> in <code>*this</code> and calls <code><a href="#context::activate">ctx.activate</a></code>().</p>
|
||
</li>
|
||
<li>
|
||
<p>The destructor:</p>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>Has no effects if <code>ctx.is_active()</code> is <code>false</code> (that is, it is valid to call <a href="#context::deactivate"><code>deactivate</code></a> manually, before the <code>context_activator</code> object expires);</p>
|
||
</li>
|
||
<li>
|
||
<p>Otherwise, calls <code><a href="#context::deactivate">ctx.deactivate</a></code>() and, if there are new uncaught exceptions since the constructor was called, the destructor calls <code><a href="#context::propagate">ctx.propagate</a></code>().</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>For automatic deduction of <code>Ctx</code>, use <a href="#activate_context"><code>activate_context</code></a>.</p>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="diagnostic_info"><code>diagnostic_info</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/handle_errors.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
class diagnostic_info: public error_info
|
||
{
|
||
//Constructors unspecified
|
||
|
||
friend std::ostream & operator<<( std::ostream & os, diagnostic_info const & x );
|
||
};
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Handlers passed to <a href="#try_handle_some"><code>try_handle_some</code></a>, <a href="#try_handle_all"><code>try_handle_all</code></a> or <a href="#try_catch"><code>try_catch</code></a> may take an argument of type <code>diagnostic_info const &</code> if they need to print diagnostic information about the error.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The message printed by <code>operator<<</code> includes the message printed by <code>error_info</code>, followed by basic information about error objects that were communicated to LEAF (to be associated with the error) for which there was no storage available in any active <a href="#context"><code>context</code></a> (these error objects were discarded by LEAF, because no handler needed them).</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The additional information is limited to the type name of the first such error object, as well as their total count.</p>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
<div class="paragraph">
|
||
<p>The behavior of <code>diagnostic_info</code> (and <a href="#verbose_diagnostic_info"><code>verbose_diagnostic_info</code></a>) is affected by the value of the macro <code>BOOST_LEAF_DIAGNOSTICS</code>:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>If it is 1 (the default), LEAF produces <code>diagnostic_info</code> but only if an active error handling context on the call stack takes an argument of type <code>diagnostic_info</code>;</p>
|
||
</li>
|
||
<li>
|
||
<p>If it is 0, the <code>diagnostic_info</code> functionality is stubbed out even for error handling contexts that take an argument of type <code>diagnostic_info</code>. This could shave a few cycles off the error path in some programs (but it is probably not worth it).</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="error_id"><code>error_id</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/error.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
class error_id
|
||
{
|
||
public:
|
||
|
||
error_id() noexcept;
|
||
|
||
template <class Enum>
|
||
result( Enum e, typename std::enable_if<std::is_error_code_enum<Enum>::value, Enum>::type * = 0 ) noexcept;
|
||
|
||
error_id( std::error_code const & ec ) noexcept;
|
||
|
||
int value() const noexcept;
|
||
explicit operator bool() const noexcept;
|
||
|
||
std::error_code to_error_code() const noexcept;
|
||
|
||
friend bool operator==( error_id a, error_id b ) noexcept;
|
||
friend bool operator!=( error_id a, error_id b ) noexcept;
|
||
friend bool operator<( error_id a, error_id b ) noexcept;
|
||
|
||
template <class... Item>
|
||
error_id load( Item && ... item ) const noexcept;
|
||
|
||
friend std::ostream & operator<<( std::ostream & os, error_id x );
|
||
};
|
||
|
||
bool is_error_id( std::error_code const & ec ) noexcept;
|
||
|
||
template <class... E>
|
||
error_id new_error( E && ... e ) noexcept;
|
||
|
||
error_id current_error() noexcept;
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#error_id::error_id">Constructors</a> | <a href="#error_id::value"><code>value</code></a> | <a href="#error_id::operator_bool"><code>operator bool</code></a> | <a href="#error_id::to_error_code"><code>to_error_code</code></a> | <a href="#error_id::comparison_operators"><code>operator==</code>, <code>!=</code>, <code><</code></a> | <a href="#error_id::load"><code>load</code></a> | <a href="#is_error_id"><code>is_error_id</code></a> | <a href="#new_error"><code>new_error</code></a> | <a href="#current_error"><code>current_error</code></a></p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Values of type <code>error_id</code> identify a specific occurrence of a failure across the entire program. They can be copied, moved, assigned to, and compared to other <code>error_id</code> objects. They’re as efficient as an <code>int</code>.</p>
|
||
</div>
|
||
<hr>
|
||
<div class="sect3">
|
||
<h4 id="error_id::error_id">Constructors</h4>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/error.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
error_id::error_id() noexcept = default;
|
||
|
||
template <class Enum>
|
||
error_id::error_id( Enum e, typename std::enable_if<std::is_error_code_enum<Enum>::value, Enum>::type * = 0 ) noexcept;
|
||
|
||
error_id::error_id( std::error_code const & ec ) noexcept;
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>A default-initialized <code>error_id</code> object does not represent a specific failure. It compares equal to any other default-initialized <code>error_id</code> object. All other <code>error_id</code> objects identify a specific occurrence of a failure.</p>
|
||
</div>
|
||
<div class="admonitionblock caution">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-caution" title="Caution"></i>
|
||
</td>
|
||
<td class="content">
|
||
When using an object of type <code>error_id</code> to initialize a <code>result<T></code> object, it will be initialized in error state, even when passing a default-initialized <code>error_id</code> value.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Converting an <code>error_id</code> object to <code>std::error_code</code> uses an unspecified <code>std::error_category</code> which LEAF recognizes. This allows an <code>error_id</code> to be transported through interfaces that work with <code>std::error_code</code>. The <code>std::error_code</code> constructor allows the original <code>error_id</code> to be restored.</p>
|
||
</div>
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
To check if a given <code>std::error_code</code> is actually carrying an <code>error_id</code>, use <a href="#is_error_id"><code>is_error_id</code></a>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Typically, users create new <code>error_id</code> objects by invoking <a href="#new_error"><code>new_error</code></a>. The constructor that takes <code>std::error_code</code>, and the one that takes a type <code>Enum</code> for which <code>std::is_error_code_enum<Enum>::value</code> is <code>true</code>, have the following effects:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>If <code>ec.value()</code> is <code>0</code>, the effect is the same as using the default constructor.</p>
|
||
</li>
|
||
<li>
|
||
<p>Otherwise, if <code><a href="#is_error_id">is_error_id</a>(ec)</code> is <code>true</code>, the original <code>error_id</code> value is used to initialize <code>*this</code>;</p>
|
||
</li>
|
||
<li>
|
||
<p>Otherwise, <code>*this</code> is initialized by the value returned by <a href="#new_error"><code>new_error</code></a>, while <code>ec</code> is passed to <code>load</code>, which enables handlers used with <code>try_handle_some</code>, <code>try_handle_all</code> or <code>try_catch</code> to receive it as an argument of type <code>std::error_code</code>.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="is_error_id"><code>is_error_id</code></h4>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/error.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
bool is_error_id( std::error_code const & ec ) noexcept;
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Returns: </dt>
|
||
<dd>
|
||
<p><code>true</code> if <code>ec</code> uses the LEAF-specific <code>std::error_category</code> that identifies it as carrying an error ID rather than another error code; otherwise returns <code>false</code>.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="error_id::load"><code>load</code></h4>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/error.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class... Item>
|
||
error_id error_id::load( Item && ... item ) const noexcept;
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Requires: </dt>
|
||
<dd>
|
||
<p>Each of the <code>Item…​</code> types must be no-throw movable.</p>
|
||
</dd>
|
||
<dt class="hdlist1">Effects: </dt>
|
||
<dd>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>If <code>value()==0</code>, all of <code>item…​</code> are discarded and no further action is taken.</p>
|
||
</li>
|
||
<li>
|
||
<p>Otherwise, what happens with each <code>item</code> depends on its type:</p>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>If it is a function that takes a single argument of some type <code>E &</code>, that function is called with the object of type <code>E</code> currently associated with <code>*this</code>. If no such object exists, a default-initialized object is associated with <code>*this</code> and then passed to the function.</p>
|
||
</li>
|
||
<li>
|
||
<p>If it is a function that takes no arguments, than function is called to obtain an error object, which is associated with <code>*this</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p>Otherwise, the <code>item</code> itself is assumed to be an error object, which is associated with <code>*this</code>.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</dd>
|
||
<dt class="hdlist1">Returns: </dt>
|
||
<dd>
|
||
<p><code>*this</code>.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
<code>load</code> discards error objects which are not used in any active error-handling calling scope.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="admonitionblock caution">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-caution" title="Caution"></i>
|
||
</td>
|
||
<td class="content">
|
||
When loaded into a <code>context</code>, an error object of a type <code>E</code> will overwrite the previously loaded object of type <code>E</code>, if any.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">See also: </dt>
|
||
<dd>
|
||
<p><a href="#tutorial-loading">Loading of Error Objects</a>.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="error_id::comparison_operators"><code>operator==</code>, <code>!=</code>, <code><</code></h4>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/error.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
friend bool operator==( error_id a, error_id b ) noexcept;
|
||
friend bool operator!=( error_id a, error_id b ) noexcept;
|
||
friend bool operator<( error_id a, error_id b ) noexcept;
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>These functions have the usual semantics, comparing <code>a.value()</code> and <code>b.value()</code>.</p>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
The exact strict weak ordering implemented by <code>operator<</code> is not specified. In particular, if for two <code>error_id</code> objects <code>a</code> and <code>b</code>, <code>a < b</code> is true, it does not follow that the failure identified by <code>a</code> ocurred earlier than the one identified by <code>b</code>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="error_id::operator_bool"><code>operator bool</code></h4>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/error.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
explicit error_id::operator bool() const noexcept;
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Effects: </dt>
|
||
<dd>
|
||
<p>As if <code>return value()!=0</code>.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="error_id::to_error_code"><code>to_error_code</code></h4>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/error.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
std::error_code error_id::to_error_code() const noexcept;
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Effects: </dt>
|
||
<dd>
|
||
<p>Returns a <code>std::error_code</code> with the same <code>value()</code> as <code>*this</code>, using an unspecified <code>std::error_category</code>.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
The returned object can be used to initialize an <code>error_id</code>, in which case the original <code>error_id</code> value will be restored.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
Use <a href="#is_error_id"><code>is_error_id</code></a> to check if a given <code>std::error_code</code> carries an <code>error_id</code>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="error_id::value"><code>value</code></h4>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/error.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
int error_id::value() const noexcept;
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Effects: </dt>
|
||
<dd>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>If <code>*this</code> was initialized using the default constructor, returns 0.</p>
|
||
</li>
|
||
<li>
|
||
<p>Otherwise returns an <code>int</code> that is guaranteed to not be 0: a program-wide unique identifier of the failure.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="error_monitor"><code>error_monitor</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/on_error.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
class error_monitor
|
||
{
|
||
public:
|
||
|
||
error_monitor() noexcept;
|
||
|
||
error_id check() const noexcept;
|
||
|
||
error_id assigned_error_id( E && ... e ) const noexcept;
|
||
};
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>This class helps obtain an <a href="#error_id"><code>error_id</code></a> to associate error objects with, when augmenting failures communicated using LEAF through uncooperative APIs that do not use LEAF to report errors (and therefore do not return an <code>error_id</code> on error).</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The common usage of this class is as follows:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">error_code compute_value( int * out_value ) noexcept; <i class="conum" data-value="1"></i><b>(1)</b>
|
||
|
||
leaf::error<int> augmenter() noexcept
|
||
{
|
||
leaf::error_monitor cur_err; <i class="conum" data-value="2"></i><b>(2)</b>
|
||
|
||
int val;
|
||
auto ec = compute_value(&val);
|
||
|
||
if( failure(ec) )
|
||
return cur_err.assigned_error_id().load(e1, e2, ...); <i class="conum" data-value="3"></i><b>(3)</b>
|
||
else
|
||
return val; <i class="conum" data-value="4"></i><b>(4)</b>
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>Uncooperative third-party API that does not use LEAF, but may result in calling a user callback that does use LEAF. In case our callback reports a failure, we’ll augment it with error objects available in the calling scope, even though <code>compute_value</code> can not communicate an <a href="#error_id"><code>error_id</code></a>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>Initialize an <code>error_monitor</code> object.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="3"></i><b>3</b></td>
|
||
<td>The call to <code>compute_value</code> has failed:
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>If <a href="#new_error"><code>new_error</code></a> was invoked (by the calling thread) after the <code>augment</code> object was initialized, <code>assigned_error_id</code> returns the last <code>error_id</code> returned by <code>new_error</code>. This would be the case if the failure originates in our callback (invoked internally by <code>compute_value</code>).</p>
|
||
</li>
|
||
<li>
|
||
<p>Else, <code>assigned_error_id</code> invokes <code>new_error</code> and returns that <code>error_id</code>.</p>
|
||
</li>
|
||
</ul>
|
||
</div></td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="4"></i><b>4</b></td>
|
||
<td>The call was successful, return the computed value.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The <code>check</code> function works similarly, but instead of invoking <code>new_error</code> it returns a defaul-initialized <code>error_id</code>.</p>
|
||
</div>
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
See <a href="#tutorial-on_error_in_c_callbacks">Using <code>error_monitor</code> to Report Arbitrary Errors from C-callbacks</a>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="e_api_function"><code>e_api_function</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/common.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
struct e_api_function {char const * value;};
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The <code>e_api_function</code> type is designed to capture the name of the API function that failed. For example, if you’re reporting an error from <code>fread</code>, you could use <code>leaf::e_api_function {"fread"}</code>.</p>
|
||
</div>
|
||
<div class="admonitionblock warning">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-warning" title="Warning"></i>
|
||
</td>
|
||
<td class="content">
|
||
The passed value is stored as a C string (<code>char const *</code>), so <code>value</code> should only be initialized with a string literal.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="e_at_line"><code>e_at_line</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/common.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
struct e_at_line { int value; };
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p><code>e_at_line</code> can be used to communicate the line number when reporting errors (for example parse errors) about a text file.</p>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="e_errno"><code>e_errno</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/common.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
struct e_errno
|
||
{
|
||
int value;
|
||
friend std::ostream & operator<<( std::ostream & os, e_errno const & err );
|
||
};
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>To capture <code>errno</code>, use <code>e_errno</code>. When printed in automatically-generated diagnostic messages, <code>e_errno</code> objects use <code>strerror</code> to convert the <code>errno</code> code to string.</p>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="e_file_name"><code>e_file_name</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/common.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
struct e_file_name { std::string value; };
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>When a file operation fails, you could use <code>e_file_name</code> to store the name of the file.</p>
|
||
</div>
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
It is probably better to define your own file name wrappers to avoid clashes if different modules all use <code>leaf::e_file_name</code>. It is best to use a descriptive name that clarifies what kind of file name it is (e.g. <code>e_source_file_name</code>, <code>e_destination_file_name</code>), or at least define <code>e_file_name</code> in a given module’s namespace.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="e_LastError"><code>e_LastError</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/common.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
namespace windows
|
||
{
|
||
struct e_LastError
|
||
{
|
||
unsigned value;
|
||
friend std::ostream & operator<<( std::ostream & os, e_LastError const & err );
|
||
};
|
||
}
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p><code>e_LastError</code> is designed to communicate <code>GetLastError()</code> values on Windows.</p>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="e_source_location"><code>e_source_location</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/error.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
struct e_source_location
|
||
{
|
||
char const * const file;
|
||
int const line;
|
||
char const * const function;
|
||
|
||
friend std::ostream & operator<<( std::ostream & os, e_source_location const & x );
|
||
};
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The <a href="#BOOST_LEAF_NEW_ERROR"><code>NEW_ERROR</code></a>, <a href="#BOOST_LEAF_EXCEPTION"><code>EXCEPTION</code></a> and <a href="#BOOST_LEAF_THROW_EXCEPTION"><code>THROW_EXCEPTION</code></a> macros capture <code>__FILE__</code>, <code>__LINE__</code> and <code>__FUNCTION__</code> into a <code>e_source_location</code> object.</p>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="e_type_info_name"><code>e_type_info_name</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/common.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
struct e_type_info_name { char const * value; };
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p><code>e_type_info_name</code> is designed to store the return value of <code>std::type_info::name</code>.</p>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="error_info"><code>error_info</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/handle_errors.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
class error_info
|
||
{
|
||
//Constructors unspecified
|
||
|
||
public:
|
||
|
||
error_id error() const noexcept;
|
||
|
||
bool exception_caught() const noexcept;
|
||
std::exception const * exception() const noexcept;
|
||
|
||
friend std::ostream & operator<<( std::ostream & os, error_info const & x );
|
||
};
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Handlers passed to error-handling functions such as <a href="#try_handle_some"><code>try_handle_some</code></a>, <a href="#try_handle_all"><code>try_handle_all</code></a> or <a href="#try_catch"><code>try_catch</code></a> may take an argument of type <code>error_info const &</code> to receive generic information about the error being handled.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The <code>error</code> member function returns the program-wide unique <a href="#error_id"><code>error_id</code></a> of the error.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The <code>exception_caught</code> member function returns <code>true</code> if the handler that received <code>*this</code> is being invoked to handle an exception, <code>false</code> otherwise.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>If handling an exception, the <code>exception</code> member function returns a pointer to the <code>std::exception</code> subobject of the caught exception, or <code>0</code> if that exception could not be converted to <code>std::exception</code>.</p>
|
||
</div>
|
||
<div class="admonitionblock warning">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-warning" title="Warning"></i>
|
||
</td>
|
||
<td class="content">
|
||
It is illegal to call the <code>exception</code> member function unless <code>exception_caught()</code> is <code>true</code>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The <code>operator<<</code> overload prints diagnostic information about each error object currently stored in the <a href="#context"><code>context</code></a> local to the <a href="#try_handle_some"><code>try_handle_some</code></a>, <a href="#try_handle_all"><code>try_handle_all</code></a> or <a href="#try_catch"><code>try_catch</code></a> scope that invoked the handler, but only if it is associated with the <a href="#error_id"><code>error_id</code></a> returned by <code>error()</code>.</p>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="polymorphic_context"><code>polymorphic_context</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/error.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
class polymorphic_context
|
||
{
|
||
protected:
|
||
|
||
polymorphic_context() noexcept;
|
||
~polymorphic_context() noexcept;
|
||
|
||
public:
|
||
|
||
virtual void activate() noexcept = 0;
|
||
virtual void deactivate() noexcept = 0;
|
||
virtual bool is_active() const noexcept = 0;
|
||
|
||
virtual void propagate() noexcept = 0;
|
||
|
||
virtual void print( std::ostream & ) const = 0;
|
||
};
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The <code>polymorphic_context</code> class is an abstract base type which can be used to erase the type of the exact instantiation of the <a href="#context"><code>context</code></a> class template used. See <a href="#make_shared_context"><code>make_shared_context</code></a>.</p>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="result"><code>result</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/result.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class T>
|
||
class result
|
||
{
|
||
public:
|
||
|
||
result() noexcept;
|
||
result( T && v ) noexcept;
|
||
result( T const & v );
|
||
|
||
template <class U>
|
||
result( U &&, <<enabled_if_T_can_be_inited_with_U>> );
|
||
|
||
result( error_id err ) noexcept;
|
||
result( std::shared_ptr<polymorphic_context> && ctx ) noexcept;
|
||
|
||
template <class Enum>
|
||
result( Enum e, typename std::enable_if<std::is_error_code_enum<Enum>::value, Enum>::type * = 0 ) noexcept;
|
||
|
||
result( std::error_code const & ec ) noexcept;
|
||
|
||
result( result && r ) noexcept;
|
||
|
||
template <class U>
|
||
result( result<U> && r ) noexcept;
|
||
|
||
result & operator=( result && r ) noexcept;
|
||
|
||
template <class U>
|
||
result & operator=( result<U> && r ) noexcept;
|
||
|
||
explicit operator bool() const noexcept;
|
||
|
||
T const & value() const;
|
||
T & value();
|
||
|
||
T const & operator*() const;
|
||
T & operator*();
|
||
|
||
T const * operator->() const;
|
||
T * operator->();
|
||
|
||
<<unspecified-type>> error() noexcept;
|
||
|
||
template <class... Item>
|
||
error_id load( Item && ... item ) noexcept;
|
||
};
|
||
|
||
template <>
|
||
class result<void>
|
||
{
|
||
public:
|
||
|
||
result() noexcept;
|
||
|
||
result( error_id err ) noexcept;
|
||
result( std::shared_ptr<polymorphic_context> && ctx ) noexcept;
|
||
|
||
template <class Enum>
|
||
result( Enum e, typename std::enable_if<std::is_error_code_enum<Enum>::value, Enum>::type * = 0 ) noexcept;
|
||
|
||
result( std::error_code const & ec ) noexcept;
|
||
|
||
result( result && r ) noexcept;
|
||
|
||
template <class U>
|
||
result( result<U> && r ) noexcept;
|
||
|
||
result & operator=( result && r ) noexcept;
|
||
|
||
template <class U>
|
||
result & operator=( result<U> && r ) noexcept;
|
||
|
||
explicit operator bool() const noexcept;
|
||
|
||
void value() const;
|
||
|
||
<<unspecified-type>> error() noexcept;
|
||
|
||
template <class... Item>
|
||
error_id load( Item && ... item ) noexcept;
|
||
};
|
||
|
||
struct bad_result: std::exception { };
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#result::result">Constructors</a> | <a href="#result::operator_eq"><code>operator=</code></a> | <a href="#result::operator_bool"><code>operator bool</code></a> | <a href="#result::value"><code>value</code>, <code>operator*</code>, <code>-></code></a> | <a href="#result::error"><code>error</code></a> | <a href="#result::load"><code>load</code></a></p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The <code>result<T></code> type can be returned by functions which produce a value of type <code>T</code> but may fail doing so.</p>
|
||
</div>
|
||
<div class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Requires: </dt>
|
||
<dd>
|
||
<p><code>T</code> must be movable, and its move constructor may not throw.</p>
|
||
</dd>
|
||
<dt class="hdlist1">Invariant: </dt>
|
||
<dd>
|
||
<p>A <code>result<T></code> object is in one of three states:</p>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>Value state, in which case it contains an object of type <code>T</code>, and <code><a href="#result::value">value</a></code>/<code><a href="#result::value">operator*</a></code>/<code><a href="#result::value">operator-></a></code> can be used to access the contained value.</p>
|
||
</li>
|
||
<li>
|
||
<p>Error state, in which case it contains an error ID, and calling <code><a href="#result::value">value</a></code>/<code><a href="#result::value">operator*</a></code>/<code><a href="#result::value">operator-></a></code> throws <code>leaf::bad_result</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p>Error-capture state, which is the same as the Error state, but in addition to the error ID, it holds a <code>std::shared_ptr<<a href="#polymorphic_context">polymorphic_context</a>></code>.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p><code>result<T></code> objects are nothrow-moveable but are not copyable.</p>
|
||
</div>
|
||
<hr>
|
||
<div class="sect3">
|
||
<h4 id="result::result">Constructors</h4>
|
||
<div class="openblock">
|
||
<div class="content">
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/result.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class T>
|
||
result<T>::result() noexcept;
|
||
|
||
template <class T>
|
||
result<T>::result( T && v ) noexcept; <i class="conum" data-value="1"></i><b>(1)</b>
|
||
|
||
template <class T>
|
||
result<T>::result( T const & v ); <i class="conum" data-value="1"></i><b>(1)</b>
|
||
|
||
template <class U>
|
||
result<T>::result( U && u, <<enabled_if_T_can_be_inited_with_U>> ); <i class="conum" data-value="2"></i><b>(2)</b>
|
||
|
||
template <class T>
|
||
result<T>::result( leaf::error_id err ) noexcept;
|
||
|
||
template <class T>
|
||
template <class Enum>
|
||
result<T>::result( Enum e, typename std::enable_if<std::is_error_code_enum<Enum>::value, Enum>::type * = 0 ) noexcept;
|
||
|
||
template <class T>
|
||
result<T>::result( std::error_code const & ec ) noexcept;
|
||
|
||
template <class T>
|
||
result<T>::result( std::shared_ptr<polymorphic_context> && ctx ) noexcept;
|
||
|
||
template <class T>
|
||
result<T>::result( result && ) noexcept;
|
||
|
||
template <class T>
|
||
template <class U>
|
||
result<T>::result( result<U> && ) noexcept;
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>Not available if <code>T</code> is <code>void</code>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>Available if an object of type <code>T</code> can be initialized with <code>std::forward<U>(u)</code>. This is to enable e.g. <code>result<std::string></code> to be initialized with a string literal.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Requires: </dt>
|
||
<dd>
|
||
<p><code>T</code> must be movable, and its move constructor may not throw; or <code>void</code>.</p>
|
||
</dd>
|
||
<dt class="hdlist1">Effects: </dt>
|
||
<dd>
|
||
<p>Establishes the <code>result<T></code> invariant:</p>
|
||
<div class="openblock">
|
||
<div class="content">
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>To get a <code>result<T></code> in <a href="#result">Value state</a>, initialize it with an object of type <code>T</code> or use the default constructor.</p>
|
||
</li>
|
||
<li>
|
||
<p>To get a <code>result<T></code> in <a href="#result">Error state</a>, initialize it with:</p>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>an <a href="#error_id"><code>error_id</code></a> object.</p>
|
||
<div class="admonitionblock caution">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-caution" title="Caution"></i>
|
||
</td>
|
||
<td class="content">
|
||
Initializing a <code>result<T></code> with a default-initialized <code>error_id</code> object (for which <code>.value()</code> returns <code>0</code>) will still result in <a href="#result">Error state</a>!
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</li>
|
||
<li>
|
||
<p>a <code>std::error_code</code> object.</p>
|
||
</li>
|
||
<li>
|
||
<p>an object of type <code>Enum</code> for which <code>std::is_error_code_enum<Enum>::value</code> is <code>true</code>.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</li>
|
||
<li>
|
||
<p>To get a <code>result<T></code> in <a href="#result">Error-capture state</a>, initialize it with a <code>std::shared_ptr<<a href="#polymorphic_context">polymorphic_context</a>></code> (which can be obtained by calling e.g. <a href="#make_shared_context"><code>make_shared_context</code></a>).</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>When a <code>result</code> object is initialized with a <code>std::error_code</code> object, it is used to initialize an <code>error_id</code> object, then the behavior is the same as if initialized with <code>error_id</code>.</p>
|
||
</div>
|
||
</dd>
|
||
<dt class="hdlist1">Throws: </dt>
|
||
<dd>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>Initializing the <code>result<T></code> in Value state may throw, depending on which constructor of <code>T</code> is invoked;</p>
|
||
</li>
|
||
<li>
|
||
<p>Other constructors do not throw.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
A <code>result</code> that is in value state converts to <code>true</code> in boolean contexts. A <code>result</code> that is not in value state converts to <code>false</code> in boolean contexts.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
<code>result<T></code> objects are nothrow-moveable but are not copyable.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="result::error"><code>error</code></h4>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/result.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class... E>
|
||
<<unspecified-type>> result<T>::error() noexcept;
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Returns: A proxy object of unspecified type, implicitly convertible to any instance of the <code>result</code> class template, as well as to <a href="#error_id"><code>error_id</code></a>.</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>If the proxy object is converted to some <code>result<U></code>:</p>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>If <code>*this</code> is in <a href="#result">Value state</a>, returns <code>result<U>(error_id())</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p>Otherwise the state of <code>*this</code> is moved into the returned <code>result<U></code>.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</li>
|
||
<li>
|
||
<p>If the proxy object is converted to an <code>error_id</code>:</p>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>If <code>*this</code> is in <a href="#result">Value state</a>, returns a default-initialized <a href="#error_id"><code>error_id</code></a> object.</p>
|
||
</li>
|
||
<li>
|
||
<p>If <code>*this</code> is in <a href="#result">Error-capture state</a>, all captured error objects are <a href="#tutorial-loading">loaded</a> in the calling thread, and the captured <code>error_id</code> value is returned.</p>
|
||
</li>
|
||
<li>
|
||
<p>If <code>*this</code> is in <a href="#result">Error state</a>, returns the stored <code>error_id</code>.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</li>
|
||
<li>
|
||
<p>If the proxy object is not used, the state of <code>*this</code> is not modified.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="admonitionblock warning">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-warning" title="Warning"></i>
|
||
</td>
|
||
<td class="content">
|
||
The returned proxy object refers to <code>*this</code>; avoid holding on to it.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="result::load"><code>load</code></h4>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/result.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class T>
|
||
template <class... Item>
|
||
error_id result<T>::load( Item && ... item ) noexcept;
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>This member function is designed for use in <code>return</code> statements in functions that return <code>result<T></code> to forward additional error objects to the caller.</p>
|
||
</div>
|
||
<div class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Effects: </dt>
|
||
<dd>
|
||
<p>As if <code>error_id(this->error()).load(std::forward<Item>(item)…​)</code>.</p>
|
||
</dd>
|
||
<dt class="hdlist1">Returns: </dt>
|
||
<dd>
|
||
<p><code>*this</code>.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="result::operator_eq"><code>operator=</code></h4>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/result.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class T>
|
||
result<T> & result<T>::operator=( result && ) noexcept;
|
||
|
||
template <class T>
|
||
template <class U>
|
||
result<T> & result<T>::operator=( result<U> && ) noexcept;
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Effects: </dt>
|
||
<dd>
|
||
<p>Destroys <code>*this</code>, then re-initializes it as if using the appropriate <code>result<T></code> constructor. Basic exception-safety guarantee.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="result::operator_bool"><code>operator bool</code></h4>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/result.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class T>
|
||
result<T>::operator bool() const noexcept;
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Returns: </dt>
|
||
<dd>
|
||
<p>If <code>*this</code> is in <a href="#result">value state</a>, returns <code>true</code>, otherwise returns <code>false</code>.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="result::value"><code>value</code>, <code>operator*</code>, <code>-></code></h4>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/result.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
void result<void>::value() const; <i class="conum" data-value="1"></i><b>(1)</b>
|
||
|
||
template <class T>
|
||
T const & result<T>::value() const; <i class="conum" data-value="2"></i><b>(2)</b>
|
||
|
||
template <class T>
|
||
T & result<T>::value();
|
||
|
||
template <class T>
|
||
T const & result<T>::operator*() const; <i class="conum" data-value="2"></i><b>(2)</b>
|
||
|
||
template <class T>
|
||
T & result<T>::operator*();
|
||
|
||
template <class T>
|
||
T const * result<T>::operator->() const; <i class="conum" data-value="2"></i><b>(2)</b>
|
||
|
||
template <class T>
|
||
T * result<T>::operator->(); <i class="conum" data-value="2"></i><b>(2)</b>
|
||
|
||
struct bad_result: std::exception { };
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>Only when <code>T</code> is <code>void</code>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>Only when <code>T</code> is not <code>void</code>.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div id="result::bad_result" class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Effects: </dt>
|
||
<dd>
|
||
<p>If <code>*this</code> is in <a href="#result">value state</a>, returns a reference (or pointer) to the stored value, otherwise throws <code>bad_result</code>.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="verbose_diagnostic_info"><code>verbose_diagnostic_info</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/handle_errors.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
class verbose_diagnostic_info: public error_info
|
||
{
|
||
//Constructors unspecified
|
||
|
||
friend std::ostream & operator<<( std::ostream & os, verbose_diagnostic_info const & x );
|
||
};
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Handlers passed to error-handling functions such as <a href="#try_handle_some"><code>try_handle_some</code></a>, <a href="#try_handle_all"><code>try_handle_all</code></a> or <a href="#try_catch"><code>try_catch</code></a> may take an argument of type <code>verbose_diagnostic_info const &</code> if they need to print diagnostic information about the error.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The message printed by <code>operator<<</code> includes the message printed by <code>error_info</code>, followed by information about error objects that were communicated to LEAF (to be associated with the error) for which there was no storage available in any active <a href="#context"><code>context</code></a> (these error objects were discarded by LEAF, because no handler needed them).</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The additional information includes the types and the values of all such error objects.</p>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
<div class="paragraph">
|
||
<p>The behavior of <code>verbose_diagnostic_info</code> (and <a href="#diagnostic_info"><code>diagnostic_info</code></a>) is affected by the value of the macro <code>BOOST_LEAF_DIAGNOSTICS</code>:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>If it is 1 (the default), LEAF produces <code>verbose_diagnostic_info</code> but only if an active error handling context on the call stack takes an argument of type <code>verbose_diagnostic_info</code>;</p>
|
||
</li>
|
||
<li>
|
||
<p>If it is 0, the <code>verbose_diagnostic_info</code> functionality is stubbed out even for error handling contexts that take an argument of type <code>verbose_diagnostic_info</code>. This could save some cycles on the error path in some programs (but is probably not worth it).</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="admonitionblock warning">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-warning" title="Warning"></i>
|
||
</td>
|
||
<td class="content">
|
||
Using <code>verbose_diagnostic_info</code> will likely allocate memory dynamically.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="predicates">Reference: Predicates</h2>
|
||
<div class="sectionbody">
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
The contents of each Reference section are organized alphabetically.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>A predicate is a special type of error handler argument which enables the <a href="#handler_selection_procedure">handler selection procedure</a> to consider the <em>value</em> of available error objects, not only their type; see <a href="#tutorial-predicates">Using Predicates to Handle Errors</a>.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The following predicates are available:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p><a href="#match"><code>match</code></a></p>
|
||
</li>
|
||
<li>
|
||
<p><a href="#match_value"><code>match_value</code></a></p>
|
||
</li>
|
||
<li>
|
||
<p><a href="#match_member"><code>match_member</code></a></p>
|
||
</li>
|
||
<li>
|
||
<p><a href="#catch_"><code>catch_</code></a></p>
|
||
</li>
|
||
<li>
|
||
<p><a href="#if_not"><code>if_not</code></a></p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>In addition, any user-defined type <code>Pred</code> for which <code><a href="#is_predicate">is_predicate</a><Pred>::value</code> is <code>true</code> is treated as a predicate. In this case, it is required that:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p><code>Pred</code> defines an accessible member type <code>error_type</code> to specify the error object type it requires;</p>
|
||
</li>
|
||
<li>
|
||
<p><code>Pred</code> defines an accessible static member function <code>evaluate</code>, which returns a boolean type, and can be invoked with an object of type <code>error_type const &</code>;</p>
|
||
</li>
|
||
<li>
|
||
<p>A <code>Pred</code> instance can be initialized with an object of type <code>error_type</code>.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>When an error handler takes an argument of a predicate type <code>Pred</code>, the <a href="#handler_selection_procedure">handler selection procedure</a> drops the handler if an error object <code>e</code> of type <code>Pred::error_type</code> is not available. Otherwise, the handler is dropped if <code>Pred::evaluate(e)</code> returns <code>false</code>. If the handler is invoked, the <code>Pred</code> argument is initialized with <code>Pred{e}</code>.</p>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
Predicates are evaluated before the error handler is invoked, and so they may not access dynamic state (of course the error handler itself can access dynamic state, e.g. by means of lambda expression captures).
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="title">Example 1:</div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">enum class my_error { e1 = 1, e2, e3 };
|
||
|
||
struct my_pred
|
||
{
|
||
using error_type = my_error; <i class="conum" data-value="1"></i><b>(1)</b>
|
||
|
||
static bool evaluate(my_error) noexcept; <i class="conum" data-value="2"></i><b>(2)</b>
|
||
|
||
my_error matched; <i class="conum" data-value="3"></i><b>(3)</b>
|
||
}
|
||
|
||
namespace boost { namespace leaf {
|
||
|
||
template <>
|
||
struct is_predicate<my_pred>: std::true_type
|
||
{
|
||
};
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>This predicate requires an error object of type <code>my_error</code>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>The handler selection procedure will call this function with an object <code>e</code> of type <code>my_error</code> to evaluate the predicate…​</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="3"></i><b>3</b></td>
|
||
<td>…​and if successful, initialize the <code>my_pred</code> error handler argument with <code>my_pred{e}</code>.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="title">Example 2:</div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">struct my_pred
|
||
{
|
||
using error_type = leaf::e_errno; <i class="conum" data-value="1"></i><b>(1)</b>
|
||
|
||
static bool evaluate(leaf::e_errno const &) noexcept; <i class="conum" data-value="2"></i><b>(2)</b>
|
||
|
||
leaf::e_errno const & matched; <i class="conum" data-value="3"></i><b>(3)</b>
|
||
}
|
||
|
||
namespace boost { namespace leaf {
|
||
|
||
template <>
|
||
struct is_predicate<my_pred>: std::true_type
|
||
{
|
||
};
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>This predicate requires an error object of type <a href="#e_errno"><code>e_errno</code></a>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>The handler selection procedure will call this function with an object <code>e</code> of type <code>e_errno</code> to evaluate the predicate…​</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="3"></i><b>3</b></td>
|
||
<td>…​and if successful, initialize the <code>my_pred</code> error handler argument with <code>my_pred{e}</code>.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
<div class="sect2">
|
||
<h3 id="catch_"><code>catch_</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/pred.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class... Ex>
|
||
struct catch_
|
||
{
|
||
std::exception const & matched;
|
||
|
||
// Other members not specified
|
||
};
|
||
|
||
template <class Ex>
|
||
struct catch_<Ex>
|
||
{
|
||
Ex const & matched;
|
||
|
||
// Other members not specified
|
||
};
|
||
|
||
template <class... Ex>
|
||
struct is_predicate<catch_<Ex...>>: std::true_type
|
||
{
|
||
};
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#is_predicate"><code>is_predicate</code></a></p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>When an error handler takes an argument of type that is an instance of the <code>catch_</code> template, the <a href="#handler_selection_procedure">handler selection procedure</a> first checks if a <code>std::exception</code> was caught. If not, the handler is dropped. Otherwise, the handler is dropped if the caught <code>std::exception</code> can not be <code>dynamic_cast</code> to any of the specified types <code>Ex…​</code>.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>If the error handler is invoked, the <code>matched</code> member can be used to access the exception object.</p>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
See also: <a href="#tutorial-predicates">Using Predicates to Handle Errors</a>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
While <code>catch_</code> requires that the caught exception object is of type that derives from <code>std::exception</code>, it is not required that the <code>Ex…​</code> types derive from <code>std::exception</code>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="title">Example 1:</div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">struct ex1: std::exception { };
|
||
struct ex2: std::exception { };
|
||
|
||
leaf::try_catch(
|
||
[]
|
||
{
|
||
return f(); // throws
|
||
},
|
||
|
||
[](leaf::catch_<ex1, ex2> c)
|
||
{ <i class="conum" data-value="1"></i><b>(1)</b>
|
||
assert(dynamic_cast<ex1 const *>(&c.matched) || dynamic_cast<ex2 const *>(&c.matched));
|
||
....
|
||
} );</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>The handler is selected if <code>f</code> throws an exception of type <code>ex1</code> or <code>ex2</code>.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="title">Example 2:</div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">struct ex1: std::exception { };
|
||
|
||
leaf::try_handle_some(
|
||
[]
|
||
{
|
||
return f(); // returns leaf::result<T>
|
||
},
|
||
|
||
[](ex1 & e)
|
||
{ <i class="conum" data-value="1"></i><b>(1)</b>
|
||
....
|
||
} );</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>The handler is selected if <code>f</code> throws an exception of type <code>ex1</code>. Notice that if we’re interested in only one exception type, as long as that type derives from <code>std::exception</code>, the use of <code>catch_</code> is not required.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="if_not"><code>if_not</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/pred.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class P>
|
||
struct if_not
|
||
{
|
||
<<deduced>> matched;
|
||
|
||
// Other members not specified
|
||
};
|
||
|
||
template <class P>
|
||
struct is_predicate<if_not<P>>: std::true_type
|
||
{
|
||
};
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#is_predicate"><code>is_predicate</code></a></p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>When an error handler takes an argument of type <code>if_not<P></code>, where <code>P</code> is another predicate type, the <a href="#handler_selection_procedure">handler selection procedure</a> first checks if an error object of the type <code>E</code> required by <code>P</code> is available. If not, the handler is dropped. Otherwise, the handler is dropped if <code>P</code> evaluates to <code>true</code>.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>If the error handler is invoked, <code>matched</code> can be used to access the matched object <code>E</code>.</p>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
See also <a href="#tutorial-predicates">Using Predicates to Handle Errors</a>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="title">Example:</div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">enum class my_enum { e1, e2, e3 };
|
||
|
||
leaf::try_handle_some(
|
||
[]
|
||
{
|
||
return f(); // returns leaf::result<T>
|
||
},
|
||
|
||
[]( leaf::if_not<leaf::match<my_enum, my_enum::e1, my_enum::e2>> )
|
||
{ <i class="conum" data-value="1"></i><b>(1)</b>
|
||
....
|
||
} );</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#try_handle_some"><code>try_handle_some</code></a> | <a href="#match"><code>match</code></a></p>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>The handler is selected if an object of type <code>my_enum</code>, which <span class="underline"><strong>does not</strong></span> compare equal to <code>e1</code> or to <code>e2</code>, <span class="underline"><strong>is</strong></span> associated with the detected error.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="match"><code>match</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/pred.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class E, auto... V>
|
||
class match
|
||
{
|
||
<<deduced>> matched;
|
||
|
||
// Other members not specified
|
||
};
|
||
|
||
template <class E, auto... V>
|
||
struct is_predicate<match<E, V...>>: std::true_type
|
||
{
|
||
};
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#is_predicate"><code>is_predicate</code></a></p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>When an error handler takes an argument of type <code>match<E, V…​></code>, the <a href="#handler_selection_procedure">handler selection procedure</a> first checks if an error object <code>e</code> of type <code>E</code> is available. If it is not available, the handler is dropped. Otherwise, the handler is dropped if the following condition is not met:</p>
|
||
</div>
|
||
<div class="paragraph text-center">
|
||
<p><code>p<sub>1</sub> || p<sub>2</sub> || …​ p<sub>n</sub></code>.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Generally, <code>p<sub>i</sub></code> is equivalent to <code>e == V<sub>i</sub></code>, except if <code>V<sub>i</sub></code> is pointer to a function</p>
|
||
</div>
|
||
<div class="paragraph text-center">
|
||
<p><code>bool (*V<sub>i</sub>)(T x)</code>.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>In this case it is required that <code>V<sub>i</sub> != 0</code> and that <code>x</code> can be initialized with <code>E const &</code>, and <code>p<sub>i</sub></code> is equivalent to:</p>
|
||
</div>
|
||
<div class="paragraph text-center">
|
||
<p><code>V<sub>i</sub>(e)</code>.</p>
|
||
</div>
|
||
<div id="category" class="paragraph">
|
||
<p>In particular, it is valid to pass pointer to the function <code>leaf::category<Enum></code> for any <code>V<sub>i</sub></code>, where:</p>
|
||
</div>
|
||
<div class="paragraph text-center">
|
||
<p><code>std::is_error_code_enum<Enum>::value || std::is_error_condition_enum<Enum>::value</code>.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>In this case, <code>p<sub>i</sub></code> is equivalent to:</p>
|
||
</div>
|
||
<div class="paragraph text-center">
|
||
<p><code>&e.category() == &std::error_code(Enum{}).category()</code>.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>If the error handler is invoked, <code>matched</code> can be used to access <code>e</code>.</p>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
See also <a href="#tutorial-predicates">Using Predicates to Handle Errors</a>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="title">Example 1: Handling of a subset of enum values.</div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">enum class my_enum { e1, e2, e3 };
|
||
|
||
leaf::try_handle_some(
|
||
[]
|
||
{
|
||
return f(); // returns leaf::result<T>
|
||
},
|
||
|
||
[]( leaf::match<my_enum, my_enum::e1, my_enum::e2> m )
|
||
{ <i class="conum" data-value="1"></i><b>(1)</b>
|
||
static_assert(std::is_same<my_enum, decltype(m.matched)>::value);
|
||
assert(m.matched == my_enum::e1 || m.matched == my_enum::e2);
|
||
....
|
||
} );</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>The handler is selected if an object of type <code>my_enum</code>, which compares equal to <code>e1</code> or to <code>e2</code>, is associated with the detected error.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="title">Example 2: Handling of a subset of std::error_code enum values (requires at least C++17, see Example 4 for a C++11-compatible workaround).</div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">enum class my_enum { e1=1, e2, e3 };
|
||
|
||
namespace std
|
||
{
|
||
template <> struct is_error_code_enum<my_enum>: std::true_type { };
|
||
}
|
||
|
||
leaf::try_handle_some(
|
||
[]
|
||
{
|
||
return f(); // returns leaf::result<T>
|
||
},
|
||
|
||
[]( leaf::match<std::error_code, my_enum::e1, my_enum::e2> m )
|
||
{ <i class="conum" data-value="1"></i><b>(1)</b>
|
||
static_assert(std::is_same<std::error_code const &, decltype(m.matched)>::value);
|
||
assert(m.matched == my_enum::e1 || m.matched == my_enum::e2);
|
||
....
|
||
} );</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>The handler is selected if an object of type <code>std::error_code</code>, which compares equal to <code>e1</code> or to <code>e2</code>, is associated with the detected error.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="title">Example 3: Handling of a specific std::error_code::category (requires at least C++17).</div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">enum class enum_a { a1=1, a2, a3 };
|
||
enum class enum_b { b1=1, b2, b3 };
|
||
|
||
namespace std
|
||
{
|
||
template <> struct is_error_code_enum<enum_a>: std::true_type { };
|
||
template <> struct is_error_code_enum<enum_b>: std::true_type { };
|
||
}
|
||
|
||
leaf::try_handle_some(
|
||
[]
|
||
{
|
||
return f(); // returns leaf::result<T>
|
||
},
|
||
|
||
[]( leaf::match<std::error_code, leaf::category<enum_a>, enum_b::b2> m )
|
||
{ <i class="conum" data-value="1"></i><b>(1)</b>
|
||
static_assert(std::is_same<std::error_code const &, decltype(m.matched)>::value);
|
||
assert(&m.matched.category() == &std::error_code(enum_{}).category() || m.matched == enum_b::b2);
|
||
....
|
||
} );</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>The handler is selected if an object of type <code>std::error_code</code>, which either has the same <code>std::error_category</code> as that of <code>enum_a</code> or compares equal to <code>enum_b::b2</code>, is associated with the detected error.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div id="condition" class="paragraph">
|
||
<p>The use of the <code>leaf::category</code> template requires automatic deduction of the type of each <code>V<sub>i</sub></code>, which in turn requires C++17 or newer. The same applies to the use of <code>std::error_code</code> as <code>E</code>, but LEAF provides a compatible C++11 workaround for this case, using the template <code>condition</code>. The following is equivalent to Example 2:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="title">Example 4: Handling of a subset of std::error_code enum values using the C++11-compatible API.</div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">enum class my_enum { e1=1, e2, e3 };
|
||
|
||
namespace std
|
||
{
|
||
template <> struct is_error_code_enum<my_enum>: std::true_type { };
|
||
}
|
||
|
||
leaf::try_handle_some(
|
||
[]
|
||
{
|
||
return f(); // returns leaf::result<T>
|
||
},
|
||
|
||
[]( leaf::match<leaf::condition<my_enum>, my_enum::e1, my_enum::e2> m )
|
||
{
|
||
static_assert(std::is_same<std::error_code const &, decltype(m.matched)>::value);
|
||
assert(m.matched == my_enum::e1 || m.matched == my_enum::e2);
|
||
....
|
||
} );</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Instead of a set of values, the <code>match</code> template can be given pointers to functions that implement a custom comparison. In the following example, we define a handler which will be selected to handle any error that communicates an object of the user-defined type <code>severity</code> with value greater than 4:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="title">Example 5: Handling of failures with severity::value greater than a specified threshold (requires at least C++17).</div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">struct severity { int value; }
|
||
|
||
template <int S>
|
||
constexpr bool severity_greater_than( severity const & e ) noexcept
|
||
{
|
||
return e.value > S;
|
||
}
|
||
|
||
leaf::try_handle_some(
|
||
[]
|
||
{
|
||
return f(); // returns leaf::result<T>
|
||
},
|
||
|
||
[]( leaf::match<severity, severity_greater_than<4>> m )
|
||
{
|
||
static_assert(std::is_same<severity const &, decltype(m.matched)>::value);
|
||
assert(m.matched.value > 4);
|
||
....
|
||
} );</code></pre>
|
||
</div>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="match_member"><code>match_member</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/pred.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <auto, auto... V>
|
||
struct match_member;
|
||
|
||
template <class E, class T, T E::* P, auto... V>
|
||
struct match_member<P, V...>
|
||
{
|
||
E const & matched;
|
||
|
||
// Other members not specified
|
||
};
|
||
|
||
template <auto P, auto... V>
|
||
struct is_predicate<match_member<P, V...>>: std::true_type
|
||
{
|
||
};
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#is_predicate"><code>is_predicate</code></a></p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>This predicate is similar to <a href="#match_value"><code>match_value</code></a>, but able to bind any accessible data member of <code>E</code>; e.g. <code>match_member<&E::value, V…​></code> is equivalent to <code>match_value<E, V…​></code>.</p>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
See also <a href="#tutorial-predicates">Using Predicates to Handle Errors</a>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="admonitionblock warning">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-warning" title="Warning"></i>
|
||
</td>
|
||
<td class="content">
|
||
<code>match_member</code> requires at least C++17, whereas <code>match_value</code> does not.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="match_value"><code>match_value</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/pred.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class E, auto... V>
|
||
struct match_value
|
||
{
|
||
E const & matched;
|
||
|
||
// Other members not specified
|
||
};
|
||
|
||
template <class E, auto... V>
|
||
struct is_predicate<match_value<E, V...>>: std::true_type
|
||
{
|
||
};
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#is_predicate"><code>is_predicate</code></a></p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>This predicate is similar to <a href="#match"><code>match</code></a>, but where <code>match</code> compares the available error object <code>e</code> of type <code>E</code> to the specified values <code>V…​</code>, <code>match_value</code> works with <code>e.value</code>.</p>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
See also <a href="#tutorial-predicates">Using Predicates to Handle Errors</a>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="title">Example:</div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">struct e_errno { int value; }
|
||
|
||
leaf::try_handle_some(
|
||
[]
|
||
{
|
||
return f(); // returns leaf::result<T>
|
||
},
|
||
|
||
[]( leaf::match_value<e_errno, ENOENT> m )
|
||
{ <i class="conum" data-value="1"></i><b>(1)</b>
|
||
static_assert(std::is_same<e_errno const &, decltype(m.matched)>::value);
|
||
assert(m.matched.value == ENOENT);
|
||
....
|
||
} );</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>The handler is selected if an object of type <a href="#e_errno"><code>e_errno</code></a>, with <code>.value</code> equal to <code>ENOENT</code>, is associated with the detected error.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="traits">Reference: Traits</h2>
|
||
<div class="sectionbody">
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
The contents of each Reference section are organized alphabetically.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="is_predicate"><code>is_predicate</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/pred.hpp>></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class T>
|
||
struct is_predicate: std::false_type
|
||
{
|
||
};
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The <code>is_predicate</code> template is used by the <a href="#handler_selection_procedure">handler selection procedure</a> to detect predicate types. See <a href="#tutorial-predicates">Using Predicates to Handle Errors</a>.</p>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="is_result_type"><code>is_result_type</code></h3>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/error.hpp>></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace boost { namespace leaf {
|
||
|
||
template <class R>
|
||
struct is_result_type: std::false_type
|
||
{
|
||
};
|
||
|
||
} }</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The error-handling functionality provided by <a href="#try_handle_some"><code>try_handle_some</code></a> and <a href="#try_handle_all"><code>try_handle_all</code></a> — including the ability to <a href="#tutorial-loading">load</a> error objects of arbitrary types — is compatible with any external <code>result<T></code> type R, as long as for a given object <code>r</code> of type <code>R</code>:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>If <code>bool(r)</code> is <code>true</code>, <code>r</code> indicates success, in which case it is valid to call <code>r.value()</code> to recover the <code>T</code> value.</p>
|
||
</li>
|
||
<li>
|
||
<p>Otherwise <code>r</code> indicates a failure, in which case it is valid to call <code>r.error()</code>. The returned value is used to initialize an <code>error_id</code> (note: <code>error_id</code> can be initialized by <code>std::error_code</code>).</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>To use an external <code>result<T></code> type R, you must specialize the <code>is_result_type</code> template so that <code>is_result_type<R>::value</code> evaluates to <code>true</code>.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Naturally, the provided <code>leaf::<a href="#result">result</a><T></code> class template satisfies these requirements. In addition, it allows error objects to be transported across thread boundaries, using a <code>std::shared_ptr<<a href="#polymorphic_context">polymorphic_context</a>></code>.</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="macros">Reference: Macros</h2>
|
||
<div class="sectionbody">
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
The contents of each Reference section are organized alphabetically.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
<div class="sect2">
|
||
<h3 id="_boost_leaf"><code>BOOST_LEAF_</code></h3>
|
||
<div class="sect3">
|
||
<h4 id="BOOST_LEAF_ASSIGN"><code>ASSIGN</code></h4>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/error.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">#define BOOST_LEAF_ASSIGN(v, r)\
|
||
auto && <<temp>> = r;\
|
||
if( !<<temp>> )\
|
||
return <<temp>>.error();\
|
||
v = std::forward<decltype(<<temp>>)>(<<temp>>).value()</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p><code>BOOST_LEAF_ASSIGN</code> is useful when calling a function that returns <code>result<T></code> (other than <code>result<void></code>), if the desired behavior is to forward any errors to the caller verbatim.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>In case of success, the result <code>value()</code> of type <code>T</code> is assigned to the specified variable <code>v</code>, which must have been declared prior to invoking <code>BOOST_LEAF_ASSIGN</code>. However, it is possible to use <code>BOOST_LEAF_ASSIGN</code> to declare a new variable, by passing in <code>v</code> its type together with its name, e.g. <code>BOOST_LEAF_ASSIGN(auto && x, f())</code> calls <code>f</code>, forwards errors to the caller, while capturing successful values in <code>x</code>.</p>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
See also <a href="#BOOST_LEAF_AUTO"><code>AUTO</code></a>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="BOOST_LEAF_AUTO"><code>AUTO</code></h4>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/error.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">#define BOOST_LEAF_AUTO(v, r)\
|
||
BOOST_LEAF_ASSIGN(auto v, r)</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#BOOST_LEAF_ASSIGN"><code>ASSIGN</code></a></p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p><code>BOOST_LEAF_AUTO</code> is useful when calling a function that returns <code>result<T></code> (other than <code>result<void></code>), if the desired behavior is to forward any errors to the caller verbatim.</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="title">Example:</div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">leaf::result<int> compute_value();
|
||
|
||
leaf::result<float> add_values()
|
||
{
|
||
BOOST_LEAF_AUTO(v1, compute_value()); <i class="conum" data-value="1"></i><b>(1)</b>
|
||
BOOST_LEAF_AUTO(v2, compute_value()); <i class="conum" data-value="2"></i><b>(2)</b>
|
||
return v1 + v2;
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>Call <code>compute_value</code>, bail out on failure, define a local variable <code>v1</code> on success.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>Call <code>compute_value</code> again, bail out on failure, define a local variable <code>v2</code> on success.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Of course, we could write <code>add_value</code> without using <code>BOOST_LEAF_AUTO</code>. This is equivalent:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="nowrap">leaf::result<float> add_values()
|
||
{
|
||
auto v1 = compute_value();
|
||
if( !v1 )
|
||
return v1.error();
|
||
|
||
auto v2 = compute_value();
|
||
if( !v2 )
|
||
return v2.error();
|
||
|
||
return v1.value() + v2.value();
|
||
}</pre>
|
||
</div>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
See also <a href="#BOOST_LEAF_ASSIGN"><code>ASSIGN</code></a>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="BOOST_LEAF_CHECK"><code>CHECK</code></h4>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/error.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">#define BOOST_LEAF_CHECK(r)\
|
||
auto && <<temp>> = r;\
|
||
if( <<temp>> )\
|
||
;\
|
||
else\
|
||
return <<temp>>.error()</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p><code>BOOST_LEAF_CHECK</code> is useful when calling a function that returns <code>result<void></code>, if the desired behavior is to forward any errors to the caller verbatim.</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="title">Example:</div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">leaf::result<void> send_message( char const * msg );
|
||
|
||
leaf::result<int> compute_value();
|
||
|
||
leaf::result<int> say_hello_and_compute_value()
|
||
{
|
||
BOOST_LEAF_CHECK(send_message("Hello!")); <i class="conum" data-value="1"></i><b>(1)</b>
|
||
return compute_value();
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>Try to send a message, then compute a value, report errors using BOOST_LEAF_CHECK.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Equivalent implementation without <code>BOOST_LEAF_CHECK</code>:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="nowrap">leaf::result<float> add_values()
|
||
{
|
||
auto r = send_message("Hello!");
|
||
if( !r )
|
||
return r.error();
|
||
|
||
return compute_value();
|
||
}</pre>
|
||
</div>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="BOOST_LEAF_EXCEPTION"><code>EXCEPTION</code></h4>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/exception.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">#define BOOST_LEAF_EXCEPTION <<voodoo>></code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Effects: </dt>
|
||
<dd>
|
||
<p><code>BOOST_LEAF_EXCEPTION(e…​)</code> is equivalent to <code>leaf::<a href="#exception">exception</a>(e…​)</code>, except the current source location is automatically passed, in a <code><a href="#e_source_location"><code>e_source_location</code></a></code> object (in addition to all <code>e…​</code> objects).</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="BOOST_LEAF_NEW_ERROR"><code>NEW_ERROR</code></h4>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/error.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">#define BOOST_LEAF_NEW_ERROR <<voodoo>></code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Effects: </dt>
|
||
<dd>
|
||
<p><code>BOOST_LEAF_NEW_ERROR(e…​)</code> is equivalent to <code>leaf::<a href="#new_error">new_error</a>(e…​)</code>, except the current source location is automatically passed, in a <code><a href="#e_source_location"><code>e_source_location</code></a></code> object (in addition to all <code>e…​</code> objects).</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="BOOST_LEAF_THROW_EXCEPTION"><code>THROW_EXCEPTION</code></h4>
|
||
<div class="listingblock">
|
||
<div class="title">#include <boost/leaf/exception.hpp></div>
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">#define BOOST_LEAF_THROW_EXCEPTION throw BOOST_LEAF_EXCEPTION</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Effects: </dt>
|
||
<dd>
|
||
<p>Throws the exception object returned by <a href="#BOOST_LEAF_EXCEPTION"><code>EXCEPTION</code></a>.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="rationale">Design</h2>
|
||
<div class="sectionbody">
|
||
<div class="sect2">
|
||
<h3 id="_rationale">Rationale</h3>
|
||
<div class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Definition: </dt>
|
||
<dd>
|
||
<p>Objects that carry information about error conditions are called error objects. For example, objects of type <code>std::error_code</code> are error objects.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
The following reasoning is independent of the mechanism used to transport error objects, whether it is exception handling or anything else.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Definition: </dt>
|
||
<dd>
|
||
<p>Depending on their interaction with error objects, functions can be classified as follows:</p>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p><strong>Error-initiating</strong>: functions that initiate error conditions by creating new error objects.</p>
|
||
</li>
|
||
<li>
|
||
<p><strong>Error-neutral</strong>: functions that forward to the caller error objects communicated by lower-level functions they call.</p>
|
||
</li>
|
||
<li>
|
||
<p><strong>Error-handling</strong>: functions that dispose of error objects they have received, recovering normal program operation.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>A crucial observation is that <em>error-initiating</em> functions are typically low-level functions that lack any context and can not determine, much less dictate, the correct program behavior in response to the errors they may initiate. Error conditions which (correctly) lead to termination in some programs may (correctly) be ignored in others; yet other programs may recover from them and resume normal operation.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The same reasoning applies to <em>error-neutral</em> functions, but in this case there is the additional issue that the errors they need to communicate, in general, are initiated by functions multiple levels removed from them in the call chain, functions which usually are — and should be treated as — implementation details. An <em>error-neutral</em> function should not be coupled with error object types communicated by <em>error-initiating</em> functions, for the same reason it should not be coupled with any other aspect of their interface.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Finally, <em>error-handling</em> functions, by definition, have the full context they need to deal with at least some, if not all, failures. In their scope it is an absolute necessity that the author knows exactly what information must be communicated by lower level functions in order to recover from each error condition. Specifically, none of this necessary information can be treated as implementation details; in this case, the coupling which is to be avoided in <em>error-neutral</em> functions is in fact desirable.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>We’re now ready to define our</p>
|
||
</div>
|
||
<div class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Design goals: </dt>
|
||
<dd>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p><strong>Error-initiating</strong> functions should be able to communicate <span class="underline">all</span> information available to them that is relevant to the failure being reported.</p>
|
||
</li>
|
||
<li>
|
||
<p><strong>Error-neutral</strong> functions should not be coupled with error types communicated by lower-level <em>error-initiating</em> functions. They should be able to augment any failure with additional relevant information available to them.</p>
|
||
</li>
|
||
<li>
|
||
<p><strong>Error-handling</strong> functions should be able to access all the information communicated by <em>error-initiating</em> or <em>error-neutral</em> functions that is needed in order to deal with failures.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The design goal that <em>error-neutral</em> functions are not coupled with the static type of error objects that pass through them seems to require dynamic polymorphism and therefore dynamic memory allocations (the Boost Exception library meets this design goal at the cost of dynamic memory allocation).</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>As it turns out, dynamic memory allocation is not necessary due to the following</p>
|
||
</div>
|
||
<div class="dlist">
|
||
<dl>
|
||
<dt class="hdlist1">Fact: </dt>
|
||
<dd>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p><strong>Error-handling</strong> functions "know" which of the information <em>error-initiating</em> and <em>error-neutral</em> functions are <span class="underline">able</span> to communicate is <span class="underline">actually needed</span> in order to deal with failures in a particular program. Ideally, no resources should be <span class="line-through">used</span> wasted storing or communicating information which is not currently needed to handle errors, <span class="underline">even if it is relevant to the failure</span>.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>For example, if a library function is able to communicate an error code but the program does not need to know the exact error code, then that information may be ignored at the time the library function attempts to communicate it. On the other hand, if an <em>error-handling</em> function needs that information, the memory needed to store it can be reserved statically in its scope.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The LEAF functions <a href="#try_handle_some"><code>try_handle_some</code></a>, <a href="#try_handle_all"><code>try_handle_all</code></a> and <a href="#try_catch"><code>try_catch</code></a> implement this idea. Users provide error-handling lambda functions, each taking arguments of the types it needs in order to recover from a particular error condition. LEAF simply provides the space needed to store these types (in the form of a <code>std::tuple</code>, using automatic storage duration) until they are passed to a suitable handler.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>At the time this space is reserved in the scope of an error-handling function, <code>thread_local</code> pointers of the required error types are set to point to the corresponding objects within it. Later on, <em>error-initiating</em> or <em>error-neutral</em> functions wanting to communicate an error object of a given type <code>E</code> use the corresponding <code>thread_local</code> pointer to detect if there is currently storage available for this type:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>If the pointer is not null, storage is available and the object is moved into the pointed storage, exactly once — regardless of how many levels of function calls must unwind before an <em>error-handling</em> function is reached.</p>
|
||
</li>
|
||
<li>
|
||
<p>If the pointer is null, storage is not available and the error object is discarded, since no error-handling function makes any use of it in this program — saving resources.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>This almost works, except we need to make sure that <em>error-handling</em> functions are protected from accessing stale error objects stored in response to previous failures, which would be a serious logic error. To this end, each occurrence of an error is assigned a unique <a href="#error_id"><code>error_id</code></a>. Each of the <code>E…​</code> objects stored in error-handling scopes is assigned an <code>error_id</code> as well, permanently associating it with a particular failure.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Thus, to handle a failure we simply match the available error objects (associated with its unique <code>error_id</code>) with the argument types required by each user-provided error-handling function. In terms of C++ exception handling, it is as if we could write something like:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">try
|
||
{
|
||
auto r = process_file();
|
||
|
||
//Success, use r:
|
||
....
|
||
}
|
||
|
||
catch(file_read_error &, e_file_name const & fn, e_errno const & err)
|
||
{
|
||
std::cerr <<
|
||
"Could not read " << fn << ", errno=" << err << std::endl;
|
||
}
|
||
|
||
catch(file_read_error &, e_errno const & err)
|
||
{
|
||
std::cerr <<
|
||
"File read error, errno=" << err << std::endl;
|
||
}
|
||
|
||
catch(file_read_error &)
|
||
{
|
||
std::cerr << "File read error!" << std::endl;
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Of course this syntax is not valid, so LEAF uses lambda functions to express the same idea:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">leaf::try_catch(
|
||
|
||
[]
|
||
{
|
||
auto r = process_file(); //Throws in case of failure, error objects stored inside the try_catch scope
|
||
|
||
//Success, use r:
|
||
....
|
||
}
|
||
|
||
[](file_read_error &, e_file_name const & fn, e_errno const & err)
|
||
{
|
||
std::cerr <<
|
||
"Could not read " << fn << ", errno=" << err << std::endl;
|
||
},
|
||
|
||
[](file_read_error &, e_errno const & err)
|
||
{
|
||
std::cerr <<
|
||
"File read error, errno=" << err << std::endl;
|
||
},
|
||
|
||
[](file_read_error &)
|
||
{
|
||
std::cerr << "File read error!" << std::endl;
|
||
} );</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#try_catch"><code>try_catch</code></a> | <a href="#e_file_name"><code>e_file_name</code></a> | <a href="#e_errno"><code>e_errno</code></a></p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Similar syntax works without exception handling as well. Below is the same snippet, written using <code><a href="#result">result</a><T></code>:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">return leaf::try_handle_some(
|
||
|
||
[]() -> leaf::result<void>
|
||
{
|
||
BOOST_LEAF_AUTO(r, process_file()); //In case of errors, error objects are stored inside the try_handle_some scope
|
||
|
||
//Success, use r:
|
||
....
|
||
|
||
return { };
|
||
}
|
||
|
||
[](leaf::match<error_enum, file_read_error>, e_file_name const & fn, e_errno const & err)
|
||
{
|
||
std::cerr <<
|
||
"Could not read " << fn << ", errno=" << err << std::endl;
|
||
},
|
||
|
||
[](leaf::match<error_enum, file_read_error>, e_errno const & err)
|
||
{
|
||
std::cerr <<
|
||
"File read error, errno=" << err << std::endl;
|
||
},
|
||
|
||
[](leaf::match<error_enum, file_read_error>)
|
||
{
|
||
std::cerr << "File read error!" << std::endl;
|
||
} );</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#result"><code>result</code></a> | <a href="#try_handle_some"><code>try_handle_some</code></a> | <a href="#match"><code>match</code></a> | <a href="#e_file_name"><code>e_file_name</code></a> | <a href="#e_errno"><code>e_errno</code></a></p>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
Please post questions and feedback on the Boost Developers Mailing List.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="exception_specifications">Critique 1: Error Types Do Not Participate in Function Signatures</h3>
|
||
<div class="paragraph">
|
||
<p>A knee-jerk critique of the LEAF design is that it does not statically enforce that each possible error condition is recognized and handled by the program. One idea I’ve heard from multiple sources is to add <code>E…​</code> parameter pack to <code>result<T></code>, essentially turning it into <code>expected<T,E…​></code>, so we could write something along these lines:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">expected<T, E1, E2, E3> f() noexcept; <i class="conum" data-value="1"></i><b>(1)</b>
|
||
|
||
expected<T, E1, E3> g() noexcept <i class="conum" data-value="2"></i><b>(2)</b>
|
||
{
|
||
if( expected<T, E1, E2, E3> r = f() )
|
||
{
|
||
return r; //Success, return the T
|
||
}
|
||
else
|
||
{
|
||
return r.handle_error<E2>( [] ( .... ) <i class="conum" data-value="3"></i><b>(3)</b>
|
||
{
|
||
....
|
||
} );
|
||
}
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td><code>f</code> may only return error objects of type <code>E1</code>, <code>E2</code>, <code>E3</code>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td><code>g</code> narrows that to only <code>E1</code> and <code>E3</code>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="3"></i><b>3</b></td>
|
||
<td>Because <code>g</code> may only return error objects of type <code>E1</code> and <code>E3</code>, it uses <code>handle_error</code> to deal with <code>E2</code>. In case <code>r</code> contains <code>E1</code> or <code>E3</code>, <code>handle_error</code> simply returns <code>r</code>, narrowing the error type parameter pack from <code>E1, E2, E3</code> down to <code>E1, E3</code>. If <code>r</code> contains an <code>E2</code>, <code>handle_error</code> calls the supplied lambda, which is required to return one of <code>E1</code>, <code>E3</code> (or a valid <code>T</code>).</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The motivation here is to help avoid bugs in functions that handle errors that pop out of <code>g</code>: as long as the programmer deals with <code>E1</code> and <code>E3</code>, he can rest assured that no error is left unhandled.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Congratulations, we’ve just discovered exception specifications. The difference is that exception specifications, before being removed from C++, were enforced dynamically, while this idea is equivalent to statically-enforced exception specifications, like they are in Java.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Why not use the equivalent of exception specifications, even if they are enforced statically?</p>
|
||
</div>
|
||
<div class="quoteblock">
|
||
<blockquote>
|
||
The short answer is that nobody knows how to fix exception specifications in any language, because the dynamic enforcement C++ chose has only different (not greater or fewer) problems than the static enforcement Java chose. …​ When you go down the Java path, people love exception specifications until they find themselves all too often encouraged, or even forced, to add <code>throws Exception</code>, which immediately renders the exception specification entirely meaningless. (Example: Imagine writing a Java generic that manipulates an arbitrary type <code>T</code>).<sup class="footnote">[<a id="_footnoteref_1" class="footnote" href="#_footnotedef_1" title="View footnote.">1</a>]</sup>
|
||
</blockquote>
|
||
<div class="attribution">
|
||
— Herb Sutter
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Consider again the example above: assuming we don’t want important error-related information to be lost, values of type <code>E1</code> and/or <code>E3</code> must be able to encode any <code>E2</code> value dynamically. But like Sutter points out, in generic contexts we don’t know what errors may result in calling a user-supplied function. The only way around that is to specify a single type (e.g. <code>std::error_code</code>) that can communicate any and all errors, which ultimately defeats the idea of using static type checking to enforce correct error handling.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>That said, in every program there are certain <em>error-handling</em> functions (e.g. <code>main</code>) which are required to handle any error, and it is highly desirable to be able to enforce this requirement at compile-time. In LEAF, the <code>try_handle_all</code> function implements this idea: if the user fails to supply at least one handler that will match any error, the result is a compile error. This guarantees that the scope invoking <code>try_handle_all</code> is prepared to recover from any failure.</p>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="translation">Critique 2: LEAF Does Not Facilitate Mapping Between Different Error Types</h3>
|
||
<div class="paragraph">
|
||
<p>Most C++ programs use multiple C and C++ libraries, and each library may provide its own system of error codes. But because it is difficult to define static interfaces that can communicate arbitrary error code types, a popular idea is to map each library-specific error code to a common program-wide enum.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>For example, if we have — </p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace lib_a
|
||
{
|
||
enum error
|
||
{
|
||
ok,
|
||
ec1,
|
||
ec2,
|
||
....
|
||
};
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace lib_b
|
||
{
|
||
enum error
|
||
{
|
||
ok,
|
||
ec1,
|
||
ec2,
|
||
....
|
||
};
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p> — we could define:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">namespace program
|
||
{
|
||
enum error
|
||
{
|
||
ok,
|
||
lib_a_ec1,
|
||
lib_a_ec2,
|
||
....
|
||
lib_b_ec1,
|
||
lib_b_ec2,
|
||
....
|
||
};
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>An error-handling library could provide conversion API that uses the C++ static type system to automate the mapping between the different error enums. For example, it may define a class template <code>result<T,E></code> with value-or-error variant semantics, so that:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p><code>lib_a</code> errors are transported in <code>result<T,lib_a::error></code>,</p>
|
||
</li>
|
||
<li>
|
||
<p><code>lib_b</code> errors are transported in <code>result<T,lib_b::error></code>,</p>
|
||
</li>
|
||
<li>
|
||
<p>then both are automatically mapped to <code>result<T,program::error></code> once control reaches the appropriate scope.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>There are several problems with this idea:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>It is prone to errors, both during the initial implementation as well as under maintenance.</p>
|
||
</li>
|
||
<li>
|
||
<p>It does not compose well. For example, if both of <code>lib_a</code> and <code>lib_b</code> use <code>lib_c</code>, errors that originate in <code>lib_c</code> would be obfuscated by the different APIs exposed by each of <code>lib_a</code> and <code>lib_b</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p>It presumes that all errors in the program can be specified by exactly one error code, which is false.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>To elaborate on the last point, consider a program that attempts to read a configuration file from three different locations: in case all of the attempts fail, it should communicate each of the failures. In theory <code>result<T,E></code> handles this case well:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">struct attempted_location
|
||
{
|
||
std::string path;
|
||
error ec;
|
||
};
|
||
|
||
struct config_error
|
||
{
|
||
attempted_location current_dir, user_dir, app_dir;
|
||
};
|
||
|
||
result<config,config_error> read_config();</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>This looks nice, until we realize what the <code>config_error</code> type means for the automatic mapping API we wanted to define: an <code>enum</code> can not represent a <code>struct</code>. It is a fact that we can not assume that all error conditions can be fully specified by an <code>enum</code>; an error handling library must be able to transport arbitrary static types efficiently.</p>
|
||
</div>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="errors_are_not_implementation_details">Critique 3: LEAF Does Not Treat Low Level Error Types as Implementation Details</h3>
|
||
<div class="paragraph">
|
||
<p>This critique is a combination of <a href="#exception_specifications">Critique 1</a> and <a href="#translation">Critique 2</a>, but it deserves special attention. Let’s consider this example using LEAF:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">leaf::result<std::string> read_line( reader & r );
|
||
|
||
leaf::result<parsed_line> parse_line( std::string const & line );
|
||
|
||
leaf::result<parsed_line> read_and_parse_line( reader & r )
|
||
{
|
||
BOOST_LEAF_AUTO(line, read_line(r)); <i class="conum" data-value="1"></i><b>(1)</b>
|
||
BOOST_LEAF_AUTO(parsed, parse_line(line)); <i class="conum" data-value="2"></i><b>(2)</b>
|
||
return parsed;
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#result"><code>result</code></a> | <a href="#BOOST_LEAF_AUTO"><code>AUTO</code></a></p>
|
||
</div>
|
||
<div class="colist arabic">
|
||
<table>
|
||
<tr>
|
||
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
||
<td>Read a line, forward errors to the caller.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
||
<td>Parse the line, forward errors to the caller.</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The objection is that LEAF will forward verbatim the errors that are detected in <code>read_line</code> or <code>parse_line</code> to the caller of <code>read_and_parse_line</code>. The premise of this objection is that such low-level errors are implementation details and should be treated as such. Under this premise, <code>read_and_parse_line</code> should act as a translator of sorts, in both directions:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>When called, it should translate its own arguments to call <code>read_line</code> and <code>parse_line</code>;</p>
|
||
</li>
|
||
<li>
|
||
<p>If an error is detected, it should translate the errors from the error types returned by <code>read_line</code> and <code>parse_line</code> to a higher-level type.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The motivation is to isolate the caller of <code>read_and_parse_line</code> from its implementation details <code>read_line</code> and <code>parse_line</code>.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>There are two possible ways to implement this translation:</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p><strong>1)</strong> <code>read_and_parse_line</code> understands the semantics of <strong>all possible failures</strong> that may be reported by both <code>read_line</code> and <code>parse_line</code>, implementing a non-trivial mapping which both <em>erases</em> information that is considered not relevant to its caller, as well as encodes <em>different</em> semantics in the error it reports. In this case <code>read_and_parse_line</code> assumes full responsibility for describing precisely what went wrong, using its own type specifically designed for the job.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p><strong>2)</strong> <code>read_and_parse_line</code> returns an error object that essentially indicates which of the two inner functions failed, and also transports the original error object without understanding its semantics and without any loss of information, wrapping it in a new error type.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The problem with <strong>1)</strong> is that typically the caller of <code>read_and_parse_line</code> is not going to handle the error, but it does need to forward it to its caller. In our attempt to protect the <strong>one</strong> error-handling function from "implementation details", we’ve coupled the interface of <strong>all</strong> intermediate error-neutral functions with the static types of errors they do not understand and do not handle.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Consider the case where <code>read_line</code> communicates <code>errno</code> in its errors. What is <code>read_and_parse_line</code> supposed to do with e.g. <code>EACCESS</code>? Turn it into <code>READ_AND_PARSE_LINE_EACCESS</code>? To what end, other than to obfuscate the original (already complex and platform-specific) semantics of <code>errno</code>?</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>And what if the call to <code>read</code> is polymorphic, which is also typical? What if it involves a user-supplied function object? What kinds of errors does it return and why should <code>read_and_parse_line</code> care?</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Therefore, we’re left with <strong>2)</strong>. There’s almost nothing wrong with this option, since it passes any and all error-related information from lower level functions without any loss. However, using a wrapper type to grant (presumably dynamic) access to any lower-level error type it may be transporting is cumbersome and (like Niall Douglas <a href="#interoperability">explains</a>) in general probably requires dynamic allocations. It is better to use independent error types that communicate the additional information not available in the original error object, while error handlers rely on LEAF to provide efficient access to any and all low-level error types, as needed.</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="_alternatives_to_leaf">Alternatives to LEAF</h2>
|
||
<div class="sectionbody">
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p><a href="https://www.boost.org/doc/libs/release/libs/exception/doc/boost-exception.html">Boost Exception</a></p>
|
||
</li>
|
||
<li>
|
||
<p><a href="https://ned14.github.io/outcome">Boost Outcome</a></p>
|
||
</li>
|
||
<li>
|
||
<p><a href="https://github.com/TartanLlama/expected"><code>tl::expected</code></a></p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Below we offer a comparison of Boost LEAF to Boost Exception and to Boost Outcome.</p>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="boost_exception">Comparison to Boost Exception</h3>
|
||
<div class="paragraph">
|
||
<p>While LEAF can be used without exception handling, in the use case when errors are communicated by throwing exceptions, it can be viewed as a better, more efficient alternative to Boost Exception. LEAF has the following advantages over Boost Exception:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>LEAF does not allocate memory dynamically;</p>
|
||
</li>
|
||
<li>
|
||
<p>LEAF does not waste system resources communicating error objects not used by specific error handling functions;</p>
|
||
</li>
|
||
<li>
|
||
<p>LEAF does not store the error objects in the exception object, and therefore it is able to augment exceptions thrown by external libraries (Boost Exception can only augment exceptions of types that derive from <code>boost::exception</code>).</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The following tables outline the differences between the two libraries which should be considered when code that uses Boost Exception is refactored to use LEAF instead.</p>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
It is possible to access Boost Exception error information using the LEAF error handling interface. See <a href="#tutorial-boost_exception_integration">Boost Exception Integration</a>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<table class="tableblock frame-all grid-all stripes-none stretch">
|
||
<caption class="title">Table 1. Defining a custom type for transporting values of type T</caption>
|
||
<colgroup>
|
||
<col style="width: 50%;">
|
||
<col style="width: 50%;">
|
||
</colgroup>
|
||
<thead>
|
||
<tr>
|
||
<th class="tableblock halign-left valign-top">Boost Exception</th>
|
||
<th class="tableblock halign-left valign-top">LEAF</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">typedef error_info<struct my_info_,T> my_info;</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="https://www.boost.org/doc/libs/release/libs/exception/doc/error_info.html"><code>boost::error_info</code></a></p>
|
||
</div></div></td>
|
||
<td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">struct my_info { T value; };</code></pre>
|
||
</div>
|
||
</div></div></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<table class="tableblock frame-all grid-all stripes-none stretch">
|
||
<caption class="title">Table 2. Passing arbitrary info at the point of the throw</caption>
|
||
<colgroup>
|
||
<col style="width: 50%;">
|
||
<col style="width: 50%;">
|
||
</colgroup>
|
||
<thead>
|
||
<tr>
|
||
<th class="tableblock halign-left valign-top">Boost Exception</th>
|
||
<th class="tableblock halign-left valign-top">LEAF</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">throw my_exception() <<
|
||
my_info(x) <<
|
||
my_info(y);</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="https://www.boost.org/doc/libs/release/libs/exception/doc/exception_operator_shl.html"><code>operator<<</code></a></p>
|
||
</div></div></td>
|
||
<td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">throw leaf::exception( my_exception(),
|
||
my_info{x},
|
||
my_info{y} );</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#exception"><code>exception</code></a></p>
|
||
</div></div></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<table class="tableblock frame-all grid-all stripes-none stretch">
|
||
<caption class="title">Table 3. Augmenting exceptions in error-neutral contexts</caption>
|
||
<colgroup>
|
||
<col style="width: 50%;">
|
||
<col style="width: 50%;">
|
||
</colgroup>
|
||
<thead>
|
||
<tr>
|
||
<th class="tableblock halign-left valign-top">Boost Exception</th>
|
||
<th class="tableblock halign-left valign-top">LEAF</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">try
|
||
{
|
||
f();
|
||
}
|
||
catch( boost::exception & e )
|
||
{
|
||
e << my_info(x);
|
||
throw;
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="https://www.boost.org/doc/libs/release/libs/exception/doc/exception.html"><code>boost::exception</code></a> | <a href="https://www.boost.org/doc/libs/release/libs/exception/doc/exception_operator_shl.html"><code>operator<<</code></a></p>
|
||
</div></div></td>
|
||
<td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">auto load = leaf::on_error( my_info{x} );
|
||
|
||
f();</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#on_error"><code>on_error</code></a></p>
|
||
</div></div></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<table class="tableblock frame-all grid-all stripes-none stretch">
|
||
<caption class="title">Table 4. Obtaining arbitrary info at the point of the catch</caption>
|
||
<colgroup>
|
||
<col style="width: 50%;">
|
||
<col style="width: 50%;">
|
||
</colgroup>
|
||
<thead>
|
||
<tr>
|
||
<th class="tableblock halign-left valign-top">Boost Exception</th>
|
||
<th class="tableblock halign-left valign-top">LEAF</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">try
|
||
{
|
||
f();
|
||
}
|
||
catch( my_exception & e )
|
||
{
|
||
if( T * v = get_error_info<my_info>(e) )
|
||
{
|
||
//my_info is available in e.
|
||
}
|
||
}</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="https://www.boost.org/doc/libs/release/libs/exception/doc/get_error_info.html"><code>boost::get_error_info</code></a></p>
|
||
</div></div></td>
|
||
<td class="tableblock halign-left valign-top"><div class="content"><div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">leaf::try_catch(
|
||
[]
|
||
{
|
||
f(); // throws
|
||
}
|
||
[](my_exception &, my_info const & x)
|
||
{
|
||
//my_info is available with
|
||
//the caught exception.
|
||
} );</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph text-right">
|
||
<p><a href="#try_catch"><code>try_catch</code></a></p>
|
||
</div></div></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<table class="tableblock frame-all grid-all stripes-none stretch">
|
||
<caption class="title">Table 5. Transporting of error objects</caption>
|
||
<colgroup>
|
||
<col style="width: 50%;">
|
||
<col style="width: 50%;">
|
||
</colgroup>
|
||
<thead>
|
||
<tr>
|
||
<th class="tableblock halign-left valign-top">Boost Exception</th>
|
||
<th class="tableblock halign-left valign-top">LEAF</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
|
||
<p>All supplied <a href="https://www.boost.org/doc/libs/release/libs/exception/doc/error_info.html"><code>boost::error_info</code></a> objects are allocated dynamically and stored in the <a href="https://www.boost.org/doc/libs/release/libs/exception/doc/exception.html"><code>boost::exception</code></a> subobject of exception objects.</p>
|
||
</div></div></td>
|
||
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
|
||
<p>User-defined error objects are stored statically in the scope of <a href="#try_catch"><code>try_catch</code></a>, but only if their types are needed to handle errors; otherwise they are discarded.</p>
|
||
</div></div></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<table class="tableblock frame-all grid-all stripes-none stretch">
|
||
<caption class="title">Table 6. Transporting of error objects across thread boundaries</caption>
|
||
<colgroup>
|
||
<col style="width: 50%;">
|
||
<col style="width: 50%;">
|
||
</colgroup>
|
||
<thead>
|
||
<tr>
|
||
<th class="tableblock halign-left valign-top">Boost Exception</th>
|
||
<th class="tableblock halign-left valign-top">LEAF</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
|
||
<p><a href="https://www.boost.org/doc/libs/release/libs/exception/doc/exception_ptr.html"><code>boost::exception_ptr</code></a> automatically captures <a href="https://www.boost.org/doc/libs/release/libs/exception/doc/error_info.html"><code>boost::error_info</code></a> objects stored in a <code>boost::exception</code> and can transport them across thread boundaries.</p>
|
||
</div></div></td>
|
||
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
|
||
<p>Transporting error objects across thread boundaries requires the use of <a href="#capture"><code>capture</code></a>.</p>
|
||
</div></div></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<table class="tableblock frame-all grid-all stripes-none stretch">
|
||
<caption class="title">Table 7. Printing of error objects in automatically-generated diagnostic information messages</caption>
|
||
<colgroup>
|
||
<col style="width: 50%;">
|
||
<col style="width: 50%;">
|
||
</colgroup>
|
||
<thead>
|
||
<tr>
|
||
<th class="tableblock halign-left valign-top">Boost Exception</th>
|
||
<th class="tableblock halign-left valign-top">LEAF</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
|
||
<p><code>boost::error_info</code> types may define conversion to <code>std::string</code> by providing <code>to_string</code> overloads <strong>or</strong> by overloading <code>operator<<</code> for <code>std::ostream</code>.</p>
|
||
</div></div></td>
|
||
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
|
||
<p>LEAF does not use <code>to_string</code>. Error types may define <code>operator<<</code> overloads for <code>std::ostream</code>.</p>
|
||
</div></div></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<div class="admonitionblock warning">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-warning" title="Warning"></i>
|
||
</td>
|
||
<td class="content">
|
||
<div class="paragraph">
|
||
<p>The fact that Boost Exception stores all supplied <code>boost::error_info</code> objects — while LEAF discards them if they aren’t needed — affects the completeness of the message we get when we print <code>leaf::<a href="#diagnostic_info">diagnostic_info</a></code> objects, compared to the string returned by <a href="https://www.boost.org/doc/libs/release/libs/exception/doc/diagnostic_information.html"><code>boost::diagnostic_information</code></a>.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>If the user requires a complete diagnostic message, the solution is to use <code>leaf::<a href="#verbose_diagnostic_info">verbose_diagnostic_info</a></code>. In this case, before unused error objects are discarded by LEAF, they are converted to string and printed. Note that this allocates memory dynamically.</p>
|
||
</div>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<hr>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="boost_outcome">Comparison to Boost Outcome</h3>
|
||
<div class="sect3">
|
||
<h4 id="_design_differences">Design Differences</h4>
|
||
<div class="paragraph">
|
||
<p>Like LEAF, the <a href="https://ned14.github.io/outcome">Boost Outcome</a> library is designed to work in low latency environments. It provides two class templates, <code>result<></code> and <code>outcome<></code>:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p><code>result<T,EC,NVP></code> can be used as the return type in <code>noexcept</code> functions which may fail, where <code>T</code> specifies the type of the return value in case of success, while <code>EC</code> is an "error code" type. Semantically, <code>result<T,EC></code> is similar to <code>std::variant<T,EC></code>. Naturally, <code>EC</code> defaults to <code>std::error_code</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>outcome<T,EC,EP,NVP></code> is similar to <code>result<></code>, but in case of failure, in addition to the "error code" type <code>EC</code> it can hold a "pointer" object of type <code>EP</code>, which defaults to <code>std::exception_ptr</code>.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
<code>NVP</code> is a policy type used to customize the behavior of <code>.value()</code> when the <code>result<></code> or the <code>outcome<></code> object contains an error.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The idea is to use <code>result<></code> to communicate failures which can be fully specified by an "error code", and <code>outcome<></code> to communicate failures that require additional information.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Another way to describe this design is that <code>result<></code> is used when it suffices to return an error object of some static type <code>EC</code>, while <code>outcome<></code> can also transport a polymorphic error object, using the pointer type <code>EP</code>.</p>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
In the default configuration of <code>outcome<T></code> the additional information — or the additional polymorphic object — is an exception object held by <code>std::exception_ptr</code>. This targets the use case when an exception thrown by a lower-level library function needs to be transported through some intermediate contexts that are not exception-safe, to a higher-level context able to handle it. LEAF directly supports this use as well, see <a href="#exception_to_result"><code>exception_to_result</code></a>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Similar reasoning drives the design of LEAF as well. The difference is that while both libraries recognize the need to transport "something else" in addition to an "error code", LEAF provides an efficient solution to this problem, while Outcome shifts this burden to the user.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The <code>leaf::result<></code> template deletes both <code>EC</code> and <code>EP</code>, which decouples it from the type of the error objects that are transported in case of a failure. This enables lower-level functions to freely communicate anything and everything they "know" about the failure: error code, even multiple error codes, file names, URLs, port numbers, etc. At the same time, the higher-level error-handling functions control which of this information is needed in a specific client program and which is not. This is ideal, because:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>Authors of lower-level library functions lack context to determine which of the information that is both relevant to the error <em>and</em> naturally available to them needs to be communicated in order for a particular client program to recover from that error;</p>
|
||
</li>
|
||
<li>
|
||
<p>Authors of higher-level error-handling functions can easily and confidently make this determination, which they communicate naturally to LEAF, by simply writing the different error handlers. LEAF will transport the needed error objects while discarding the ones handlers don’t care to use, saving resources.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
The LEAF examples include an adaptation of the program from the <a href="https://ned14.github.io/outcome/tutorial/essential/result/">Boost Outcome <code>result<></code> tutorial</a>. You can <a href="https://github.com/boostorg/leaf/blob/master/examples/print_half.cpp?ts=4">view it on GitHub</a>.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<div class="admonitionblock note">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-note" title="Note"></i>
|
||
</td>
|
||
<td class="content">
|
||
Programs using LEAF for error-handling are not required to use <code>leaf::result<T></code>; for example, it is possible to use <code>outcome::result<T></code> with LEAF.
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</div>
|
||
<div class="sect3">
|
||
<h4 id="interoperability">The Interoperability Problem</h4>
|
||
<div class="paragraph">
|
||
<p>The Boost Outcome documentation discusses the important problem of bringing together multiple libraries — each using its own error reporting mechanism — and incorporating them in a robust error handling infrastructure in a client program.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Users are advised that whenever possible they should use a common error handling system throughout their entire codebase, but because this is not practical, both the <code>result<></code> and the <code>outcome<></code> templates can carry user-defined "payloads".</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The following analysis is from the Boost Outcome documentation:</p>
|
||
</div>
|
||
<div class="exampleblock">
|
||
<div class="content">
|
||
<div class="paragraph">
|
||
<p>If library A uses <code>result<T, libraryA::failure_info></code>, and library B uses <code>result<T, libraryB::error_info></code> 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.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The application writer has one of three choices:</p>
|
||
</div>
|
||
<div class="olist arabic">
|
||
<ol class="arabic">
|
||
<li>
|
||
<p>In the application, the form of result used is <code>result<T, std::variant<E1, E2, …​>></code> where <code>E1, E2 …</code> 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.</p>
|
||
</li>
|
||
<li>
|
||
<p>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.</p>
|
||
</li>
|
||
<li>
|
||
<p>One can type erase the third party’s failure type into some application failure type, which can later be reconstituted if necessary. <strong>This is the cleanest solution with the least coupling issues and no problems with mis-mapping</strong>, but it almost certainly requires the use of <code>malloc</code> which the previous two did not.</p>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>The analysis above (emphasis added) is clear and precise, but LEAF and Boost Outcome tackle the interoperability problem differently:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p>The Boost Outcome design asserts that the "cleanest" solution based on type-erasure is suboptimal ("almost certainly requires the use of <code>malloc</code>"), and instead provides a system for injecting custom converters into the <code>outcome::convert</code> namespace, used to translate between library-specific and program-wide error types, even though this approach "may lose the original failure detail".</p>
|
||
</li>
|
||
<li>
|
||
<p>The LEAF design asserts that coupling the signatures of <a href="#rationale">error-neutral</a> functions with the static types of the error objects they need to forward to the caller <a href="#translation">does not scale</a>, and instead transports error objects directly to error-handling scopes where they are stored statically, effectively implementing the third choice outlined above (without the use of <code>malloc</code>).</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Further, consider that Outcome aims to hopefully become <em>the</em> one error-handling API all libraries would use, and in theory everyone would benefit from uniformity and standardization. But the reality is that this is wishful thinking. In fact, that reality is reflected in the design of <code>outcome::result<></code>, in its lack of commitment to using <code>std::error_code</code> for its intended purpose: to be <em>the</em> standard type for transporting error codes. The fact is that <code>std::error_code</code> became <em>yet another</em> error code type programmers need to understand and support.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>In contrast, the design of LEAF acknowledges that C++ programmers don’t even agree on what a string is. If your project uses 10 different libraries, this probably means 15 different ways to report errors, sometimes across uncooperative interfaces (e.g. C APIs). LEAF helps you get the job done.</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="_benchmark">Benchmark</h2>
|
||
<div class="sectionbody">
|
||
<div class="paragraph">
|
||
<p><a href="https://github.com/boostorg/leaf/blob/master/benchmark/benchmark.md">This benchmark</a> compares the performance of LEAF, Boost Outcome and <code>tl::expected</code>.</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="_running_the_unit_tests">Running the Unit Tests</h2>
|
||
<div class="sectionbody">
|
||
<div class="paragraph">
|
||
<p>The unit tests can be run with <a href="https://mesonbuild.com">Meson Build</a> or with Boost Build. To run the unit tests:</p>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="_meson_build">Meson Build</h3>
|
||
<div class="paragraph">
|
||
<p>Clone LEAF into any local directory and execute:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-sh" data-lang="sh">cd leaf
|
||
meson bld/debug
|
||
cd bld/debug
|
||
meson test</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>See <code>meson_options.txt</code> found in the root directory for available build options.</p>
|
||
</div>
|
||
</div>
|
||
<div class="sect2">
|
||
<h3 id="_boost_build">Boost Build</h3>
|
||
<div class="paragraph">
|
||
<p>Assuming the current working directory is <code><boostroot>/libs/leaf</code>:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-sh" data-lang="sh">../../b2 test</code></pre>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="configuration">Configuration Macros</h2>
|
||
<div class="sectionbody">
|
||
<div class="paragraph">
|
||
<p>The following configuration macros are recognized:</p>
|
||
</div>
|
||
<div class="ulist">
|
||
<ul>
|
||
<li>
|
||
<p><code>BOOST_LEAF_DIAGNOSTICS</code>: Defining this macro to <code>0</code> stubs out both <a href="#diagnostic_info"><code>diagnostic_info</code></a> and <a href="#verbose_diagnostic_info"><code>verbose_diagnostic_info</code></a>, which could improve the performance of the error path in some programs (if the macro is left undefined, LEAF defines it as <code>1</code>).</p>
|
||
</li>
|
||
<li>
|
||
<p><code>BOOST_LEAF_NO_EXCEPTIONS</code>: Disables all exception handling support. If left undefined, LEAF defines it based on the compiler configuration (e.g. <code>-fno-exceptions</code>).</p>
|
||
</li>
|
||
<li>
|
||
<p><code>BOOST_LEAF_NO_THREADS</code>: Disable all multi-thread support.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="_limitations">Limitations</h2>
|
||
<div class="sectionbody">
|
||
<div class="paragraph">
|
||
<p>LEAF requires C++11, including <code>thread_local</code> support, except when compiled with <code>BOOST_LEAF_NO_THREADS</code> (which can be useful on some embedded platforms).</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>When using dynamic linking, it is required that error types are declared with <code>default</code> visibility, e.g.:</p>
|
||
</div>
|
||
<div class="listingblock">
|
||
<div class="content">
|
||
<pre class="highlight nowrap"><code class="language-c++" data-lang="c++">struct __attribute__ ((visibility ("default"))) my_error_info
|
||
{
|
||
int value;
|
||
};</code></pre>
|
||
</div>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>This works as expected except on Windows, where thread-local storage is not shared between the individual binary modules. For this reason, to transport error objects across DLL boundaries, it is required that they’re captured in a <a href="#polymorphic_context"><code>polymorphic_context</code></a>, just like when <a href="#tutorial-async">Transporting Error Objects Between Threads</a>.</p>
|
||
</div>
|
||
<div class="admonitionblock tip">
|
||
<table>
|
||
<tr>
|
||
<td class="icon">
|
||
<i class="fa icon-tip" title="Tip"></i>
|
||
</td>
|
||
<td class="content">
|
||
When using dynamic linking, it is always best to define module interfaces in terms of C (and implement them in C++ if appropriate).
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect1">
|
||
<h2 id="_acknowledgements">Acknowledgements</h2>
|
||
<div class="sectionbody">
|
||
<div class="paragraph">
|
||
<p>Special thanks to Peter Dimov and Sorin Fetche.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Ivo Belchev, Sean Palmer, Jason King, Vinnie Falco, Glen Fernandes, Augustín Bergé — thanks for the valuable feedback.</p>
|
||
</div>
|
||
<div class="paragraph">
|
||
<p>Documentation rendered by <a href="https://asciidoctor.org/">Asciidoctor</a> with <a href="https://github.com/zajo/asciidoctor_skin">these customizations</a>.</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div id="footnotes">
|
||
<hr>
|
||
<div class="footnote" id="_footnotedef_1">
|
||
<a href="#_footnoteref_1">1</a>. <a href="https://herbsutter.com/2007/01/24/questions-about-exception-specifications/" class="bare">https://herbsutter.com/2007/01/24/questions-about-exception-specifications/</a>
|
||
</div>
|
||
</div>
|
||
<div id="footer">
|
||
<div id="footer-text">
|
||
</div>
|
||
</div>
|
||
</body>
|
||
</html> |