mirror of
https://github.com/boostorg/leaf.git
synced 2026-01-19 04:22:08 +00:00
8550 lines
573 KiB
HTML
8550 lines
573 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<meta name="generator" content="Asciidoctor 2.0.26">
|
|
<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">
|
|
<link rel="stylesheet" href="./rouge-github.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="#distribution">Distribution</a></li>
|
|
<li><a href="#tutorial">Tutorial</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_reporting_errors">Reporting Errors</a></li>
|
|
<li><a href="#checking_for_errors">Checking for Errors</a></li>
|
|
<li><a href="#tutorial-error_handling">Error Handling</a></li>
|
|
<li><a href="#_working_with_different_error_types">Working with Different Error Types</a></li>
|
|
<li><a href="#_working_with_multiple_error_objects">Working with Multiple Error Objects</a></li>
|
|
<li><a href="#tutorial-augmenting_errors">Augmenting Errors</a></li>
|
|
<li><a href="#tutorial-exception_handling">Exception Handling</a></li>
|
|
<li><a href="#_using_external_result_types">Using External <code>result</code> Types</a></li>
|
|
<li><a href="#tutorial-interoperability">Interoperability</a></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">Reusing Common Error Handlers</a></li>
|
|
<li><a href="#tutorial-async">Transporting Errors Between Threads</a>
|
|
<ul class="sectlevel3">
|
|
<li><a href="#tutorial-async_result">Transporting Errors Between Threads Without Exception Handling</a></li>
|
|
<li><a href="#tutorial-async_eh">Transporting Errors Between Threads With 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 Errors from C Callbacks</a></li>
|
|
<li><a href="#tutorial-diagnostic_information">Diagnostic Information</a></li>
|
|
<li><a href="#tutorial-serialization">Serialization</a>
|
|
<ul class="sectlevel3">
|
|
<li><a href="#custom-encoders">Custom Encoders</a></li>
|
|
<li><a href="#_json_serialization">JSON Serialization</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#tutorial-std_error_code">Working with <code>std::error_code</code> and <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="#example">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="#common.hpp"><code>common.hpp</code></a></li>
|
|
<li><a href="#error.hpp"><code>error.hpp</code></a></li>
|
|
<li><a href="#exception.hpp"><code>exception.hpp</code></a></li>
|
|
<li><a href="#on_error.hpp"><code>on_error.hpp</code></a></li>
|
|
<li><a href="#result.hpp"><code>result.hpp</code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#synopsis-handling">Error Handling</a>
|
|
<ul class="sectlevel3">
|
|
<li><a href="#context.hpp"><code>context.hpp</code></a></li>
|
|
<li><a href="#diagnostics.hpp"><code>diagnostics.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>
|
|
<li><a href="#to_variant.hpp"><code>to_variant.hpp</code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#synopsis-serialization">Serialization</a>
|
|
<ul class="sectlevel3">
|
|
<li><a href="#json_encoder_boost.hpp"><code>json_encoder_boost.hpp</code></a></li>
|
|
<li><a href="#json_encoder_nlohmann.hpp"><code>json_encoder_nlohmann.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="#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_to_result"><code>exception_to_result</code></a></li>
|
|
<li><a href="#make_context"><code>make_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="#serialize"><code>serialize</code></a></li>
|
|
<li><a href="#throw_exception"><code>throw_exception</code></a></li>
|
|
<li><a href="#to_variant"><code>to_variant</code></a></li>
|
|
<li><a href="#try_capture_all"><code>try_capture_all</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::unload"><code>unload</code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#context_activator"><code>context_activator</code></a></li>
|
|
<li><a href="#diagnostic_details"><code>diagnostic_details</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="#json_encoder_boost"><code>json_encoder_boost</code></a></li>
|
|
<li><a href="#json_encoder_nlohmann"><code>json_encoder_nlohmann</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::has_error"><code>has_error</code></a></li>
|
|
<li><a href="#result::has_value"><code>has_value</code></a></li>
|
|
<li><a href="#result::load"><code>load</code></a></li>
|
|
<li><a href="#result::operator_bool"><code>operator bool</code></a></li>
|
|
<li><a href="#result::operator_deref"><code>operator*</code></a></li>
|
|
<li><a href="#result::operator_eq"><code>operator=</code></a></li>
|
|
<li><a href="#result::operator_ptr"><code>operator-></code></a></li>
|
|
<li><a href="#result::value"><code>value</code></a></li>
|
|
<li><a href="#result::value_type"><code>value_type</code></a></li>
|
|
<li><a href="#result::output_to"><code>output_to</code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#show_in_diagnostics"><code>show_in_diagnostics</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_ASSIGN"><code>BOOST_LEAF_ASSIGN</code></a></li>
|
|
<li><a href="#BOOST_LEAF_AUTO"><code>BOOST_LEAF_AUTO</code></a></li>
|
|
<li><a href="#BOOST_LEAF_CHECK"><code>BOOST_LEAF_CHECK</code></a></li>
|
|
<li><a href="#BOOST_LEAF_THROW_EXCEPTION"><code>BOOST_LEAF_THROW_EXCEPTION</code></a></li>
|
|
<li><a href="#BOOST_LEAF_NEW_ERROR"><code>BOOST_LEAF_NEW_ERROR</code></a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#configuration">Configuration</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#configuring_tls_access">Configuring TLS Access</a></li>
|
|
<li><a href="#embedded_platforms">Embedded Platforms</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#portability">Portability</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="#rationale">Design Rationale</a></li>
|
|
<li><a href="#_dynamic_linking">Dynamic Linking</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#_posix">POSIX</a></li>
|
|
<li><a href="#_windows">Windows</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#_alternatives_to_leaf">Alternatives to LEAF</a>
|
|
<ul class="sectlevel2">
|
|
<li><a href="#std_expected">Comparison to <code>std::expected</code></a></li>
|
|
<li><a href="#boost_outcome">Comparison to Boost Outcome</a>
|
|
<ul class="sectlevel3">
|
|
<li><a href="#interoperability">The Interoperability Problem</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#boost_exception">Comparison to Boost Exception</a></li>
|
|
</ul>
|
|
</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>Portable single-header format, no dependencies.</p>
|
|
</li>
|
|
<li>
|
|
<p>Tiny code size, configurable for embedded development.</p>
|
|
</li>
|
|
<li>
|
|
<p>No dynamic memory allocations, even with very large payloads.</p>
|
|
</li>
|
|
<li>
|
|
<p>Deterministic unbiased efficiency on the "happy" path and the "sad" path.</p>
|
|
</li>
|
|
<li>
|
|
<p>Error objects are handled in constant time, independent of call stack depth.</p>
|
|
</li>
|
|
<li>
|
|
<p>Can be used with or without exception handling.</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="#tutorial">Tutorial</a> | <a href="#synopsis">Synopsis</a> | <a href="https://github.com/boostorg/leaf/blob/master/doc/whitepaper.md">Whitepaper</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>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="support">Support</h2>
|
|
<div class="sectionbody">
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p><a href="https://github.com/boostorg/leaf/issues">Report issues</a> on GitHub</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="distribution">Distribution</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>LEAF is 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), and therefore available via most package managers.</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 latest LEAF release is also available in single-header format: <a href="https://raw.githubusercontent.com/boostorg/leaf/gh-pages/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="tutorial">Tutorial</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>Typically, error handling libraries define a variant result type, e.g. <code>result<T, E></code>. In LEAF we drop the <code>E</code>, using just <code>result<T></code>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In case of success, access to the value <code>T</code> is immediate and direct, and we can easily bail out in case of a failure.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To handle errors, we use a special syntax, which enables error objects to be transported directly to the error handling scopes that need them. This is more efficient than holding them in result types, and it also allows any given handler to access multiple error objects associated with the same failure.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>LEAF is also compatible with exception handling, providing identical functionality but without needing a result type.</p>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_reporting_errors">Reporting Errors</h3>
|
|
<div class="paragraph">
|
|
<p>Let’s introduce the <code>result<T></code>-based interface first.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Report errors with <code>leaf::new_error</code>:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">enum</span> <span class="k">class</span> <span class="nc">api_error</span> <span class="p">{</span> <span class="n">connect_failed</span><span class="p">,</span> <span class="n">invalid_request</span><span class="p">,</span> <span class="n">timeout</span> <span class="p">};</span>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">connection</span><span class="o">></span> <span class="n">connect</span><span class="p">()</span>
|
|
<span class="p">{</span>
|
|
<span class="p">....</span>
|
|
<span class="k">if</span><span class="p">(</span> <span class="o"><<</span><span class="n">connection</span><span class="o">-</span><span class="n">failure</span><span class="o">-</span><span class="n">detected</span><span class="o">>></span> <span class="p">)</span>
|
|
<span class="k">return</span> <span class="n">leaf</span><span class="o">::</span><span class="n">new_error</span><span class="p">(</span> <span class="n">api_error</span><span class="o">::</span><span class="n">connect_failed</span> <span class="p">);</span> <span class="c1">// Pass error objects of any type</span>
|
|
|
|
<span class="c1">// Produce and return a connection object.</span>
|
|
<span class="p">}</span></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></p>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="checking_for_errors">Checking for Errors</h3>
|
|
<div class="paragraph">
|
|
<p>To bail out on failure, return <code>result::error()</code>:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">data</span><span class="o">></span> <span class="n">connect_and_fetch_data</span><span class="p">()</span>
|
|
<span class="p">{</span>
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">connection</span><span class="o">></span> <span class="n">cr</span> <span class="o">=</span> <span class="n">connect</span><span class="p">();</span>
|
|
<span class="k">if</span><span class="p">(</span> <span class="o">!</span><span class="n">cr</span> <span class="p">)</span>
|
|
<span class="k">return</span> <span class="n">cr</span><span class="p">.</span><span class="n">error</span><span class="p">();</span>
|
|
|
|
<span class="n">connection</span> <span class="o">&</span> <span class="n">c</span> <span class="o">=</span> <span class="n">cr</span><span class="p">.</span><span class="n">value</span><span class="p">();</span>
|
|
|
|
<span class="c1">// Use c to fetch and return data</span>
|
|
<span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph text-right">
|
|
<p><a href="#result"><code>result</code></a></p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Use <code>BOOST_LEAF_AUTO</code> to avoid the boilerplate <code>if</code> statement:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">data</span><span class="o">></span> <span class="n">connect_and_fetch_data</span><span class="p">()</span>
|
|
<span class="p">{</span>
|
|
<span class="n">BOOST_LEAF_AUTO</span><span class="p">(</span><span class="n">c</span><span class="p">,</span> <span class="n">connect</span><span class="p">());</span> <span class="c1">// Bail out on error</span>
|
|
|
|
<span class="c1">// Use c to fetch and return data</span>
|
|
<span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph text-right">
|
|
<p><a href="#BOOST_LEAF_AUTO"><code>BOOST_LEAF_AUTO</code></a></p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Use <code>BOOST_LEAF_CHECK</code> in case of <code>void</code> results:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">void</span><span class="o">></span> <span class="n">flush</span><span class="p">(</span><span class="n">connection</span> <span class="o">&</span> <span class="n">c</span><span class="p">);</span>
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="kt">size_t</span><span class="o">></span> <span class="n">bytes_sent</span><span class="p">(</span><span class="n">connection</span> <span class="o">&</span> <span class="n">c</span><span class="p">);</span>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="kt">size_t</span><span class="o">></span> <span class="n">flush_and_get_bytes_sent</span><span class="p">(</span><span class="n">connection</span> <span class="o">&</span> <span class="n">c</span><span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">BOOST_LEAF_CHECK</span><span class="p">(</span><span class="n">flush</span><span class="p">(</span><span class="n">c</span><span class="p">));</span> <span class="c1">// Bail out on error</span>
|
|
<span class="k">return</span> <span class="n">bytes_sent</span><span class="p">(</span><span class="n">c</span><span class="p">);</span>
|
|
<span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph text-right">
|
|
<p><a href="#BOOST_LEAF_CHECK"><code>BOOST_LEAF_CHECK</code></a></p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>On implementations that define <code>__GNUC__</code> (e.g. GCC/clang), <code>BOOST_LEAF_CHECK</code> is compatible with non-<code>void</code> results as well:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="n">count_rows</span><span class="p">();</span>
|
|
|
|
<span class="kt">float</span> <span class="nf">update_average</span><span class="p">(</span><span class="kt">int</span> <span class="n">n</span><span class="p">);</span>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">float</span><span class="o">></span> <span class="n">average_row_count</span><span class="p">()</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">update_average</span><span class="p">(</span> <span class="n">BOOST_LEAF_CHECK</span><span class="p">(</span><span class="n">count_rows</span><span class="p">())</span> <span class="p">);</span>
|
|
<span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The following is the portable alternative:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">float</span><span class="o">></span> <span class="n">average_row_count</span><span class="p">()</span>
|
|
<span class="p">{</span>
|
|
<span class="n">BOOST_LEAF_AUTO</span><span class="p">(</span><span class="n">n</span><span class="p">,</span> <span class="n">count_rows</span><span class="p">());</span>
|
|
<span class="k">return</span> <span class="n">update_average</span><span class="p">(</span><span class="n">n</span><span class="p">);</span>
|
|
<span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="tutorial-error_handling">Error Handling</h3>
|
|
<div class="paragraph">
|
|
<p>Error handling scopes use a special syntax to indicate that they need to access error objects:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">data</span><span class="o">></span> <span class="n">r</span> <span class="o">=</span> <span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_some</span><span class="p">(</span>
|
|
|
|
<span class="p">[]()</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">data</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="n">BOOST_LEAF_AUTO</span><span class="p">(</span><span class="n">c</span><span class="p">,</span> <span class="n">connect</span><span class="p">());</span>
|
|
<span class="k">return</span> <span class="n">fetch</span><span class="p">(</span><span class="n">c</span><span class="p">);</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">api_error</span> <span class="n">e</span> <span class="p">)</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">data</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="k">if</span><span class="p">(</span> <span class="n">e</span> <span class="o">==</span> <span class="n">api_error</span><span class="o">::</span><span class="n">connect_failed</span> <span class="p">)</span>
|
|
<span class="p">....</span> <span class="c1">// Handle api_error::connect_failed</span>
|
|
<span class="k">else</span>
|
|
<span class="p">....</span> <span class="c1">// Handle any other api_error value</span>
|
|
<span class="p">}</span> <span class="p">);</span></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>BOOST_LEAF_AUTO</code></a></p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>First, <code>try_handle_some</code> executes the first function passed to it; it attempts to produce a <code>result<data></code>, but it may fail.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The second lambda is an error handler: it will be called iff the first lambda fails with an error object of type <code>api_error</code>. That object is stored on the stack, local to the <code>try_handle_some</code> function (LEAF knows to allocate this storage because we gave it an error handler that takes an <code>api_error</code>). Error handlers passed to <code>leaf::try_handle_some</code> can return a valid <code>leaf::result</code> but are allowed to fail.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>It is possible for an error handler to declare that it can only handle some specific values of a given error type:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">data</span><span class="o">></span> <span class="n">r</span> <span class="o">=</span> <span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_some</span><span class="p">(</span>
|
|
|
|
<span class="p">[]()</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">data</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="n">BOOST_LEAF_AUTO</span><span class="p">(</span><span class="n">c</span><span class="p">,</span> <span class="n">connect</span><span class="p">());</span>
|
|
<span class="k">return</span> <span class="n">fetch</span><span class="p">(</span><span class="n">c</span><span class="p">);</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">leaf</span><span class="o">::</span><span class="n">match</span><span class="o"><</span><span class="n">api_error</span><span class="p">,</span> <span class="n">api_error</span><span class="o">::</span><span class="n">connect_failed</span><span class="p">,</span> <span class="n">api_error</span><span class="o">::</span><span class="n">timeout</span><span class="o">></span> <span class="p">)</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">data</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="c1">// Handle api_error::connect_failed or api_error::timeout</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">api_error</span> <span class="n">e</span> <span class="p">)</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">data</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="c1">// Handle any other api_error value</span>
|
|
<span class="p">}</span> <span class="p">);</span></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>BOOST_LEAF_AUTO</code></a> | <a href="#match"><code>match</code></a></p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>LEAF considers the provided error handlers in order, and calls the first one for which it is able to supply arguments, based on the error objects currently being communicated. Above:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>The first error handler will be called iff an error object of type <code>api_error</code> is available, and its value is either <code>api_error::connect_failed</code> or <code>api_error::timeout</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p>Otherwise the second error handler will be called iff an error object of type <code>api_error</code> is available, regardless of its value.</p>
|
|
</li>
|
|
<li>
|
|
<p>Otherwise <code>leaf::try_handle_some</code> is unable to handle the error.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>It is possible for an error handler to conditionally leave the failure unhandled:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">data</span><span class="o">></span> <span class="n">r</span> <span class="o">=</span> <span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_some</span><span class="p">(</span>
|
|
|
|
<span class="p">[]()</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">data</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="n">BOOST_LEAF_AUTO</span><span class="p">(</span><span class="n">c</span><span class="p">,</span> <span class="n">connect</span><span class="p">());</span>
|
|
<span class="k">return</span> <span class="n">fetch</span><span class="p">(</span><span class="n">c</span><span class="p">);</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">api_error</span> <span class="n">e</span><span class="p">,</span> <span class="n">leaf</span><span class="o">::</span><span class="n">error_info</span> <span class="k">const</span> <span class="o">&</span> <span class="n">ei</span> <span class="p">)</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">data</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="k">if</span><span class="p">(</span> <span class="n">e</span> <span class="o">==</span> <span class="n">api_error</span><span class="o">::</span><span class="n">timeout</span> <span class="p">)</span>
|
|
<span class="k">return</span> <span class="n">cached_data</span><span class="p">();</span>
|
|
<span class="k">else</span>
|
|
<span class="k">return</span> <span class="n">ei</span><span class="p">.</span><span class="n">error</span><span class="p">();</span>
|
|
<span class="p">}</span> <span class="p">);</span></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>BOOST_LEAF_AUTO</code></a> | <a href="#error_info"><code>error_info</code></a></p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Any error handler can take an argument of type <code>leaf::error_info const &</code> to get access to generic information about the error being handled; in this case we use the <code>error</code> member function, which returns the unique <a href="#error_id"><code>error_id</code></a> of the current error; we use it to initialize the returned <code>leaf::result</code>, effectively propagating the current error out of <code>try_handle_some</code>.</p>
|
|
</div>
|
|
<div class="admonitionblock tip">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<i class="fa icon-tip" title="Tip"></i>
|
|
</td>
|
|
<td class="content">
|
|
If we wanted to signal a new error (rather than propagating the current error), in the <code>return</code> statement we would invoke the <code>leaf::new_error</code> function.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If we want to ensure that all possible failures are handled, we use <code>leaf::try_handle_all</code> instead of <code>leaf::try_handle_some</code>:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">data</span> <span class="n">r</span> <span class="o">=</span> <span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_all</span><span class="p">(</span>
|
|
|
|
<span class="p">[]()</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">data</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="n">BOOST_LEAF_AUTO</span><span class="p">(</span><span class="n">c</span><span class="p">,</span> <span class="n">connect</span><span class="p">());</span>
|
|
<span class="k">return</span> <span class="n">fetch</span><span class="p">(</span><span class="n">c</span><span class="p">);</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">leaf</span><span class="o">::</span><span class="n">match</span><span class="o"><</span><span class="n">api_error</span><span class="p">,</span> <span class="n">api_error</span><span class="o">::</span><span class="n">connect_failed</span><span class="o">></span> <span class="p">)</span> <span class="o">-></span> <span class="n">data</span>
|
|
<span class="p">{</span>
|
|
<span class="c1">// Handle api_error::connect_failed</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">api_error</span> <span class="n">e</span> <span class="p">)</span> <span class="o">-></span> <span class="n">data</span>
|
|
<span class="p">{</span>
|
|
<span class="c1">// Handle any other api_error value</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[]()</span> <span class="o">-></span> <span class="n">data</span>
|
|
<span class="p">{</span>
|
|
<span class="c1">// Handle any other failure</span>
|
|
<span class="p">}</span> <span class="p">);</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph text-right">
|
|
<p><a href="#try_handle_all"><code>try_handle_all</code></a></p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>leaf::try_handle_all</code> function enforces at compile time that at least one of the supplied error handlers takes no arguments (and therefore is able to handle any failure). In addition, all error handlers are forced to return a valid object rather than a <code>leaf::result</code>, so that <code>leaf::try_handle_all</code> is guaranteed to succeed.</p>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_working_with_different_error_types">Working with Different Error Types</h3>
|
|
<div class="paragraph">
|
|
<p>It is of course possible to provide different handlers for different error types:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">enum</span> <span class="k">class</span> <span class="nc">api_error</span> <span class="p">{</span> <span class="n">connect_failed</span><span class="p">,</span> <span class="n">invalid_request</span><span class="p">,</span> <span class="n">timeout</span> <span class="p">};</span>
|
|
<span class="k">enum</span> <span class="k">class</span> <span class="nc">auth_error</span> <span class="p">{</span> <span class="n">unauthorized</span><span class="p">,</span> <span class="n">forbidden</span> <span class="p">};</span>
|
|
|
|
<span class="p">....</span>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">data</span><span class="o">></span> <span class="n">r</span> <span class="o">=</span> <span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_some</span><span class="p">(</span>
|
|
|
|
<span class="p">[]()</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">data</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="n">BOOST_LEAF_AUTO</span><span class="p">(</span><span class="n">c</span><span class="p">,</span> <span class="n">connect</span><span class="p">());</span>
|
|
<span class="k">return</span> <span class="n">fetch</span><span class="p">(</span><span class="n">c</span><span class="p">);</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">api_error</span> <span class="n">e</span> <span class="p">)</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">data</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="c1">// Handle errors of type `api_error`.</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">auth_error</span> <span class="n">e</span> <span class="p">)</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">data</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="c1">// Handle errors of type `auth_error`.</span>
|
|
<span class="p">}</span> <span class="p">);</span></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>BOOST_LEAF_AUTO</code></a></p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Error handlers are always considered in order:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>The first error handler will be used if an error object of type <code>api_error</code> is available;</p>
|
|
</li>
|
|
<li>
|
|
<p>otherwise, the second error handler will be used if an error object of type <code>auth_error</code> is available;</p>
|
|
</li>
|
|
<li>
|
|
<p>otherwise, <code>leaf::try_handle_some</code> fails.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_working_with_multiple_error_objects">Working with Multiple Error Objects</h3>
|
|
<div class="paragraph">
|
|
<p>The <code>leaf::new_error</code> function can be invoked with multiple error objects, for example to communicate an error code and the relevant file name:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">enum</span> <span class="k">class</span> <span class="nc">io_error</span> <span class="p">{</span> <span class="n">open_error</span><span class="p">,</span> <span class="n">read_error</span><span class="p">,</span> <span class="n">write_error</span> <span class="p">};</span>
|
|
|
|
<span class="k">struct</span> <span class="nc">e_file_name</span> <span class="p">{</span> <span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">value</span><span class="p">;</span> <span class="p">};</span>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">File</span><span class="o">></span> <span class="n">open_file</span><span class="p">(</span> <span class="kt">char</span> <span class="k">const</span> <span class="o">*</span> <span class="n">name</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="p">....</span>
|
|
<span class="k">if</span><span class="p">(</span> <span class="n">open_failed</span> <span class="p">)</span>
|
|
<span class="k">return</span> <span class="n">leaf</span><span class="o">::</span><span class="n">new_error</span><span class="p">(</span><span class="n">io_error</span><span class="o">::</span><span class="n">open_error</span><span class="p">,</span> <span class="n">e_file_name</span> <span class="p">{</span><span class="n">name</span><span class="p">});</span>
|
|
<span class="p">....</span>
|
|
<span class="p">}</span></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></p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Similarly, error handlers may take multiple error objects as arguments:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">></span> <span class="n">r</span> <span class="o">=</span> <span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_some</span><span class="p">(</span>
|
|
|
|
<span class="p">[]()</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="n">BOOST_LEAF_AUTO</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="n">open_file</span><span class="p">(</span><span class="n">fn</span><span class="p">));</span>
|
|
<span class="p">....</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">io_error</span> <span class="n">ec</span><span class="p">,</span> <span class="n">e_file_name</span> <span class="n">fn</span> <span class="p">)</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="c1">// Handle I/O errors when a file name is also available.</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">io_error</span> <span class="n">ec</span> <span class="p">)</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="c1">// Handle I/O errors when no file name is available.</span>
|
|
<span class="p">}</span> <span class="p">);</span></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>BOOST_LEAF_AUTO</code></a></p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Once again, error handlers are considered in order:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>The first error handler will be used if an error object of type <code>io_error</code> <em>and</em> an error object of type <code>e_file_name</code> are available;</p>
|
|
</li>
|
|
<li>
|
|
<p>otherwise, the second error handler will be used if an error object of type <code>io_error</code> is available;</p>
|
|
</li>
|
|
<li>
|
|
<p>otherwise, <code>leaf::try_handle_some</code> fails.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>An alternative way to write the above is to provide a single error handler that takes the <code>e_file_name</code> argument as a pointer:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">></span> <span class="n">r</span> <span class="o">=</span> <span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_some</span><span class="p">(</span>
|
|
|
|
<span class="p">[]()</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="n">BOOST_LEAF_AUTO</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="n">open_file</span><span class="p">(</span><span class="n">fn</span><span class="p">));</span>
|
|
<span class="p">....</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">io_error</span> <span class="n">ec</span><span class="p">,</span> <span class="n">e_file_name</span> <span class="k">const</span> <span class="o">*</span> <span class="n">fn</span> <span class="p">)</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="k">if</span><span class="p">(</span> <span class="n">fn</span> <span class="p">)</span>
|
|
<span class="p">....</span> <span class="c1">// Handle I/O errors when a file name is also available.</span>
|
|
<span class="k">else</span>
|
|
<span class="p">....</span> <span class="c1">// Handle I/O errors when no file name is available.</span>
|
|
<span class="p">}</span> <span class="p">);</span></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>BOOST_LEAF_AUTO</code></a></p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>An error handler is never dropped for lack of error objects of types which the handler takes as pointers; in this case LEAF simply passes <code>nullptr</code> for these arguments.</p>
|
|
</div>
|
|
<div class="admonitionblock tip">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<i class="fa icon-tip" title="Tip"></i>
|
|
</td>
|
|
<td class="content">
|
|
When an error handler takes arguments by mutable reference or pointer, changes to their state are preserved when the error is communicated to the caller.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="tutorial-augmenting_errors">Augmenting Errors</h3>
|
|
<div class="paragraph">
|
|
<p>Let’s say we have a function <code>parse_line</code> which could fail due to an <code>io_error</code> or a <code>parse_error</code>:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">enum</span> <span class="k">class</span> <span class="nc">io_error</span> <span class="p">{</span> <span class="n">open_error</span><span class="p">,</span> <span class="n">read_error</span><span class="p">,</span> <span class="n">write_error</span> <span class="p">};</span>
|
|
|
|
<span class="k">enum</span> <span class="k">class</span> <span class="nc">parse_error</span> <span class="p">{</span> <span class="n">bad_syntax</span><span class="p">,</span> <span class="n">bad_range</span> <span class="p">};</span>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="n">parse_line</span><span class="p">(</span> <span class="kt">FILE</span> <span class="o">*</span> <span class="n">f</span> <span class="p">);</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>leaf::on_error</code> function can be used to automatically associate additional error objects with any failure that is "in flight":</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">struct</span> <span class="nc">e_line</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">value</span><span class="p">;</span> <span class="p">};</span>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">void</span><span class="o">></span> <span class="n">process_file</span><span class="p">(</span> <span class="kt">FILE</span> <span class="o">*</span> <span class="n">f</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="k">for</span><span class="p">(</span> <span class="kt">int</span> <span class="n">current_line</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span> <span class="n">current_line</span> <span class="o">!=</span> <span class="mi">10</span><span class="p">;</span> <span class="o">++</span><span class="n">current_line</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="k">auto</span> <span class="n">load</span> <span class="o">=</span> <span class="n">leaf</span><span class="o">::</span><span class="n">on_error</span><span class="p">(</span> <span class="n">e_line</span> <span class="p">{</span><span class="n">current_line</span><span class="p">}</span> <span class="p">);</span>
|
|
|
|
<span class="n">BOOST_LEAF_AUTO</span><span class="p">(</span><span class="n">v</span><span class="p">,</span> <span class="n">parse_line</span><span class="p">(</span><span class="n">f</span><span class="p">));</span>
|
|
|
|
<span class="c1">// use v</span>
|
|
<span class="p">}</span>
|
|
<span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph text-right">
|
|
<p><a href="#on_error"><code>on_error</code></a> | <a href="#BOOST_LEAF_AUTO"><code>BOOST_LEAF_AUTO</code></a></p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Because <code>process_file</code> does not handle errors, it remains neutral to failures, except to attach the <code>current_line</code> if something goes wrong. The object returned by <code>on_error</code> holds a copy of <code>current_line</code> wrapped in <code>struct e_line</code>. If <code>parse_line</code> succeeds, the <code>e_line</code> object is simply discarded; if it fails, the <code>e_line</code> object will be automatically "attached" to the failure.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Such failures can then be handled like so:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">void</span><span class="o">></span> <span class="n">r</span> <span class="o">=</span> <span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_some</span><span class="p">(</span>
|
|
|
|
<span class="p">[</span><span class="o">&</span><span class="p">]()</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">void</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="n">BOOST_LEAF_CHECK</span><span class="p">(</span> <span class="n">process_file</span><span class="p">(</span><span class="n">f</span><span class="p">)</span> <span class="p">);</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">parse_error</span> <span class="n">e</span><span class="p">,</span> <span class="n">e_line</span> <span class="n">current_line</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"Parse error at line "</span> <span class="o"><<</span> <span class="n">current_line</span><span class="p">.</span><span class="n">value</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">io_error</span> <span class="n">e</span><span class="p">,</span> <span class="n">e_line</span> <span class="n">current_line</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"I/O error at line "</span> <span class="o"><<</span> <span class="n">current_line</span><span class="p">.</span><span class="n">value</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">io_error</span> <span class="n">e</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"I/O error"</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
|
|
<span class="p">}</span> <span class="p">);</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph text-right">
|
|
<p><a href="#try_handle_some"><code>try_handle_some</code></a> | <a href="#BOOST_LEAF_CHECK"><code>BOOST_LEAF_CHECK</code></a></p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The following is equivalent, and perhaps simpler:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">void</span><span class="o">></span> <span class="n">r</span> <span class="o">=</span> <span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_some</span><span class="p">(</span>
|
|
|
|
<span class="p">[]()</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">void</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="n">BOOST_LEAF_CHECK</span><span class="p">(</span> <span class="n">process_file</span><span class="p">(</span><span class="n">f</span><span class="p">)</span> <span class="p">);</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">parse_error</span> <span class="n">e</span><span class="p">,</span> <span class="n">e_line</span> <span class="n">current_line</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"Parse error at line "</span> <span class="o"><<</span> <span class="n">current_line</span><span class="p">.</span><span class="n">value</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">io_error</span> <span class="n">e</span><span class="p">,</span> <span class="n">e_line</span> <span class="k">const</span> <span class="o">*</span> <span class="n">current_line</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"I/O error"</span><span class="p">;</span>
|
|
<span class="k">if</span><span class="p">(</span> <span class="n">current_line</span> <span class="p">)</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">" at line "</span> <span class="o"><<</span> <span class="n">current_line</span><span class="o">-></span><span class="n">value</span><span class="p">;</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
|
|
<span class="p">}</span> <span class="p">);</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="tutorial-exception_handling">Exception Handling</h3>
|
|
<div class="paragraph">
|
|
<p>What happens if an operation throws an exception? Both <code>try_handle_some</code> and <code>try_handle_all</code> catch exceptions and are able to pass them to any compatible error handler:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">void</span><span class="o">></span> <span class="n">r</span> <span class="o">=</span> <span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_some</span><span class="p">(</span>
|
|
|
|
<span class="p">[]()</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">void</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="n">BOOST_LEAF_CHECK</span><span class="p">(</span> <span class="n">process_file</span><span class="p">(</span><span class="n">f</span><span class="p">)</span> <span class="p">);</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">std</span><span class="o">::</span><span class="n">bad_alloc</span> <span class="k">const</span> <span class="o">&</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"Out of memory!"</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">parse_error</span> <span class="n">e</span><span class="p">,</span> <span class="n">e_line</span> <span class="n">l</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"Parse error at line "</span> <span class="o"><<</span> <span class="n">l</span><span class="p">.</span><span class="n">value</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">io_error</span> <span class="n">e</span><span class="p">,</span> <span class="n">e_line</span> <span class="k">const</span> <span class="o">*</span> <span class="n">l</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"I/O error"</span><span class="p">;</span>
|
|
<span class="k">if</span><span class="p">(</span> <span class="n">l</span> <span class="p">)</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">" at line "</span> <span class="o"><<</span> <span class="n">l</span><span class="p">.</span><span class="n">value</span><span class="p">;</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
|
|
<span class="p">}</span> <span class="p">);</span></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_CHECK"><code>BOOST_LEAF_CHECK</code></a></p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Above, we have simply added an error handler that takes a <code>std::bad_alloc</code>, and everything "just works" as expected: LEAF will dispatch error handlers correctly no matter if failures are communicated via <code>leaf::result</code> or by an exception.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Of course, if we use exception handling exclusively, we do not need <code>leaf::result</code> at all. In this case we use <code>leaf::try_catch</code>:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">leaf</span><span class="o">::</span><span class="n">try_catch</span><span class="p">(</span>
|
|
|
|
<span class="p">[]</span>
|
|
<span class="p">{</span>
|
|
<span class="n">process_file</span><span class="p">(</span><span class="n">f</span><span class="p">);</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">std</span><span class="o">::</span><span class="n">bad_alloc</span> <span class="k">const</span> <span class="o">&</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"Out of memory!"</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">parse_error</span> <span class="n">e</span><span class="p">,</span> <span class="n">e_line</span> <span class="n">l</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"Parse error at line "</span> <span class="o"><<</span> <span class="n">l</span><span class="p">.</span><span class="n">value</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">io_error</span> <span class="n">e</span><span class="p">,</span> <span class="n">e_line</span> <span class="k">const</span> <span class="o">*</span> <span class="n">l</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"I/O error"</span><span class="p">;</span>
|
|
<span class="k">if</span><span class="p">(</span> <span class="n">l</span> <span class="p">)</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">" at line "</span> <span class="o"><<</span> <span class="n">l</span><span class="p">.</span><span class="n">value</span><span class="p">;</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
|
|
<span class="p">}</span> <span class="p">);</span></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>We did not have to change the error handlers! But how does this work? What kind of exceptions would <code>process_file</code> throw?</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>LEAF enables a novel exception handling technique, which does not require an exception type hierarchy to classify failures and does not carry data in exception objects. Recall that when failures are communicated via <code>leaf::result</code>, we call <code>leaf::new_error</code> in a <code>return</code> statement, passing any number of error objects which are sent directly to the correct error handling scope:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">enum</span> <span class="k">class</span> <span class="nc">api_error</span> <span class="p">{</span> <span class="n">connect_failed</span><span class="p">,</span> <span class="n">invalid_request</span><span class="p">,</span> <span class="n">timeout</span> <span class="p">};</span>
|
|
<span class="k">enum</span> <span class="k">class</span> <span class="nc">auth_error</span> <span class="p">{</span> <span class="n">unauthorized</span><span class="p">,</span> <span class="n">forbidden</span> <span class="p">};</span>
|
|
|
|
<span class="p">....</span>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">></span> <span class="n">f</span><span class="p">()</span>
|
|
<span class="p">{</span>
|
|
<span class="p">....</span>
|
|
<span class="k">if</span><span class="p">(</span> <span class="n">error_detected</span> <span class="p">)</span>
|
|
<span class="k">return</span> <span class="n">leaf</span><span class="o">::</span><span class="n">new_error</span><span class="p">(</span><span class="n">api_error</span><span class="o">::</span><span class="n">connect_failed</span><span class="p">,</span> <span class="n">auth_error</span><span class="o">::</span><span class="n">forbidden</span><span class="p">);</span>
|
|
|
|
<span class="c1">// Produce and return a T.</span>
|
|
<span class="p">}</span></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></p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>When using exception handling this becomes:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">enum</span> <span class="k">class</span> <span class="nc">api_error</span> <span class="p">{</span> <span class="n">connect_failed</span><span class="p">,</span> <span class="n">invalid_request</span><span class="p">,</span> <span class="n">timeout</span> <span class="p">};</span>
|
|
<span class="k">enum</span> <span class="k">class</span> <span class="nc">auth_error</span> <span class="p">{</span> <span class="n">unauthorized</span><span class="p">,</span> <span class="n">forbidden</span> <span class="p">};</span>
|
|
|
|
<span class="n">T</span> <span class="nf">f</span><span class="p">()</span>
|
|
<span class="p">{</span>
|
|
<span class="k">if</span><span class="p">(</span> <span class="n">error_detected</span> <span class="p">)</span>
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">throw_exception</span><span class="p">(</span><span class="n">api_error</span><span class="o">::</span><span class="n">connect_failed</span><span class="p">,</span> <span class="n">auth_error</span><span class="o">::</span><span class="n">forbidden</span><span class="p">);</span>
|
|
|
|
<span class="c1">// Produce and return a T.</span>
|
|
<span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph text-right">
|
|
<p><a href="#throw_exception"><code>throw_exception</code></a></p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>leaf::throw_exception</code> function handles the passed error objects just like <code>leaf::new_error</code> does, and then throws an object of a type that derives from <code>std::exception</code>. Using this technique, the exception type is not important: <code>leaf::try_catch</code> catches all exceptions, then goes through the usual LEAF error handler selection routine.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If instead we want to use the standard convention of throwing different types to indicate different failures, we simply pass an exception object (that is, an object of a type that derives from <code>std::exception</code>) as the first argument to <code>leaf::throw_exception</code>:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">leaf</span><span class="o">::</span><span class="n">throw_exception</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">runtime_error</span><span class="p">(</span><span class="s">"Error!"</span><span class="p">),</span> <span class="n">api_error</span><span class="o">::</span><span class="n">connect_failed</span><span class="p">,</span> <span class="n">auth_error</span><span class="o">::</span><span class="n">forbidden</span><span class="p">);</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In this case the thrown exception object will be of a type that derives from <code>std::runtime_error</code>, rather than from <code>std::exception</code>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Finally, <code>leaf::on_error</code> "just works" as well. Here is our <code>process_file</code> function rewritten to work with exceptions, rather than return a <code>leaf::result</code> (see <a href="#tutorial-augmenting_errors">Augmenting Errors</a>):</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="kt">int</span> <span class="nf">parse_line</span><span class="p">(</span> <span class="kt">FILE</span> <span class="o">*</span> <span class="n">f</span> <span class="p">);</span> <span class="c1">// Throws</span>
|
|
|
|
<span class="k">struct</span> <span class="nc">e_line</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">value</span><span class="p">;</span> <span class="p">};</span>
|
|
|
|
<span class="kt">void</span> <span class="nf">process_file</span><span class="p">(</span> <span class="kt">FILE</span> <span class="o">*</span> <span class="n">f</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="k">for</span><span class="p">(</span> <span class="kt">int</span> <span class="n">current_line</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span> <span class="n">current_line</span> <span class="o">!=</span> <span class="mi">10</span><span class="p">;</span> <span class="o">++</span><span class="n">current_line</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="k">auto</span> <span class="n">load</span> <span class="o">=</span> <span class="n">leaf</span><span class="o">::</span><span class="n">on_error</span><span class="p">(</span> <span class="n">e_line</span> <span class="p">{</span><span class="n">current_line</span><span class="p">}</span> <span class="p">);</span>
|
|
<span class="kt">int</span> <span class="n">v</span> <span class="o">=</span> <span class="n">parse_line</span><span class="p">(</span><span class="n">f</span><span class="p">);</span>
|
|
|
|
<span class="c1">// use v</span>
|
|
<span class="p">}</span>
|
|
<span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph text-right">
|
|
<p><a href="#on_error"><code>on_error</code></a></p>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_using_external_result_types">Using External <code>result</code> Types</h3>
|
|
<div class="paragraph">
|
|
<p>Static type checking creates difficulties in error handling interoperability in any non-trivial project. Using exception handling alleviates this problem somewhat because in that case error types are not burned into function signatures, so errors easily punch through multiple layers of APIs; but this doesn’t help C++ in general because the community is fractured on the issue of exception handling. That debate notwithstanding, the reality is that C++ programs need to handle errors communicated through multiple layers of APIs via a plethora of error codes, <code>result</code> types and exceptions.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>LEAF enables application developers to shake error objects out of each individual library’s <code>result</code> type and send them to error handling scopes verbatim. Here is an example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">lib1</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">int</span><span class="p">,</span> <span class="n">lib1</span><span class="o">::</span><span class="n">error_code</span><span class="o">></span> <span class="n">foo</span><span class="p">();</span>
|
|
<span class="n">lib2</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">int</span><span class="p">,</span> <span class="n">lib2</span><span class="o">::</span><span class="n">error_code</span><span class="o">></span> <span class="n">bar</span><span class="p">();</span>
|
|
|
|
<span class="kt">int</span> <span class="nf">g</span><span class="p">(</span> <span class="kt">int</span> <span class="n">a</span><span class="p">,</span> <span class="kt">int</span> <span class="n">b</span> <span class="p">);</span>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="n">f</span><span class="p">()</span>
|
|
<span class="p">{</span>
|
|
<span class="k">auto</span> <span class="n">a</span> <span class="o">=</span> <span class="n">foo</span><span class="p">();</span>
|
|
<span class="k">if</span><span class="p">(</span> <span class="o">!</span><span class="n">a</span> <span class="p">)</span>
|
|
<span class="k">return</span> <span class="n">leaf</span><span class="o">::</span><span class="n">new_error</span><span class="p">(</span> <span class="n">a</span><span class="p">.</span><span class="n">error</span><span class="p">()</span> <span class="p">);</span>
|
|
|
|
<span class="k">auto</span> <span class="n">b</span> <span class="o">=</span> <span class="n">bar</span><span class="p">();</span>
|
|
<span class="k">if</span><span class="p">(</span> <span class="o">!</span><span class="n">b</span> <span class="p">)</span>
|
|
<span class="k">return</span> <span class="n">leaf</span><span class="o">::</span><span class="n">new_error</span><span class="p">(</span> <span class="n">b</span><span class="p">.</span><span class="n">error</span><span class="p">()</span> <span class="p">);</span>
|
|
|
|
<span class="k">return</span> <span class="n">g</span><span class="p">(</span> <span class="n">a</span><span class="p">.</span><span class="n">value</span><span class="p">(),</span> <span class="n">b</span><span class="p">.</span><span class="n">value</span><span class="p">()</span> <span class="p">);</span>
|
|
<span class="p">}</span></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></p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Later we simply call <code>leaf::try_handle_some</code>, passing an error handler for each type:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="n">r</span> <span class="o">=</span> <span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_some</span><span class="p">(</span>
|
|
|
|
<span class="p">[]()</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">int</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">f</span><span class="p">();</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">lib1</span><span class="o">::</span><span class="n">error_code</span> <span class="n">ec</span> <span class="p">)</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">int</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="c1">// Handle lib1::error_code</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">lib2</span><span class="o">::</span><span class="n">error_code</span> <span class="n">ec</span> <span class="p">)</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">int</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="c1">// Handle lib2::error_code</span>
|
|
<span class="p">}</span> <span class="p">);</span></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></p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>A possible complication is that we might not have the option to return <code>leaf::result<int></code> from <code>f</code>: a third party API may impose a specific signature on it, forcing it to return a library-specific <code>result</code> type. This would be the case when <code>f</code> is intended to be used as a callback:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="kt">void</span> <span class="nf">register_callback</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">function</span><span class="o"><</span><span class="n">lib3</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">int</span><span class="o">></span><span class="p">()</span><span class="o">></span> <span class="k">const</span> <span class="o">&</span> <span class="n">callback</span> <span class="p">);</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Can we use LEAF in this case? Actually we can, as long as <code>lib3::result</code> is able to communicate a <code>std::error_code</code>. We just have to let LEAF know, by specializing the <code>is_result_type</code> template:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">is_result_type</span><span class="o"><</span><span class="n">lib3</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">>>:</span> <span class="n">std</span><span class="o">::</span><span class="n">true_type</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph text-right">
|
|
<p><a href="#is_result_type"><code>is_result_type</code></a></p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>With this in place, <code>f</code> works as before, even though <code>lib3::result</code> isn’t capable of transporting <code>lib1</code> errors or <code>lib2</code> errors:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">lib1</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">int</span><span class="p">,</span> <span class="n">lib1</span><span class="o">::</span><span class="n">error_type</span><span class="o">></span> <span class="n">foo</span><span class="p">();</span>
|
|
<span class="n">lib2</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">int</span><span class="p">,</span> <span class="n">lib2</span><span class="o">::</span><span class="n">error_type</span><span class="o">></span> <span class="n">bar</span><span class="p">();</span>
|
|
|
|
<span class="kt">int</span> <span class="nf">g</span><span class="p">(</span> <span class="kt">int</span> <span class="n">a</span><span class="p">,</span> <span class="kt">int</span> <span class="n">b</span> <span class="p">);</span>
|
|
|
|
<span class="n">lib3</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="n">f</span><span class="p">()</span> <span class="c1">// Note: return type is not leaf::result<int></span>
|
|
<span class="p">{</span>
|
|
<span class="k">auto</span> <span class="n">a</span> <span class="o">=</span> <span class="n">foo</span><span class="p">();</span>
|
|
<span class="k">if</span><span class="p">(</span> <span class="o">!</span><span class="n">a</span> <span class="p">)</span>
|
|
<span class="k">return</span> <span class="n">leaf</span><span class="o">::</span><span class="n">new_error</span><span class="p">(</span> <span class="n">a</span><span class="p">.</span><span class="n">error</span><span class="p">()</span> <span class="p">);</span>
|
|
|
|
<span class="k">auto</span> <span class="n">b</span> <span class="o">=</span> <span class="n">bar</span><span class="p">();</span>
|
|
<span class="k">if</span><span class="p">(</span> <span class="o">!</span><span class="n">b</span> <span class="p">)</span>
|
|
<span class="k">return</span> <span class="n">leaf</span><span class="o">::</span><span class="n">new_error</span><span class="p">(</span> <span class="n">b</span><span class="p">.</span><span class="n">error</span><span class="p">()</span> <span class="p">);</span>
|
|
|
|
<span class="k">return</span> <span class="n">g</span><span class="p">(</span> <span class="n">a</span><span class="p">.</span><span class="n">value</span><span class="p">(),</span> <span class="n">b</span><span class="p">.</span><span class="n">value</span><span class="p">()</span> <span class="p">);</span>
|
|
<span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph text-right">
|
|
<p><a href="#new_error"><code>new_error</code></a></p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The object returned by <code>leaf::new_error</code> converts implicitly to <code>std::error_code</code>, using a LEAF-specific <code>error_category</code>, which makes <code>lib3::result</code> compatible with <code>leaf::try_handle_some</code> (and with <code>leaf::try_handle_all</code>):</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">lib3</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="n">r</span> <span class="o">=</span> <span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_some</span><span class="p">(</span>
|
|
|
|
<span class="p">[]()</span> <span class="o">-></span> <span class="n">lib3</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">int</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">f</span><span class="p">();</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">lib1</span><span class="o">::</span><span class="n">error_code</span> <span class="n">ec</span> <span class="p">)</span> <span class="o">-></span> <span class="n">lib3</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">int</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="c1">// Handle lib1::error_code</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">lib2</span><span class="o">::</span><span class="n">error_code</span> <span class="n">ec</span> <span class="p">)</span> <span class="o">-></span> <span class="n">lib3</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">int</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="c1">// Handle lib2::error_code</span>
|
|
<span class="p">}</span> <span class="p">);</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph text-right">
|
|
<p><a href="#try_handle_some"><code>try_handle_some</code></a></p>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="tutorial-interoperability">Interoperability</h3>
|
|
<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, an error ID may be encoded in a <code>std::error_code</code>. As long as a 3rd-party interface is able to transport a <code>std::error_code</code>, it can 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 low 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="paragraph">
|
|
<p>For a detailed tutorial see <a href="#tutorial-on_error_in_c_callbacks">Using <code>error_monitor</code> to Report Errors from C Callbacks</a>.</p>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="tutorial-loading">Loading of Error Objects</h3>
|
|
<div class="paragraph">
|
|
<p>Recall that error objects communicated to LEAF are stored on the stack, local to the <code>try_handle_some</code>, <code>try_handle_all</code> or <code>try_catch</code> function used to handle errors. To <em>load</em> an error object means to move it into such storage, if 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="rouge highlight nowrap"><code data-lang="c++"><span class="k">return</span> <span class="n">leaf</span><span class="o">::</span><span class="n">new_error</span><span class="p">(</span><span class="n">ec</span><span class="p">,</span> <span class="n">e_input_name</span><span class="p">{</span><span class="n">n1</span><span class="p">},</span> <span class="n">e_output_name</span><span class="p">{</span><span class="n">n2</span><span class="p">});</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="n">f</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">void</span><span class="o">></span> <span class="n">g</span><span class="p">(</span> <span class="kt">char</span> <span class="k">const</span> <span class="o">*</span> <span class="n">fn</span> <span class="p">)</span> <span class="k">noexcept</span>
|
|
<span class="p">{</span>
|
|
<span class="k">if</span><span class="p">(</span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="n">r</span> <span class="o">=</span> <span class="n">f</span><span class="p">()</span> <span class="p">)</span>
|
|
<span class="p">{</span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
<span class="p">....;</span>
|
|
<span class="k">return</span> <span class="p">{</span> <span class="p">};</span>
|
|
<span class="p">}</span>
|
|
<span class="k">else</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">r</span><span class="p">.</span><span class="n">load</span><span class="p">(</span> <span class="n">e_file_name</span><span class="p">{</span><span class="n">fn</span><span class="p">}</span> <span class="p">);</span> <i class="conum" data-value="2"></i><b>(2)</b>
|
|
<span class="p">}</span>
|
|
<span class="p">}</span></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 used by an error handler, it will be discarded. If instead of an error object we pass a function that returns an error object, that function will only be called if the object it returns is needed, that is, if it will not be discarded. This is helpful when the error object is relatively expensive to produce:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">struct</span> <span class="nc">info</span> <span class="p">{</span> <span class="p">....</span> <span class="p">};</span>
|
|
|
|
<span class="n">info</span> <span class="n">compute_info</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">void</span><span class="o">></span> <span class="n">operation</span><span class="p">(</span> <span class="kt">char</span> <span class="k">const</span> <span class="o">*</span> <span class="n">file_name</span> <span class="p">)</span> <span class="k">noexcept</span>
|
|
<span class="p">{</span>
|
|
<span class="k">if</span><span class="p">(</span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="n">r</span> <span class="o">=</span> <span class="n">try_something</span><span class="p">()</span> <span class="p">)</span>
|
|
<span class="p">{</span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
<span class="p">....</span>
|
|
<span class="k">return</span> <span class="p">{</span> <span class="p">};</span>
|
|
<span class="p">}</span>
|
|
<span class="k">else</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">r</span><span class="p">.</span><span class="n">load</span><span class="p">(</span> <i class="conum" data-value="2"></i><b>(2)</b>
|
|
<span class="p">[</span><span class="o">&</span><span class="p">]</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">compute_info</span><span class="p">();</span>
|
|
<span class="p">}</span> <span class="p">);</span>
|
|
<span class="p">}</span>
|
|
<span class="p">}</span></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 in the call stack 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 some reference 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="rouge highlight nowrap"><code data-lang="c++"><span class="k">struct</span> <span class="nc">e_relevant_file_names</span>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">></span> <span class="n">value</span><span class="p">;</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">void</span><span class="o">></span> <span class="n">operation</span><span class="p">(</span> <span class="kt">char</span> <span class="k">const</span> <span class="o">*</span> <span class="n">file_name</span> <span class="p">)</span> <span class="k">noexcept</span>
|
|
<span class="p">{</span>
|
|
<span class="k">if</span><span class="p">(</span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="n">r</span> <span class="o">=</span> <span class="n">try_something</span><span class="p">()</span> <span class="p">)</span>
|
|
<span class="p">{</span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
<span class="p">....</span>
|
|
<span class="k">return</span> <span class="p">{</span> <span class="p">};</span>
|
|
<span class="p">}</span>
|
|
<span class="k">else</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">r</span><span class="p">.</span><span class="n">load</span><span class="p">(</span> <i class="conum" data-value="2"></i><b>(2)</b>
|
|
<span class="p">[</span><span class="o">&</span><span class="p">](</span><span class="n">e_relevant_file_names</span> <span class="o">&</span> <span class="n">e</span><span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">e</span><span class="p">.</span><span class="n">value</span><span class="p">.</span><span class="n">push_back</span><span class="p">(</span><span class="n">file_name</span><span class="p">);</span>
|
|
<span class="p">}</span> <span class="p">);</span>
|
|
<span class="p">}</span>
|
|
<span class="p">}</span></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> 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>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="rouge highlight nowrap"><code data-lang="c++"><span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">info</span><span class="o">></span> <span class="n">parse_info</span><span class="p">(</span> <span class="kt">FILE</span> <span class="o">*</span> <span class="n">f</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">info</span><span class="o">></span> <span class="n">parse_file</span><span class="p">(</span> <span class="kt">char</span> <span class="k">const</span> <span class="o">*</span> <span class="n">file_name</span> <span class="p">)</span> <span class="k">noexcept</span>
|
|
<span class="p">{</span>
|
|
<span class="k">auto</span> <span class="n">load</span> <span class="o">=</span> <span class="n">leaf</span><span class="o">::</span><span class="n">on_error</span><span class="p">(</span><span class="n">leaf</span><span class="o">::</span><span class="n">e_file_name</span><span class="p">{</span><span class="n">file_name</span><span class="p">});</span> <i class="conum" data-value="2"></i><b>(2)</b>
|
|
|
|
<span class="k">if</span><span class="p">(</span> <span class="kt">FILE</span> <span class="o">*</span> <span class="n">f</span> <span class="o">=</span> <span class="n">fopen</span><span class="p">(</span><span class="n">file_name</span><span class="p">,</span><span class="s">"r"</span><span class="p">)</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="k">auto</span> <span class="n">r</span> <span class="o">=</span> <span class="n">parse_info</span><span class="p">(</span><span class="n">f</span><span class="p">);</span>
|
|
<span class="n">fclose</span><span class="p">(</span><span class="n">f</span><span class="p">);</span>
|
|
<span class="k">return</span> <span class="n">r</span><span class="p">;</span>
|
|
<span class="p">}</span>
|
|
<span class="k">else</span>
|
|
<span class="k">return</span> <span class="n">leaf</span><span class="o">::</span><span class="n">new_error</span><span class="p">(</span> <span class="n">error_enum</span><span class="o">::</span><span class="n">file_open_error</span> <span class="p">);</span>
|
|
<span class="p">}</span></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> communicates errors using <code>leaf::result</code>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
|
<td><code>on_error</code> ensures that the file name is included with any error reported out of <code>parse_file</code>. When the <code>load</code> object 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>new_error</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 a single error object by mutable reference.</p>
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>For example, if we want to use <code>on_error</code> to capture <code>errno</code>, we could use the <a href="#e_errno"><code>e_errno</code></a> type, which is a simple struct that wraps an <code>int</code>. But, we can’t just pass an <a href="#e_errno"><code>e_errno</code></a> to <code>on_error</code>, because at that time <code>errno</code> hasn’t been set (yet). Instead, we’d pass a function that returns it:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="kt">void</span> <span class="nf">read_file</span><span class="p">(</span><span class="kt">FILE</span> <span class="o">*</span> <span class="n">f</span><span class="p">)</span> <span class="p">{</span>
|
|
|
|
<span class="k">auto</span> <span class="n">load</span> <span class="o">=</span> <span class="n">leaf</span><span class="o">::</span><span class="n">on_error</span><span class="p">([]{</span> <span class="k">return</span> <span class="n">leaf</span><span class="o">::</span><span class="n">e_errno</span><span class="p">{</span><span class="n">errno</span><span class="p">};</span> <span class="p">});</span>
|
|
|
|
<span class="p">....</span>
|
|
<span class="kt">size_t</span> <span class="n">nr1</span><span class="o">=</span><span class="n">fread</span><span class="p">(</span><span class="n">buf1</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="n">count1</span><span class="p">,</span><span class="n">f</span><span class="p">);</span>
|
|
<span class="k">if</span><span class="p">(</span> <span class="n">ferror</span><span class="p">(</span><span class="n">f</span><span class="p">)</span> <span class="p">)</span>
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">throw_exception</span><span class="p">();</span>
|
|
|
|
<span class="kt">size_t</span> <span class="n">nr2</span><span class="o">=</span><span class="n">fread</span><span class="p">(</span><span class="n">buf2</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="n">count2</span><span class="p">,</span><span class="n">f</span><span class="p">);</span>
|
|
<span class="k">if</span><span class="p">(</span> <span class="n">ferror</span><span class="p">(</span><span class="n">f</span><span class="p">)</span> <span class="p">)</span>
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">throw_exception</span><span class="p">();</span>
|
|
|
|
<span class="kt">size_t</span> <span class="n">nr3</span><span class="o">=</span><span class="n">fread</span><span class="p">(</span><span class="n">buf3</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="n">count3</span><span class="p">,</span><span class="n">f</span><span class="p">);</span>
|
|
<span class="k">if</span><span class="p">(</span> <span class="n">ferror</span><span class="p">(</span><span class="n">f</span><span class="p">)</span> <span class="p">)</span>
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">throw_exception</span><span class="p">();</span>
|
|
<span class="p">....</span>
|
|
<span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Above, if an exception is thrown, 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>Finally, if <code>on_error</code> is passed a function that takes a single error object by mutable reference, the behavior is similar to how such functions are handled 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, the compatibility between error handlers and the available error objects is determined based on the type of the arguments they take. 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="rouge highlight nowrap"><code data-lang="c++"><span class="k">enum</span> <span class="k">class</span> <span class="nc">validation_error</span>
|
|
<span class="p">{</span>
|
|
<span class="n">empty_field</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span>
|
|
<span class="n">invalid_format</span><span class="p">,</span>
|
|
<span class="n">out_of_range</span>
|
|
<span class="p">};</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>We could handle <code>validation_error</code> errors like so:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">return</span> <span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_some</span><span class="p">(</span>
|
|
|
|
<span class="p">[]</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">validate_input</span><span class="p">();</span> <span class="c1">// Returns leaf::result<input></span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">validation_error</span> <span class="n">e</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="k">switch</span><span class="p">(</span><span class="n">e</span><span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="k">case</span> <span class="n">validation_error</span><span class="o">::</span><span class="n">empty_field</span><span class="p">:</span>
|
|
<span class="p">....;</span> <span class="c1">// Handle empty_field errors</span>
|
|
<span class="k">break</span><span class="p">;</span>
|
|
<span class="k">case</span> <span class="n">validation_error</span><span class="o">::</span><span class="n">invalid_format</span><span class="p">:</span>
|
|
<span class="k">case</span> <span class="n">validation_error</span><span class="o">::</span><span class="n">out_of_range</span><span class="p">:</span>
|
|
<span class="p">....;</span> <span class="c1">// Handle invalid_format and out_of_range errors</span>
|
|
<span class="k">break</span><span class="p">;</span>
|
|
<span class="nl">default:</span>
|
|
<span class="p">....;</span> <span class="c1">// Handle unexpected validation_error values</span>
|
|
<span class="k">break</span><span class="p">;</span>
|
|
<span class="p">}</span>
|
|
<span class="p">}</span> <span class="p">);</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If a <code>validation_error</code> object is available, LEAF will call our error handler. If not, the failure will be forwarded to the 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="rouge highlight nowrap"><code data-lang="c++"><span class="k">return</span> <span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_some</span><span class="p">(</span>
|
|
|
|
<span class="p">[]</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">validate_input</span><span class="p">();</span> <span class="c1">// Returns leaf::result<input></span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">leaf</span><span class="o">::</span><span class="n">match</span><span class="o"><</span><span class="n">validation_error</span><span class="p">,</span> <span class="n">validation_error</span><span class="o">::</span><span class="n">empty_field</span><span class="o">></span> <span class="n">m</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">assert</span><span class="p">(</span><span class="n">m</span><span class="p">.</span><span class="n">matched</span> <span class="o">==</span> <span class="n">validation_error</span><span class="o">::</span><span class="n">empty_field</span><span class="p">);</span>
|
|
<span class="p">....;</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">leaf</span><span class="o">::</span><span class="n">match</span><span class="o"><</span><span class="n">validation_error</span><span class="p">,</span> <span class="n">validation_error</span><span class="o">::</span><span class="n">invalid_format</span><span class="p">,</span> <span class="n">validation_error</span><span class="o">::</span><span class="n">out_of_range</span><span class="o">></span> <span class="n">m</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">assert</span><span class="p">(</span><span class="n">m</span><span class="p">.</span><span class="n">matched</span> <span class="o">==</span> <span class="n">validation_error</span><span class="o">::</span><span class="n">invalid_format</span> <span class="o">||</span> <span class="n">m</span><span class="p">.</span><span class="n">matched</span> <span class="o">==</span> <span class="n">validation_error</span><span class="o">::</span><span class="n">out_of_range</span><span class="p">);</span>
|
|
<span class="p">....;</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">validation_error</span> <span class="n">e</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="p">....;</span>
|
|
<span class="p">}</span> <span class="p">);</span></code></pre>
|
|
</div>
|
|
</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 is 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="rouge highlight nowrap"><code data-lang="c++"><span class="p">[](</span> <span class="n">leaf</span><span class="o">::</span><span class="n">match</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">error_code</span><span class="p">,</span> <span class="n">std</span><span class="o">::</span><span class="n">errc</span><span class="o">::</span><span class="n">no_such_file_or_directory</span><span class="o">></span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>This, however, requires C++17 or newer. LEAF provides the following workaround, compatible with C++11:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="p">[](</span> <span class="n">leaf</span><span class="o">::</span><span class="n">match</span><span class="o"><</span><span class="n">leaf</span><span class="o">::</span><span class="n">condition</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">errc</span><span class="o">></span><span class="p">,</span> <span class="n">std</span><span class="o">::</span><span class="n">errc</span><span class="o">::</span><span class="n">no_such_file_or_directory</span><span class="o">></span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>It is also 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="rouge highlight nowrap"><code data-lang="c++"><span class="p">[](</span> <span class="n">std</span><span class="o">::</span><span class="n">error_code</span><span class="p">,</span> <span class="n">leaf</span><span class="o">::</span><span class="n">category</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">errc</span><span class="o">></span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="p">}</span></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 equivalent 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_"><code>catch_</code></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>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> and <code>std::error_condition</code></a>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="tutorial-binding_handlers">Reusing Common Error Handlers</h3>
|
|
<div class="paragraph">
|
|
<p>Consider this snippet:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">config</span> <span class="n">cfg</span> <span class="o">=</span> <span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_all</span><span class="p">(</span>
|
|
|
|
<span class="p">[</span><span class="o">&</span><span class="p">]</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">load_config_file</span><span class="p">(</span><span class="n">config_path</span><span class="p">);</span> <span class="c1">// returns leaf::result<config></span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span><span class="n">api_error</span> <span class="n">e</span><span class="p">)</span> <span class="o">-></span> <span class="n">config</span>
|
|
<span class="p">{</span>
|
|
<span class="p">....</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span><span class="n">io_error</span> <span class="n">e</span><span class="p">,</span> <span class="n">e_file_name</span> <span class="k">const</span> <span class="o">&</span> <span class="n">fn</span><span class="p">)</span> <span class="o">-></span> <span class="n">config</span>
|
|
<span class="p">{</span>
|
|
<span class="p">....</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[]()</span> <span class="o">-></span> <span class="n">config</span>
|
|
<span class="p">{</span>
|
|
<span class="p">....</span>
|
|
<span class="p">});</span></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>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 the <code>TryBlock</code> for <code>try_handle_all</code>:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">config</span> <span class="n">cfg</span> <span class="o">=</span> <span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_all</span><span class="p">(</span>
|
|
|
|
<span class="p">[</span><span class="o">&</span><span class="p">]</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">load_config_file</span><span class="p">(</span><span class="n">fallback_path</span><span class="p">);</span> <span class="c1">// returns leaf::result<config></span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span><span class="n">api_error</span> <span class="n">e</span><span class="p">)</span> <span class="o">-></span> <span class="n">config</span>
|
|
<span class="p">{</span>
|
|
<span class="p">....</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span><span class="n">io_error</span> <span class="n">e</span><span class="p">,</span> <span class="n">e_file_name</span> <span class="k">const</span> <span class="o">&</span> <span class="n">fn</span><span class="p">)</span> <span class="o">-></span> <span class="n">config</span>
|
|
<span class="p">{</span>
|
|
<span class="p">....</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[]()</span> <span class="o">-></span> <span class="n">config</span>
|
|
<span class="p">{</span>
|
|
<span class="p">....</span>
|
|
<span class="p">});</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>That works, but it is also possible to bind the error handlers in a <code>std::tuple</code>:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">auto</span> <span class="n">load_config_error_handlers</span> <span class="o">=</span> <span class="n">std</span><span class="o">::</span><span class="n">make_tuple</span><span class="p">(</span>
|
|
|
|
<span class="p">[](</span><span class="n">api_error</span> <span class="n">e</span><span class="p">)</span> <span class="o">-></span> <span class="n">config</span>
|
|
<span class="p">{</span>
|
|
<span class="p">....</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span><span class="n">io_error</span> <span class="n">e</span><span class="p">,</span> <span class="n">e_file_name</span> <span class="k">const</span> <span class="o">&</span> <span class="n">fn</span><span class="p">)</span> <span class="o">-></span> <span class="n">config</span>
|
|
<span class="p">{</span>
|
|
<span class="p">....</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[]()</span> <span class="o">-></span> <span class="n">config</span>
|
|
<span class="p">{</span>
|
|
<span class="p">....</span>
|
|
<span class="p">});</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>load_config_error_handlers</code> tuple can later be used with any error handling function:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">config</span> <span class="n">cfg1</span> <span class="o">=</span> <span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_all</span><span class="p">(</span>
|
|
|
|
<span class="p">[</span><span class="o">&</span><span class="p">]</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">load_config_file</span><span class="p">(</span><span class="n">config_path</span><span class="p">);</span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
<span class="p">},</span>
|
|
|
|
<span class="n">load_config_error_handlers</span> <span class="p">);</span>
|
|
|
|
<span class="n">config</span> <span class="n">cfg2</span> <span class="o">=</span> <span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_all</span><span class="p">(</span>
|
|
|
|
<span class="p">[</span><span class="o">&</span><span class="p">]</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">load_config_file</span><span class="p">(</span><span class="n">fallback_path</span><span class="p">);</span> <i class="conum" data-value="2"></i><b>(2)</b>
|
|
<span class="p">},</span>
|
|
|
|
<span class="n">load_config_error_handlers</span> <span class="p">);</span> <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>load_config_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 Errors Between Threads</h3>
|
|
<div class="paragraph">
|
|
<p>Like exceptions, LEAF error objects are local to a thread. When using concurrency, sometimes we need to collect error objects in one thread, then use them to handle errors in another thread.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>LEAF supports this functionality with or without exception handling. In both cases error objects are captured and transported in a <code>leaf::<a href="#result"><code>result</code></a><T></code> object.</p>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="tutorial-async_result">Transporting Errors Between Threads Without Exception Handling</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="rouge highlight nowrap"><code data-lang="c++"><span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">task_result</span><span class="o">></span> <span class="n">task</span><span class="p">();</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Because the task will run asynchronously, in case of a failure we need to capture any produced error objects but not handle errors. We do this by invoking <code>try_capture_all</code>:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">std</span><span class="o">::</span><span class="n">future</span><span class="o"><</span><span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">task_result</span><span class="o">>></span> <span class="n">launch_task</span><span class="p">()</span> <span class="k">noexcept</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">std</span><span class="o">::</span><span class="n">async</span><span class="p">(</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">launch</span><span class="o">::</span><span class="n">async</span><span class="p">,</span>
|
|
<span class="p">[</span><span class="o">&</span><span class="p">]</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">leaf</span><span class="o">::</span><span class="n">try_capture_all</span><span class="p">(</span><span class="n">task</span><span class="p">);</span>
|
|
<span class="p">}</span> <span class="p">);</span>
|
|
<span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph text-right">
|
|
<p><a href="#result"><code>result</code></a> | <a href="#try_capture_all"><code>try_capture_all</code></a></p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In case of a failure, the returned from <code>try_capture_all</code> <code>result<T></code> object holds all error objects communicated out of the <code>task</code>, at the cost of dynamic allocations. The <code>result<T></code> object can then be stashed away or moved to another thread, and later passed to an error-handling function to unload its content and handle errors:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="c1">//std::future<leaf::result<task_result>> fut;</span>
|
|
<span class="n">fut</span><span class="p">.</span><span class="n">wait</span><span class="p">();</span>
|
|
|
|
<span class="k">return</span> <span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_some</span><span class="p">(</span>
|
|
|
|
<span class="p">[</span><span class="o">&</span><span class="p">]()</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">void</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="n">BOOST_LEAF_AUTO</span><span class="p">(</span><span class="n">r</span><span class="p">,</span> <span class="n">fut</span><span class="p">.</span><span class="n">get</span><span class="p">());</span>
|
|
<span class="c1">//Success!</span>
|
|
<span class="k">return</span> <span class="p">{</span> <span class="p">};</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span><span class="n">E1</span> <span class="n">e1</span><span class="p">,</span> <span class="n">E2</span> <span class="n">e2</span><span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="c1">//Deal with E1, E2</span>
|
|
<span class="p">....</span>
|
|
<span class="k">return</span> <span class="p">{</span> <span class="p">};</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span><span class="n">E3</span> <span class="n">e3</span><span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="c1">//Deal with E3</span>
|
|
<span class="p">....</span>
|
|
<span class="k">return</span> <span class="p">{</span> <span class="p">};</span>
|
|
<span class="p">}</span> <span class="p">);</span></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>BOOST_LEAF_AUTO</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">
|
|
Follow this link to see a complete example program: <a href="https://github.com/boostorg/leaf/blob/master/example/try_capture_all_result.cpp?ts=4">try_capture_all_result.cpp</a>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="tutorial-async_eh">Transporting Errors Between Threads With 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="rouge highlight nowrap"><code data-lang="c++"><span class="n">task_result</span> <span class="nf">task</span><span class="p">();</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>We use <code>try_capture_all</code> to capture all error objects and the <code>std::current_exception()</code> in a <code>result<T></code>:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">std</span><span class="o">::</span><span class="n">future</span><span class="o"><</span><span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">task_result</span><span class="o">>></span> <span class="n">launch_task</span><span class="p">()</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">std</span><span class="o">::</span><span class="n">async</span><span class="p">(</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">launch</span><span class="o">::</span><span class="n">async</span><span class="p">,</span>
|
|
<span class="p">[</span><span class="o">&</span><span class="p">]</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">leaf</span><span class="o">::</span><span class="n">try_capture_all</span><span class="p">(</span><span class="n">task</span><span class="p">);</span>
|
|
<span class="p">}</span> <span class="p">);</span>
|
|
<span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph text-right">
|
|
<p><a href="#try_capture_all"><code>try_capture_all</code></a></p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To handle errors after waiting on the future, we use <code>try_catch</code> as usual:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="c1">//std::future<leaf::result<task_result>> fut;</span>
|
|
<span class="n">fut</span><span class="p">.</span><span class="n">wait</span><span class="p">();</span>
|
|
|
|
<span class="k">return</span> <span class="n">leaf</span><span class="o">::</span><span class="n">try_catch</span><span class="p">(</span>
|
|
|
|
<span class="p">[</span><span class="o">&</span><span class="p">]</span>
|
|
<span class="p">{</span>
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">task_result</span><span class="o">></span> <span class="n">r</span> <span class="o">=</span> <span class="n">fut</span><span class="p">.</span><span class="n">get</span><span class="p">();</span>
|
|
<span class="n">task_result</span> <span class="n">v</span> <span class="o">=</span> <span class="n">r</span><span class="p">.</span><span class="n">value</span><span class="p">();</span> <span class="c1">// throws on error</span>
|
|
<span class="c1">//Success!</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span><span class="n">E1</span> <span class="n">e1</span><span class="p">,</span> <span class="n">E2</span> <span class="n">e2</span><span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="c1">//Deal with E1, E2</span>
|
|
<span class="p">....</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span><span class="n">E3</span> <span class="n">e3</span><span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="c1">//Deal with E3</span>
|
|
<span class="p">....</span>
|
|
<span class="p">}</span> <span class="p">);</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph text-right">
|
|
<p><a href="#try_catch"><code>try_catch</code></a> | <a href="#result"><code>result</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">
|
|
Follow this link to see a complete example program: <a href="https://github.com/boostorg/leaf/blob/master/example/try_capture_all_exceptions.cpp?ts=4">try_capture_all_exceptions.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 an 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 well documented:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">enum</span> <span class="n">error_code</span>
|
|
<span class="p">{</span>
|
|
<span class="p">....</span>
|
|
<span class="n">read_error</span><span class="p">,</span>
|
|
<span class="n">size_error</span><span class="p">,</span>
|
|
<span class="n">eof_error</span><span class="p">,</span>
|
|
<span class="p">....</span>
|
|
<span class="p">};</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The disadvantage of such flat enums is that they do not support handling of a whole class of failures. Consider the following LEAF error handler:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="p">....</span>
|
|
<span class="p">[](</span><span class="n">leaf</span><span class="o">::</span><span class="n">match</span><span class="o"><</span><span class="n">error_code</span><span class="p">,</span> <span class="n">size_error</span><span class="p">,</span> <span class="n">read_error</span><span class="p">,</span> <span class="n">eof_error</span><span class="o">></span><span class="p">,</span> <span class="n">leaf</span><span class="o">::</span><span class="n">e_file_name</span> <span class="k">const</span> <span class="o">&</span> <span class="n">fn</span><span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"Failed to access "</span> <span class="o"><<</span> <span class="n">fn</span><span class="p">.</span><span class="n">value</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
|
|
<span class="p">},</span>
|
|
<span class="p">....</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph text-right">
|
|
<p><a href="#match"><code>match</code></a> | <a href="#e_file_name"><code>e_file_name</code></a></p>
|
|
</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>Using exceptions is an improvement because exception types can be organized in a hierarchy in order to classify failures:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">struct</span> <span class="nc">input_error</span><span class="o">:</span> <span class="n">std</span><span class="o">::</span><span class="n">exception</span> <span class="p">{</span> <span class="p">};</span>
|
|
<span class="k">struct</span> <span class="nc">read_error</span><span class="o">:</span> <span class="n">input_error</span> <span class="p">{</span> <span class="p">};</span>
|
|
<span class="k">struct</span> <span class="nc">size_error</span><span class="o">:</span> <span class="n">input_error</span> <span class="p">{</span> <span class="p">};</span>
|
|
<span class="k">struct</span> <span class="nc">eof_error</span><span class="o">:</span> <span class="n">input_error</span> <span class="p">{</span> <span class="p">};</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="p">[](</span><span class="n">input_error</span> <span class="o">&</span><span class="p">,</span> <span class="n">leaf</span><span class="o">::</span><span class="n">e_file_name</span> <span class="k">const</span> <span class="o">&</span> <span class="n">fn</span><span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"Failed to access "</span> <span class="o"><<</span> <span class="n">fn</span><span class="p">.</span><span class="n">value</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
|
|
<span class="p">},</span></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. Instead of our <code>error_code</code> enum, we could define:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="p">....</span>
|
|
<span class="k">struct</span> <span class="nc">input_error</span> <span class="p">{</span> <span class="p">};</span>
|
|
<span class="k">struct</span> <span class="nc">read_error</span> <span class="p">{</span> <span class="p">};</span>
|
|
<span class="k">struct</span> <span class="nc">size_error</span> <span class="p">{</span> <span class="p">};</span>
|
|
<span class="k">struct</span> <span class="nc">eof_error</span> <span class="p">{</span> <span class="p">};</span>
|
|
<span class="p">....</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>With this in place, we could define a function <code>file_read</code>:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">void</span><span class="o">></span> <span class="n">file_read</span><span class="p">(</span> <span class="kt">FILE</span> <span class="o">&</span> <span class="n">f</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span> <span class="n">buf</span><span class="p">,</span> <span class="kt">int</span> <span class="n">size</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="kt">int</span> <span class="n">n</span> <span class="o">=</span> <span class="n">fread</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">size</span><span class="p">,</span> <span class="o">&</span><span class="n">f</span><span class="p">);</span>
|
|
|
|
<span class="k">if</span><span class="p">(</span> <span class="n">ferror</span><span class="p">(</span><span class="o">&</span><span class="n">f</span><span class="p">)</span> <span class="p">)</span>
|
|
<span class="k">return</span> <span class="n">leaf</span><span class="o">::</span><span class="n">new_error</span><span class="p">(</span><span class="n">input_error</span><span class="p">{},</span> <span class="n">read_error</span><span class="p">{},</span> <span class="n">leaf</span><span class="o">::</span><span class="n">e_errno</span><span class="p">{</span><span class="n">errno</span><span class="p">});</span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
|
|
<span class="k">if</span><span class="p">(</span> <span class="n">n</span><span class="o">!=</span><span class="n">size</span> <span class="p">)</span>
|
|
<span class="k">return</span> <span class="n">leaf</span><span class="o">::</span><span class="n">new_error</span><span class="p">(</span><span class="n">input_error</span><span class="p">{},</span> <span class="n">eof_error</span><span class="p">{});</span> <i class="conum" data-value="2"></i><b>(2)</b>
|
|
|
|
<span class="k">return</span> <span class="p">{</span> <span class="p">};</span>
|
|
<span class="p">}</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">void</span><span class="o">></span> <span class="n">file_read</span><span class="p">(</span> <span class="kt">FILE</span> <span class="o">&</span> <span class="n">f</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span> <span class="n">buf</span><span class="p">,</span> <span class="kt">int</span> <span class="n">size</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="k">auto</span> <span class="n">load</span> <span class="o">=</span> <span class="n">leaf</span><span class="o">::</span><span class="n">on_error</span><span class="p">(</span><span class="n">input_error</span><span class="p">{});</span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
|
|
<span class="kt">int</span> <span class="n">n</span> <span class="o">=</span> <span class="n">fread</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">size</span><span class="p">,</span> <span class="o">&</span><span class="n">f</span><span class="p">);</span>
|
|
|
|
<span class="k">if</span><span class="p">(</span> <span class="n">ferror</span><span class="p">(</span><span class="o">&</span><span class="n">f</span><span class="p">)</span> <span class="p">)</span>
|
|
<span class="k">return</span> <span class="n">leaf</span><span class="o">::</span><span class="n">new_error</span><span class="p">(</span><span class="n">read_error</span><span class="p">{},</span> <span class="n">leaf</span><span class="o">::</span><span class="n">e_errno</span><span class="p">{</span><span class="n">errno</span><span class="p">});</span> <i class="conum" data-value="2"></i><b>(2)</b>
|
|
|
|
<span class="k">if</span><span class="p">(</span> <span class="n">n</span><span class="o">!=</span><span class="n">size</span> <span class="p">)</span>
|
|
<span class="k">return</span> <span class="n">leaf</span><span class="o">::</span><span class="n">new_error</span><span class="p">(</span><span class="n">eof_error</span><span class="p">{});</span> <i class="conum" data-value="3"></i><b>(3)</b>
|
|
|
|
<span class="k">return</span> <span class="p">{</span> <span class="p">};</span>
|
|
<span class="p">}</span></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, we just call <code>leaf::throw_exception</code> instead of <code>leaf::new_error</code>:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="kt">void</span> <span class="nf">file_read</span><span class="p">(</span> <span class="kt">FILE</span> <span class="o">&</span> <span class="n">f</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span> <span class="n">buf</span><span class="p">,</span> <span class="kt">int</span> <span class="n">size</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="k">auto</span> <span class="n">load</span> <span class="o">=</span> <span class="n">leaf</span><span class="o">::</span><span class="n">on_error</span><span class="p">(</span><span class="n">input_error</span><span class="p">{});</span>
|
|
|
|
<span class="kt">int</span> <span class="n">n</span> <span class="o">=</span> <span class="n">fread</span><span class="p">(</span><span class="n">buf</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">size</span><span class="p">,</span> <span class="o">&</span><span class="n">f</span><span class="p">);</span>
|
|
|
|
<span class="k">if</span><span class="p">(</span> <span class="n">ferror</span><span class="p">(</span><span class="o">&</span><span class="n">f</span><span class="p">)</span> <span class="p">)</span>
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">throw_exception</span><span class="p">(</span><span class="n">read_error</span><span class="p">{},</span> <span class="n">leaf</span><span class="o">::</span><span class="n">e_errno</span><span class="p">{</span><span class="n">errno</span><span class="p">});</span>
|
|
|
|
<span class="k">if</span><span class="p">(</span> <span class="n">n</span><span class="o">!=</span><span class="n">size</span> <span class="p">)</span>
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">throw_exception</span><span class="p">(</span><span class="n">eof_error</span><span class="p">{});</span>
|
|
<span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph text-right">
|
|
<p><a href="#on_error"><code>on_error</code></a> | <a href="#throw_exception"><code>throw_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::throw_exception</code> derives from <code>std::exception</code>, it will be used to initialize the thrown exception object. Here this is not the case, so the function throws 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>Now we can write a future-proof handler for any <code>input_error</code>:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="p">....</span>
|
|
<span class="p">[](</span><span class="n">input_error</span><span class="p">,</span> <span class="n">leaf</span><span class="o">::</span><span class="n">e_file_name</span> <span class="k">const</span> <span class="o">&</span> <span class="n">fn</span><span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"Failed to access "</span> <span class="o"><<</span> <span class="n">fn</span><span class="p">.</span><span class="n">value</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
|
|
<span class="p">},</span>
|
|
<span class="p">....</span></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.</p>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="tutorial-exception_to_result">Converting Exceptions to <code>result<T></code></h3>
|
|
<div class="paragraph">
|
|
<p>When integrating a library that throws exceptions into code that uses <code>result<T></code>, use <code>exception_to_result</code> to convert exceptions at the boundary:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">struct</span> <span class="nc">parse_error</span><span class="o">:</span> <span class="n">std</span><span class="o">::</span><span class="n">exception</span> <span class="p">{</span> <span class="p">};</span>
|
|
<span class="k">struct</span> <span class="nc">syntax_error</span><span class="o">:</span> <span class="n">parse_error</span> <span class="p">{</span> <span class="p">};</span>
|
|
<span class="k">struct</span> <span class="nc">encoding_error</span><span class="o">:</span> <span class="n">parse_error</span> <span class="p">{</span> <span class="p">};</span>
|
|
|
|
<span class="n">json_value</span> <span class="nf">parse_json</span><span class="p">(</span><span class="kt">char</span> <span class="k">const</span> <span class="o">*</span> <span class="n">str</span><span class="p">);</span> <span class="c1">// Throws parse_error</span>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">json_value</span><span class="o">></span> <span class="n">safe_parse_json</span><span class="p">(</span><span class="kt">char</span> <span class="k">const</span> <span class="o">*</span> <span class="n">str</span><span class="p">)</span> <span class="k">noexcept</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">leaf</span><span class="o">::</span><span class="n">exception_to_result</span><span class="o"><</span><span class="n">syntax_error</span><span class="p">,</span> <span class="n">encoding_error</span><span class="o">></span><span class="p">(</span>
|
|
<span class="p">[</span><span class="o">&</span><span class="p">]</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">parse_json</span><span class="p">(</span><span class="n">str</span><span class="p">);</span>
|
|
<span class="p">}</span> <span class="p">);</span>
|
|
<span class="p">}</span></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 template arguments specify which exception types to capture as error objects. All exceptions are caught, and for each type listed, LEAF attempts a <code>dynamic_cast</code> and loads a copy of that slice. The <code>std::current_exception()</code> is also captured, so unlisted exception types can still be handled.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Errors can then be handled normally:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_all</span><span class="p">(</span>
|
|
|
|
<span class="p">[]()</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">void</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="n">BOOST_LEAF_AUTO</span><span class="p">(</span><span class="n">doc</span><span class="p">,</span> <span class="n">safe_parse_json</span><span class="p">(</span><span class="n">input</span><span class="p">));</span>
|
|
<span class="n">process</span><span class="p">(</span><span class="n">doc</span><span class="p">);</span>
|
|
<span class="k">return</span> <span class="p">{</span> <span class="p">};</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span><span class="n">syntax_error</span> <span class="k">const</span> <span class="o">&</span><span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"JSON syntax error"</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span><span class="n">encoding_error</span> <span class="k">const</span> <span class="o">&</span><span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"Invalid encoding"</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[]</span>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"Unknown error"</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
|
|
<span class="p">}</span> <span class="p">);</span></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>BOOST_LEAF_AUTO</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">
|
|
Handlers that take exception types work the same way whether the object was thrown or loaded via <code>exception_to_result</code>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="tutorial-on_error_in_c_callbacks">Using <code>error_monitor</code> to Report Errors from C Callbacks</h3>
|
|
<div class="paragraph">
|
|
<p>C callbacks have fixed signatures that cannot return C++ types like <code>leaf::result<T></code>. The <a href="#error_monitor"><code>error_monitor</code></a> class solves this problem.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Consider a C library that invokes a user-provided callback:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">enum</span> <span class="k">class</span> <span class="nc">parse_error</span> <span class="p">{</span> <span class="n">unexpected_token</span><span class="p">,</span> <span class="n">invalid_syntax</span> <span class="p">};</span>
|
|
|
|
<span class="kt">int</span> <span class="nf">on_element</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span> <span class="n">ctx</span><span class="p">,</span> <span class="kt">char</span> <span class="k">const</span> <span class="o">*</span> <span class="n">data</span><span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="k">if</span><span class="p">(</span> <span class="o"><<</span><span class="n">error</span><span class="o">-</span><span class="n">detected</span><span class="o">>></span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">new_error</span><span class="p">(</span><span class="n">parse_error</span><span class="o">::</span><span class="n">unexpected_token</span><span class="p">);</span>
|
|
<span class="k">return</span> <span class="o">-</span><span class="mi">1</span><span class="p">;</span>
|
|
<span class="p">}</span>
|
|
<span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
|
|
<span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph text-right">
|
|
<p><a href="#new_error"><code>new_error</code></a></p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The callback calls <code>new_error</code> to associate error objects with the failure, then returns an error code to the C library. The wrapper function uses <code>error_monitor</code> to retrieve the <code>error_id</code>:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="n">document</span><span class="o">></span> <span class="n">parse</span><span class="p">(</span><span class="kt">char</span> <span class="k">const</span> <span class="o">*</span> <span class="n">input</span><span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">error_monitor</span> <span class="n">cur_err</span><span class="p">;</span>
|
|
|
|
<span class="k">if</span><span class="p">(</span> <span class="n">c_library_parse</span><span class="p">(</span><span class="n">input</span><span class="p">,</span> <span class="o">&</span><span class="n">on_element</span><span class="p">,</span> <span class="nb">nullptr</span><span class="p">)</span> <span class="o">!=</span> <span class="mi">0</span> <span class="p">)</span>
|
|
<span class="k">return</span> <span class="n">cur_err</span><span class="p">.</span><span class="n">assigned_error_id</span><span class="p">();</span>
|
|
<span class="k">else</span>
|
|
<span class="k">return</span> <span class="n">make_document</span><span class="p">();</span>
|
|
<span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph text-right">
|
|
<p><a href="#result"><code>result</code></a> | <a href="#error_monitor"><code>error_monitor</code></a></p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If <code>new_error</code> was called inside the callback, <code>assigned_error_id</code> returns that <code>error_id</code>. Otherwise, it calls <code>new_error</code> and returns a fresh <code>error_id</code>. Either way, the caller can handle the failure normally.</p>
|
|
</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:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">enum</span> <span class="k">class</span> <span class="nc">error_code</span>
|
|
<span class="p">{</span>
|
|
<span class="n">read_error</span><span class="p">,</span>
|
|
<span class="n">write_error</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="p">....</span>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_all</span><span class="p">(</span>
|
|
|
|
<span class="p">[]()</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">void</span><span class="o">></span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
<span class="p">{</span>
|
|
<span class="p">....</span>
|
|
<span class="k">return</span> <span class="n">leaf</span><span class="o">::</span><span class="n">new_error</span><span class="p">(</span> <span class="n">error_code</span><span class="o">::</span><span class="n">write_error</span><span class="p">,</span> <span class="n">leaf</span><span class="o">::</span><span class="n">e_file_name</span><span class="p">{</span> <span class="s">"file.txt"</span> <span class="p">}</span> <span class="p">);</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">leaf</span><span class="o">::</span><span class="n">match</span><span class="o"><</span><span class="n">error_code</span><span class="p">,</span> <span class="n">error_code</span><span class="o">::</span><span class="n">read_error</span><span class="o">></span> <span class="p">)</span> <i class="conum" data-value="2"></i><b>(2)</b>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"Read error!"</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">leaf</span><span class="o">::</span><span class="n">diagnostic_details</span> <span class="k">const</span> <span class="o">&</span> <span class="n">info</span> <span class="p">)</span> <i class="conum" data-value="3"></i><b>(3)</b>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"Unrecognized error detected</span><span class="se">\n</span><span class="s">"</span> <span class="o"><<</span> <span class="n">info</span><span class="p">;</span>
|
|
<span class="p">}</span> <span class="p">);</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="colist arabic">
|
|
<table>
|
|
<tr>
|
|
<td><i class="conum" data-value="1"></i><b>1</b></td>
|
|
<td>We handle all failures that occur in this try block.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
|
<td>One or more error handlers that should handle all possible failures.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><i class="conum" data-value="3"></i><b>3</b></td>
|
|
<td>This "catch all" error handler is required by <code>try_handle_all</code>. It will be called if LEAF is unable to use another error handler.</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>diagnostic_details</code> output for the snippet above tells us that we got an <code>error_code</code> with value <code>1</code> (<code>write_error</code>), and an object of type <code>e_file_name</code> with <code>"file.txt"</code> stored in its <code>.value</code>:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="nowrap">Unrecognized error detected
|
|
Error with serial #1
|
|
Caught:
|
|
error_code: 1
|
|
Diagnostic details:
|
|
boost::leaf::e_file_name: file.txt</pre>
|
|
</div>
|
|
</div>
|
|
<div class="admonitionblock tip">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<i class="fa icon-tip" title="Tip"></i>
|
|
</td>
|
|
<td class="content">
|
|
In the <code>diagnostic_details</code> output, the section under <code>Caught:</code> lists the objects which error handlers take as arguments — these are the objects which are stored on the stack. The section under <code>Diagnostic details:</code> lists all other objects that were communicated. These are the objects that would have been discarded if we didn’t provide a handler that takes <code>diagnostic_details</code>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To print each error object, 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 does not 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="rouge highlight nowrap"><code data-lang="c++"><span class="k">struct</span> <span class="nc">e_errno</span>
|
|
<span class="p">{</span>
|
|
<span class="kt">int</span> <span class="n">value</span><span class="p">;</span>
|
|
|
|
<span class="k">friend</span> <span class="n">std</span><span class="o">::</span><span class="n">ostream</span> <span class="o">&</span> <span class="k">operator</span><span class="o"><<</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">ostream</span> <span class="o">&</span> <span class="n">os</span><span class="p">,</span> <span class="n">e_errno</span> <span class="k">const</span> <span class="o">&</span> <span class="n">e</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">os</span> <span class="o"><<</span> <span class="n">e</span><span class="p">.</span><span class="n">value</span> <span class="o"><<</span> <span class="s">", </span><span class="se">\"</span><span class="s">"</span> <span class="o"><<</span> <span class="n">strerror</span><span class="p">(</span><span class="n">e</span><span class="p">.</span><span class="n">value</span><span class="p">)</span> <span class="o"><<</span> <span class="sc">'"'</span><span class="p">;</span>
|
|
<span class="p">}</span>
|
|
<span class="p">};</span></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="paragraph">
|
|
<p>Using <code>diagnostic_details</code> comes at a cost. Normally, when the program attempts to communicate error objects of types which are not used in any error handling scope in the current call stack, they are discarded, which saves cycles. However, if an error handler is provided that takes <code>diagnostic_details</code> argument, such objects are stored on the heap instead of being discarded.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If handling <code>diagnostic_details</code> is considered too costly, use <code>diagnostic_info</code> instead:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_all</span><span class="p">(</span>
|
|
|
|
<span class="p">[]()</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">void</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="p">....</span>
|
|
<span class="k">return</span> <span class="n">leaf</span><span class="o">::</span><span class="n">new_error</span><span class="p">(</span> <span class="n">error_code</span><span class="o">::</span><span class="n">write_error</span><span class="p">,</span> <span class="n">leaf</span><span class="o">::</span><span class="n">e_file_name</span><span class="p">{</span> <span class="s">"file.txt"</span> <span class="p">}</span> <span class="p">);</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">leaf</span><span class="o">::</span><span class="n">match</span><span class="o"><</span><span class="n">error_code</span><span class="p">,</span> <span class="n">error_code</span><span class="o">::</span><span class="n">read_error</span><span class="o">></span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"Read error!"</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">leaf</span><span class="o">::</span><span class="n">diagnostic_info</span> <span class="k">const</span> <span class="o">&</span> <span class="n">info</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"Unrecognized error detected</span><span class="se">\n</span><span class="s">"</span> <span class="o"><<</span> <span class="n">info</span><span class="p">;</span>
|
|
<span class="p">}</span> <span class="p">);</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>In this case, the output may look like this:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="nowrap">Unrecognized error detected
|
|
Error serial #1
|
|
Caught:
|
|
error_code: 1</pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Notice how we are missing the <code>Diagnostic details:</code> section. That’s because the <code>e_file_name</code> object was discarded by LEAF, since no error handler needed it.</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.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="tutorial-serialization">Serialization</h3>
|
|
<div class="paragraph">
|
|
<p>LEAF provides a serialization API that enables exporting error information into different formats, such as JSON. This is useful for structured logging, remote debugging, or integrating with monitoring systems. To serialize error information, use the <code>output_to</code> member function available on the following types:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p><a href="#error_info"><code>error_info</code></a></p>
|
|
</li>
|
|
<li>
|
|
<p><a href="#diagnostic_info"><code>diagnostic_info</code></a></p>
|
|
</li>
|
|
<li>
|
|
<p><a href="#diagnostic_details"><code>diagnostic_details</code></a></p>
|
|
</li>
|
|
<li>
|
|
<p><a href="#result"><code>result</code></a></p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>LEAF serialization is defined in terms of <code>output</code> and <code>output_at</code> function calls, found via ADL:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p><code>output(e, x)</code> serializes <code>x</code> directly to encoder <code>e</code> as a value.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>output_at(e, x, name)</code> serializes <code>x</code> to encoder <code>e</code> as a named field.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>LEAF provides generic <code>output</code> overloads for the following types:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p><code>error_id</code></p>
|
|
</li>
|
|
<li>
|
|
<p><code>e_source_location</code></p>
|
|
</li>
|
|
<li>
|
|
<p><code>e_errno</code></p>
|
|
</li>
|
|
<li>
|
|
<p><code>std::error_code</code></p>
|
|
</li>
|
|
<li>
|
|
<p><code>std::error_condition</code></p>
|
|
</li>
|
|
<li>
|
|
<p><code>std::exception</code></p>
|
|
</li>
|
|
<li>
|
|
<p><code>std::exception_ptr</code></p>
|
|
</li>
|
|
<li>
|
|
<p>any type with a <code>.value</code> member for which a suitable <code>output</code> can be found via ADL</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="custom-encoders">Custom Encoders</h4>
|
|
<div class="paragraph">
|
|
<p>To support exporting to a specific format, users define an encoder class with associated <code>output</code> and <code>output_at</code> function templates specific to that encoder:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">struct</span> <span class="nc">my_encoder</span>
|
|
<span class="p">{</span>
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="kt">void</span> <span class="n">output</span><span class="p">(</span><span class="n">my_encoder</span> <span class="o">&</span> <span class="n">e</span><span class="p">,</span> <span class="n">T</span> <span class="k">const</span> <span class="o">&</span> <span class="n">x</span><span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="c1">// output value x to e</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="kt">void</span> <span class="nf">output_at</span><span class="p">(</span><span class="n">my_encoder</span> <span class="o">&</span> <span class="n">e</span><span class="p">,</span> <span class="n">T</span> <span class="k">const</span> <span class="o">&</span> <span class="n">x</span><span class="p">,</span> <span class="kt">char</span> <span class="k">const</span> <span class="o">*</span> <span class="n">name</span><span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="c1">// output x to e as a named field</span>
|
|
<span class="p">}</span>
|
|
<span class="p">};</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>output_at</code> function typically creates a nested scope (e.g. a JSON object or XML element) and then makes an unqualified call to <code>output</code> to output the value. This will call any compatible overload found via ADL.</p>
|
|
</div>
|
|
<div class="admonitionblock tip">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<i class="fa icon-tip" title="Tip"></i>
|
|
</td>
|
|
<td class="content">
|
|
The <code>output</code> function may need to be defined using SFINAE to avoid ambiguities with the generic <code>output</code> overloads provided by LEAF. Custom encoders must also handle types that do not provide ADL <code>output</code> overloads, including built-in types like <code>int</code> and <code>std::string</code>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To enable serialization to a custom encoder type, define a <code>serialize</code> function template in the <code>boost::leaf::serialization</code> namespace:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">namespace</span> <span class="n">serialization</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Handle</span><span class="p">,</span> <span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="kt">void</span> <span class="n">serialize</span><span class="p">(</span><span class="n">Handle</span> <span class="o">&</span> <span class="n">h</span><span class="p">,</span> <span class="n">T</span> <span class="k">const</span> <span class="o">&</span> <span class="n">x</span><span class="p">,</span> <span class="kt">char</span> <span class="k">const</span> <span class="o">*</span> <span class="n">name</span><span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">h</span><span class="p">.</span><span class="n">dispatch</span><span class="p">([</span><span class="o">&</span><span class="p">](</span><span class="n">my_encoder</span> <span class="o">&</span> <span class="n">e</span><span class="p">)</span> <span class="p">{</span>
|
|
<span class="n">output_at</span><span class="p">(</span><span class="n">e</span><span class="p">,</span> <span class="n">x</span><span class="p">,</span> <span class="n">name</span><span class="p">);</span>
|
|
<span class="p">});</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="p">}</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>serialize</code> function template takes a handle reference <code>h</code> (of unspecified type) that holds an encoder, the error object to be serialized, and its type name. Call <code>h.dispatch</code> with a single-argument function F to detect the encoder type based on F’s argument type; F is called only if the handle contains an encoder of that type.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>To support multiple output formats, pass multiple functions to <code>h.dispatch</code>:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">h</span><span class="p">.</span><span class="n">dispatch</span><span class="p">(</span>
|
|
<span class="p">[</span><span class="o">&</span><span class="p">](</span><span class="n">json_encoder_nlohmann</span> <span class="o">&</span> <span class="n">e</span><span class="p">)</span> <span class="p">{</span> <span class="n">output_at</span><span class="p">(</span><span class="n">e</span><span class="p">,</span> <span class="n">x</span><span class="p">,</span> <span class="n">name</span><span class="p">);</span> <span class="p">},</span>
|
|
<span class="p">[</span><span class="o">&</span><span class="p">](</span><span class="n">xml_encoder</span> <span class="o">&</span> <span class="n">xe</span><span class="p">)</span> <span class="p">{</span> <span class="n">output_at</span><span class="p">(</span><span class="n">xe</span><span class="p">,</span> <span class="n">x</span><span class="p">,</span> <span class="n">name</span><span class="p">);</span> <span class="p">}</span>
|
|
<span class="p">);</span></code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="_json_serialization">JSON Serialization</h4>
|
|
<div class="paragraph">
|
|
<p>LEAF provides encoders for JSON serialization with two popular JSON libraries:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p><a href="#json_encoder_nlohmann"><code>json_encoder_nlohmann</code></a> for <a href="https://github.com/nlohmann/json">nlohmann/json</a></p>
|
|
</li>
|
|
<li>
|
|
<p><a href="#json_encoder_boost"><code>json_encoder_boost</code></a> for <a href="https://www.boost.org/doc/libs/release/libs/json/">Boost.JSON</a></p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Below is an example using <code>json_encoder_nlohmann</code>. We just need to define the required <code>serialize</code> function template (see <a href="#custom-encoders">Custom Encoders</a>):</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="cp">#include</span> <span class="cpf"><boost/leaf/serialization/json_encoder_nlohmann.hpp></span><span class="cp">
|
|
#include</span> <span class="cpf">"nlohmann/json.hpp"</span><span class="cp">
|
|
</span>
|
|
<span class="k">namespace</span> <span class="n">leaf</span> <span class="o">=</span> <span class="n">boost</span><span class="o">::</span><span class="n">leaf</span><span class="p">;</span>
|
|
|
|
<span class="k">using</span> <span class="n">json_encoder_nlohmann</span> <span class="o">=</span> <span class="n">leaf</span><span class="o">::</span><span class="n">serialization</span><span class="o">::</span><span class="n">json_encoder_nlohmann</span><span class="o"><</span><span class="n">nlohmann</span><span class="o">::</span><span class="n">json</span><span class="o">></span><span class="p">;</span>
|
|
|
|
<span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">namespace</span> <span class="n">serialization</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Handle</span><span class="p">,</span> <span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="kt">void</span> <span class="n">serialize</span><span class="p">(</span><span class="n">Handle</span> <span class="o">&</span> <span class="n">h</span><span class="p">,</span> <span class="n">T</span> <span class="k">const</span> <span class="o">&</span> <span class="n">x</span><span class="p">,</span> <span class="kt">char</span> <span class="k">const</span> <span class="o">*</span> <span class="n">name</span><span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">h</span><span class="p">.</span><span class="n">dispatch</span><span class="p">([</span><span class="o">&</span><span class="p">](</span><span class="n">json_encoder_nlohmann</span> <span class="o">&</span> <span class="n">e</span><span class="p">)</span> <span class="p">{</span>
|
|
<span class="n">output_at</span><span class="p">(</span><span class="n">e</span><span class="p">,</span> <span class="n">x</span><span class="p">,</span> <span class="n">name</span><span class="p">);</span>
|
|
<span class="p">});</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="p">}</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>With this in place, we can easily (for example) output <a href="#diagnostic_details"><code>diagnostic_details</code></a> to JSON:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">struct</span> <span class="nc">e_api_response</span>
|
|
<span class="p">{</span>
|
|
<span class="kt">int</span> <span class="n">status</span><span class="p">;</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">message</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Json</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="kt">void</span> <span class="n">to_json</span><span class="p">(</span><span class="n">Json</span> <span class="o">&</span> <span class="n">j</span><span class="p">,</span> <span class="n">e_api_response</span> <span class="k">const</span> <span class="o">&</span> <span class="n">e</span><span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">j</span><span class="p">[</span><span class="s">"status"</span><span class="p">]</span> <span class="o">=</span> <span class="n">e</span><span class="p">.</span><span class="n">status</span><span class="p">;</span>
|
|
<span class="n">j</span><span class="p">[</span><span class="s">"message"</span><span class="p">]</span> <span class="o">=</span> <span class="n">e</span><span class="p">.</span><span class="n">message</span><span class="p">;</span>
|
|
<span class="p">}</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">struct</span> <span class="nc">e_request_url</span>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">value</span><span class="p">;</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="p">....</span>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_all</span><span class="p">(</span>
|
|
<span class="p">[]()</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">void</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="p">....</span>
|
|
<span class="k">return</span> <span class="n">leaf</span><span class="o">::</span><span class="n">new_error</span><span class="p">(</span><span class="n">e_api_response</span><span class="p">{</span><span class="mi">403</span><span class="p">,</span> <span class="s">"Access denied"</span><span class="p">},</span> <span class="n">e_request_url</span><span class="p">{</span><span class="s">"/api/admin/settings"</span><span class="p">});</span>
|
|
<span class="p">},</span>
|
|
<span class="p">[](</span><span class="n">leaf</span><span class="o">::</span><span class="n">diagnostic_details</span> <span class="k">const</span> <span class="o">&</span> <span class="n">dd</span><span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">nlohmann</span><span class="o">::</span><span class="n">json</span> <span class="n">j</span><span class="p">;</span>
|
|
<span class="n">json_encoder_nlohmann</span> <span class="n">e</span><span class="p">(</span><span class="n">j</span><span class="p">);</span>
|
|
<span class="n">dd</span><span class="p">.</span><span class="n">output_to</span><span class="p">(</span><span class="n">e</span><span class="p">);</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="n">j</span><span class="p">.</span><span class="n">dump</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
|
|
<span class="p">}</span>
|
|
<span class="p">);</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">Output:</div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="json"><span class="p">{</span><span class="w">
|
|
</span><span class="nl">"e_api_response"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
|
|
</span><span class="nl">"status"</span><span class="p">:</span><span class="w"> </span><span class="mi">403</span><span class="p">,</span><span class="w">
|
|
</span><span class="nl">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Access denied"</span><span class="w">
|
|
</span><span class="p">},</span><span class="w">
|
|
</span><span class="nl">"e_request_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"/api/admin/settings"</span><span class="w">
|
|
</span><span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph text-right">
|
|
<p><a href="#diagnostic_details"><code>diagnostic_details</code></a> | <a href="#diagnostic_info"><code>diagnostic_info</code></a> | <a href="#error_info"><code>error_info</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">
|
|
In the example above, <code>e_api_response</code> uses an unqualified call to <code>to_json</code> for serialization. This is to demonstrate that <code>json_encoder_nlohmann</code> handles third party type with suitable <code>to_json</code> overloads automatically. If instead we defined a function <code>output</code> compatible with the LEAF serialization API, it would make <code>e_api_response</code> compatible with any LEAF encoder.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="tutorial-std_error_code">Working with <code>std::error_code</code> and <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 specification. 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="rouge highlight nowrap"><code data-lang="c++"><span class="k">enum</span> <span class="k">class</span> <span class="nc">file_error</span>
|
|
<span class="p">{</span>
|
|
<span class="n">not_found</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span>
|
|
<span class="n">permission_denied</span><span class="p">,</span>
|
|
<span class="n">disk_full</span>
|
|
<span class="p">};</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>We want to be able to transport <code>file_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>file_error</code> type:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">std</span><span class="o">::</span><span class="n">error_category</span> <span class="k">const</span> <span class="o">&</span> <span class="n">file_error_category</span><span class="p">()</span>
|
|
<span class="p">{</span>
|
|
<span class="k">struct</span> <span class="nc">category</span><span class="o">:</span> <span class="n">std</span><span class="o">::</span><span class="n">error_category</span>
|
|
<span class="p">{</span>
|
|
<span class="kt">char</span> <span class="k">const</span> <span class="o">*</span> <span class="n">name</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span> <span class="k">override</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="s">"file_error"</span><span class="p">;</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="nf">message</span><span class="p">(</span><span class="kt">int</span> <span class="n">code</span><span class="p">)</span> <span class="k">const</span> <span class="k">override</span>
|
|
<span class="p">{</span>
|
|
<span class="k">switch</span><span class="p">(</span> <span class="n">file_error</span><span class="p">(</span><span class="n">code</span><span class="p">)</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="k">case</span> <span class="n">file_error</span><span class="o">::</span><span class="n">not_found</span><span class="p">:</span> <span class="k">return</span> <span class="s">"file not found"</span><span class="p">;</span>
|
|
<span class="k">case</span> <span class="n">file_error</span><span class="o">::</span><span class="n">permission_denied</span><span class="p">:</span> <span class="k">return</span> <span class="s">"permission denied"</span><span class="p">;</span>
|
|
<span class="k">case</span> <span class="n">file_error</span><span class="o">::</span><span class="n">disk_full</span><span class="p">:</span> <span class="k">return</span> <span class="s">"disk full"</span><span class="p">;</span>
|
|
<span class="nl">default:</span> <span class="k">return</span> <span class="s">"unknown file error"</span><span class="p">;</span>
|
|
<span class="p">}</span>
|
|
<span class="p">}</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">static</span> <span class="n">category</span> <span class="n">c</span><span class="p">;</span>
|
|
<span class="k">return</span> <span class="n">c</span><span class="p">;</span>
|
|
<span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>We also need to inform the standard library that <code>file_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>file_error</code> values:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">std</span>
|
|
<span class="p">{</span>
|
|
<span class="k">template</span> <span class="o"><</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">is_error_code_enum</span><span class="o"><</span><span class="n">file_error</span><span class="o">>:</span> <span class="n">std</span><span class="o">::</span><span class="n">true_type</span>
|
|
<span class="p">{</span>
|
|
<span class="p">};</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="n">std</span><span class="o">::</span><span class="n">error_code</span> <span class="nf">make_error_code</span><span class="p">(</span><span class="n">file_error</span> <span class="n">e</span><span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">std</span><span class="o">::</span><span class="n">error_code</span><span class="p">(</span><span class="kt">int</span><span class="p">(</span><span class="n">e</span><span class="p">),</span> <span class="n">file_error_category</span><span class="p">());</span>
|
|
<span class="p">}</span></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>file_error</code> values we’re interested in:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">std</span><span class="o">::</span><span class="n">error_code</span> <span class="nf">read_file</span><span class="p">();</span>
|
|
|
|
<span class="p">....</span>
|
|
<span class="k">auto</span> <span class="n">ec</span> <span class="o">=</span> <span class="n">read_file</span><span class="p">();</span>
|
|
<span class="k">if</span><span class="p">(</span> <span class="n">ec</span> <span class="o">==</span> <span class="n">file_error</span><span class="o">::</span><span class="n">not_found</span> <span class="o">||</span> <span class="n">ec</span> <span class="o">==</span> <span class="n">file_error</span><span class="o">::</span><span class="n">permission_denied</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="c1">// We got either file_error::not_found or file_error::permission_denied</span>
|
|
<span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>This works because the standard library detects that <code>std::is_error_code_enum<file_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>file_error</code>, our program uses a network library which communicates failures in terms of <code>std::error_code</code> with a different error category:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">enum</span> <span class="k">class</span> <span class="nc">net_error</span>
|
|
<span class="p">{</span>
|
|
<span class="n">connection_refused</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span>
|
|
<span class="n">timeout</span><span class="p">,</span>
|
|
<span class="n">host_unreachable</span><span class="p">,</span>
|
|
<span class="n">dns_failed</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="c1">// Boilerplate omitted:</span>
|
|
<span class="c1">// - net_error_category()</span>
|
|
<span class="c1">// - specialization of std::is_error_code_enum</span>
|
|
<span class="c1">// - make_error_code factory function for net_error.</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>We can now use <code>std::error_condition</code> to define <em>logical</em> error conditions that group related <code>std::error_code</code> values from both libraries:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">enum</span> <span class="k">class</span> <span class="nc">resource_condition</span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
<span class="p">{</span>
|
|
<span class="n">unavailable</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span>
|
|
<span class="n">access_denied</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="n">std</span><span class="o">::</span><span class="n">error_category</span> <span class="k">const</span> <span class="o">&</span> <span class="n">resource_condition_category</span><span class="p">()</span> <i class="conum" data-value="2"></i><b>(2)</b>
|
|
<span class="p">{</span>
|
|
<span class="k">struct</span> <span class="nc">category</span><span class="o">:</span> <span class="n">std</span><span class="o">::</span><span class="n">error_category</span>
|
|
<span class="p">{</span>
|
|
<span class="kt">char</span> <span class="k">const</span> <span class="o">*</span> <span class="n">name</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span> <span class="k">override</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="s">"resource_condition"</span><span class="p">;</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="nf">message</span><span class="p">(</span><span class="kt">int</span> <span class="n">cond</span><span class="p">)</span> <span class="k">const</span> <span class="k">override</span>
|
|
<span class="p">{</span>
|
|
<span class="k">switch</span><span class="p">(</span> <span class="n">resource_condition</span><span class="p">(</span><span class="n">cond</span><span class="p">)</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="k">case</span> <span class="n">resource_condition</span><span class="o">::</span><span class="n">unavailable</span><span class="p">:</span> <span class="k">return</span> <span class="s">"resource unavailable"</span><span class="p">;</span>
|
|
<span class="k">case</span> <span class="n">resource_condition</span><span class="o">::</span><span class="n">access_denied</span><span class="p">:</span> <span class="k">return</span> <span class="s">"access denied"</span><span class="p">;</span>
|
|
<span class="nl">default:</span> <span class="k">return</span> <span class="s">"unknown condition"</span><span class="p">;</span>
|
|
<span class="p">}</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="kt">bool</span> <span class="nf">equivalent</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">error_code</span> <span class="k">const</span> <span class="o">&</span> <span class="n">code</span><span class="p">,</span> <span class="kt">int</span> <span class="n">cond</span><span class="p">)</span> <span class="k">const</span> <span class="k">noexcept</span>
|
|
<span class="p">{</span>
|
|
<span class="k">switch</span><span class="p">(</span> <span class="n">resource_condition</span><span class="p">(</span><span class="n">cond</span><span class="p">)</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="k">case</span> <span class="n">resource_condition</span><span class="o">::</span><span class="n">unavailable</span><span class="p">:</span> <i class="conum" data-value="3"></i><b>(3)</b>
|
|
<span class="k">return</span>
|
|
<span class="n">code</span> <span class="o">==</span> <span class="n">file_error</span><span class="o">::</span><span class="n">not_found</span> <span class="o">||</span>
|
|
<span class="n">code</span> <span class="o">==</span> <span class="n">net_error</span><span class="o">::</span><span class="n">host_unreachable</span> <span class="o">||</span>
|
|
<span class="n">code</span> <span class="o">==</span> <span class="n">net_error</span><span class="o">::</span><span class="n">dns_failed</span><span class="p">;</span>
|
|
<span class="k">case</span> <span class="n">resource_condition</span><span class="o">::</span><span class="n">access_denied</span><span class="p">:</span> <i class="conum" data-value="4"></i><b>(4)</b>
|
|
<span class="k">return</span>
|
|
<span class="n">code</span> <span class="o">==</span> <span class="n">file_error</span><span class="o">::</span><span class="n">permission_denied</span> <span class="o">||</span>
|
|
<span class="n">code</span> <span class="o">==</span> <span class="n">net_error</span><span class="o">::</span><span class="n">connection_refused</span><span class="p">;</span>
|
|
<span class="nl">default:</span>
|
|
<span class="k">return</span> <span class="nb">false</span><span class="p">;</span>
|
|
<span class="p">}</span>
|
|
<span class="p">}</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">static</span> <span class="n">category</span> <span class="n">c</span><span class="p">;</span>
|
|
<span class="k">return</span> <span class="n">c</span><span class="p">;</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="k">namespace</span> <span class="n">std</span>
|
|
<span class="p">{</span>
|
|
<span class="k">template</span> <span class="o"><</span><span class="p">></span> <i class="conum" data-value="5"></i><b>(5)</b>
|
|
<span class="k">class</span> <span class="nc">is_error_condition_enum</span><span class="o"><</span><span class="n">resource_condition</span><span class="o">>:</span> <span class="n">std</span><span class="o">::</span><span class="n">true_type</span>
|
|
<span class="p">{</span>
|
|
<span class="p">};</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="n">std</span><span class="o">::</span><span class="n">error_condition</span> <span class="nf">make_error_condition</span><span class="p">(</span><span class="n">resource_condition</span> <span class="n">e</span><span class="p">)</span> <i class="conum" data-value="6"></i><b>(6)</b>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">std</span><span class="o">::</span><span class="n">error_condition</span><span class="p">(</span><span class="kt">int</span><span class="p">(</span><span class="n">e</span><span class="p">),</span> <span class="n">resource_condition_category</span><span class="p">());</span>
|
|
<span class="p">}</span></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 conditions: <code>unavailable</code> and <code>access_denied</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>resource_condition</code>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><i class="conum" data-value="3"></i><b>3</b></td>
|
|
<td>Here we specify that <code>file_error::not_found</code>, <code>net_error::host_unreachable</code>, and <code>net_error::dns_failed</code> are all logically equivalent to <code>resource_condition::unavailable</code>, and that…​</td>
|
|
</tr>
|
|
<tr>
|
|
<td><i class="conum" data-value="4"></i><b>4</b></td>
|
|
<td>…​<code>file_error::permission_denied</code> and <code>net_error::connection_refused</code> are logically equivalent to <code>resource_condition::access_denied</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>resource_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>resource_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>resource_condition::unavailable</code> like so:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">if</span><span class="p">(</span> <span class="n">ec</span> <span class="o">==</span> <span class="n">resource_condition</span><span class="o">::</span><span class="n">unavailable</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="c1">// The resource is unavailable (file not found, host unreachable, or DNS failed)</span>
|
|
<span class="p">}</span></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>resource_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 <code>match</code> predicate can be used as an argument to a LEAF error handler to match a <code>std::error_code</code> with a given error condition. For example, to handle <code>resource_condition::unavailable</code> (see above), we could use:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_some</span><span class="p">(</span>
|
|
|
|
<span class="p">[]</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">open_resource</span><span class="p">();</span> <span class="c1">// returns leaf::result<resource></span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">leaf</span><span class="o">::</span><span class="n">match</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">error_code</span><span class="p">,</span> <span class="n">resource_condition</span><span class="o">::</span><span class="n">unavailable</span><span class="o">></span> <span class="n">m</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">assert</span><span class="p">(</span><span class="n">m</span><span class="p">.</span><span class="n">matched</span> <span class="o">==</span> <span class="n">resource_condition</span><span class="o">::</span><span class="n">unavailable</span><span class="p">);</span>
|
|
<span class="p">....</span>
|
|
<span class="p">}</span> <span class="p">);</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>See <a href="#match"><code>match</code></a> for more examples.</p>
|
|
</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="rouge highlight nowrap"><code data-lang="c++"><span class="k">typedef</span> <span class="n">boost</span><span class="o">::</span><span class="n">error_info</span><span class="o"><</span><span class="k">struct</span> <span class="nc">my_info_</span><span class="p">,</span> <span class="kt">int</span><span class="o">></span> <span class="n">my_info</span><span class="p">;</span>
|
|
|
|
<span class="kt">void</span> <span class="nf">f</span><span class="p">();</span> <span class="c1">// Throws using boost::throw_exception</span>
|
|
|
|
<span class="kt">void</span> <span class="nf">g</span><span class="p">()</span>
|
|
<span class="p">{</span>
|
|
<span class="k">try</span>
|
|
<span class="p">{</span>
|
|
<span class="n">f</span><span class="p">();</span>
|
|
<span class="p">},</span>
|
|
<span class="k">catch</span><span class="p">(</span> <span class="n">boost</span><span class="o">::</span><span class="n">exception</span> <span class="o">&</span> <span class="n">e</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="k">if</span><span class="p">(</span> <span class="kt">int</span> <span class="k">const</span> <span class="o">*</span> <span class="n">x</span> <span class="o">=</span> <span class="n">boost</span><span class="o">::</span><span class="n">get_error_info</span><span class="o"><</span><span class="n">my_info</span><span class="o">></span><span class="p">(</span><span class="n">e</span><span class="p">)</span> <span class="p">)</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"Got my_info with value = "</span> <span class="o"><<</span> <span class="o">*</span><span class="n">x</span><span class="p">;</span>
|
|
<span class="p">}</span> <span class="p">);</span>
|
|
<span class="p">}</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="cp">#include</span> <span class="cpf"><boost/leaf/handle_errors.hpp></span><span class="cp">
|
|
</span>
|
|
<span class="kt">void</span> <span class="nf">g</span><span class="p">()</span>
|
|
<span class="p">{</span>
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">try_catch</span><span class="p">(</span>
|
|
|
|
<span class="p">[]</span>
|
|
<span class="p">{</span>
|
|
<span class="n">f</span><span class="p">();</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">my_info</span> <span class="n">x</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"Got my_info with value = "</span> <span class="o"><<</span> <span class="n">x</span><span class="p">.</span><span class="n">value</span><span class="p">();</span>
|
|
<span class="p">}</span> <span class="p">);</span>
|
|
<span class="p">}</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="kt">void</span> <span class="nf">g</span><span class="p">()</span>
|
|
<span class="p">{</span>
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">try_catch</span><span class="p">(</span>
|
|
|
|
<span class="p">[]</span>
|
|
<span class="p">{</span>
|
|
<span class="n">f</span><span class="p">();</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">leaf</span><span class="o">::</span><span class="n">match_value</span><span class="o"><</span><span class="n">my_info</span><span class="p">,</span> <span class="mi">42</span><span class="o">></span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"Got my_info with value = 42"</span><span class="p">;</span>
|
|
<span class="p">}</span> <span class="p">);</span>
|
|
<span class="p">}</span></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="example">Examples</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>See <a href="https://github.com/boostorg/leaf/tree/master/example">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 see <a href="#distribution">Distribution</a>.</p>
|
|
</div>
|
|
<hr>
|
|
<div class="sect2">
|
|
<h3 id="synopsis-reporting">Error Reporting</h3>
|
|
<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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">struct</span> <span class="nc">e_api_function</span> <span class="p">{</span> <span class="kt">char</span> <span class="k">const</span> <span class="o">*</span> <span class="n">value</span><span class="p">;</span> <span class="p">};</span>
|
|
|
|
<span class="k">struct</span> <span class="nc">e_file_name</span> <span class="p">{</span> <span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">value</span><span class="p">;</span> <span class="p">};</span>
|
|
|
|
<span class="k">struct</span> <span class="nc">e_type_info_name</span> <span class="p">{</span> <span class="kt">char</span> <span class="k">const</span> <span class="o">*</span> <span class="n">value</span><span class="p">;</span> <span class="p">};</span>
|
|
|
|
<span class="k">struct</span> <span class="nc">e_at_line</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">value</span><span class="p">;</span> <span class="p">};</span>
|
|
|
|
<span class="k">struct</span> <span class="nc">e_errno</span>
|
|
<span class="p">{</span>
|
|
<span class="kt">int</span> <span class="n">value</span><span class="p">;</span>
|
|
<span class="k">explicit</span> <span class="n">e_errno</span><span class="p">(</span><span class="kt">int</span> <span class="n">value</span><span class="o">=</span><span class="n">errno</span><span class="p">);</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">CharT</span><span class="p">,</span> <span class="k">class</span> <span class="nc">Traits</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="n">std</span><span class="o">::</span><span class="n">ostream</span> <span class="o">&</span> <span class="k">operator</span><span class="o"><<</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">basic_ostream</span><span class="o"><</span><span class="n">CharT</span><span class="p">,</span> <span class="n">Traits</span><span class="o">></span> <span class="o">&</span><span class="p">,</span> <span class="n">e_errno</span> <span class="k">const</span> <span class="o">&</span><span class="p">);</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">namespace</span> <span class="n">windows</span>
|
|
<span class="p">{</span>
|
|
<span class="k">struct</span> <span class="nc">e_LastError</span>
|
|
<span class="p">{</span>
|
|
<span class="kt">unsigned</span> <span class="n">value</span><span class="p">;</span>
|
|
|
|
<span class="k">explicit</span> <span class="n">e_LastError</span><span class="p">(</span><span class="kt">unsigned</span> <span class="n">value</span><span class="p">);</span>
|
|
|
|
<span class="cp">#if BOOST_LEAF_CFG_WIN32
|
|
</span> <span class="n">e_LastError</span><span class="p">();</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">CharT</span><span class="p">,</span> <span class="k">class</span> <span class="nc">Traits</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="n">std</span><span class="o">::</span><span class="n">ostream</span> <span class="o">&</span> <span class="k">operator</span><span class="o"><<</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">basic_ostream</span><span class="o"><</span><span class="n">CharT</span><span class="p">,</span> <span class="n">Traits</span><span class="o">></span> <span class="o">&</span><span class="p">,</span> <span class="n">e_LastError</span> <span class="k">const</span> <span class="o">&</span><span class="p">);</span>
|
|
<span class="cp">#endif
|
|
</span> <span class="p">};</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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="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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">class</span> <span class="nc">error_id</span>
|
|
<span class="p">{</span>
|
|
<span class="nl">public:</span>
|
|
|
|
<span class="n">error_id</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Enum</span><span class="p">></span>
|
|
<span class="n">error_id</span><span class="p">(</span> <span class="n">Enum</span> <span class="n">e</span><span class="p">,</span> <span class="k">typename</span> <span class="n">std</span><span class="o">::</span><span class="n">enable_if</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">is_error_code_enum</span><span class="o"><</span><span class="n">Enum</span><span class="o">>::</span><span class="n">value</span><span class="p">,</span> <span class="n">Enum</span><span class="o">>::</span><span class="n">type</span> <span class="o">*</span> <span class="o">=</span> <span class="mi">0</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="n">error_id</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">error_code</span> <span class="k">const</span> <span class="o">&</span> <span class="n">ec</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="kt">int</span> <span class="n">value</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="k">explicit</span> <span class="k">operator</span> <span class="kt">bool</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="n">std</span><span class="o">::</span><span class="n">error_code</span> <span class="n">to_error_code</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">friend</span> <span class="kt">bool</span> <span class="k">operator</span><span class="o">==</span><span class="p">(</span> <span class="n">error_id</span> <span class="n">a</span><span class="p">,</span> <span class="n">error_id</span> <span class="n">b</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="k">friend</span> <span class="kt">bool</span> <span class="k">operator</span><span class="o">!=</span><span class="p">(</span> <span class="n">error_id</span> <span class="n">a</span><span class="p">,</span> <span class="n">error_id</span> <span class="n">b</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="k">friend</span> <span class="kt">bool</span> <span class="k">operator</span><span class="o"><</span><span class="p">(</span> <span class="n">error_id</span> <span class="n">a</span><span class="p">,</span> <span class="n">error_id</span> <span class="n">b</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">Item</span><span class="p">></span>
|
|
<span class="n">error_id</span> <span class="n">load</span><span class="p">(</span> <span class="n">Item</span> <span class="o">&&</span> <span class="p">...</span> <span class="n">item</span> <span class="p">)</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">CharT</span><span class="p">,</span> <span class="k">class</span> <span class="nc">Traits</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="n">std</span><span class="o">::</span><span class="n">ostream</span> <span class="o">&</span> <span class="k">operator</span><span class="o"><<</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">basic_ostream</span><span class="o"><</span><span class="n">CharT</span><span class="p">,</span> <span class="n">Traits</span><span class="o">></span> <span class="o">&</span><span class="p">,</span> <span class="n">error_id</span> <span class="p">);</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="kt">bool</span> <span class="n">is_error_id</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">error_code</span> <span class="k">const</span> <span class="o">&</span> <span class="n">ec</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">Item</span><span class="p">></span>
|
|
<span class="n">error_id</span> <span class="n">new_error</span><span class="p">(</span> <span class="n">Item</span> <span class="o">&&</span> <span class="p">...</span> <span class="n">item</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="n">error_id</span> <span class="n">current_error</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="c1">////////////////////////////////////////</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Ctx</span><span class="p">></span>
|
|
<span class="k">class</span> <span class="nc">context_activator</span>
|
|
<span class="p">{</span>
|
|
<span class="n">context_activator</span><span class="p">(</span> <span class="n">context_activator</span> <span class="k">const</span> <span class="o">&</span> <span class="p">)</span> <span class="o">=</span> <span class="k">delete</span><span class="p">;</span>
|
|
<span class="n">context_activator</span> <span class="o">&</span> <span class="k">operator</span><span class="o">=</span><span class="p">(</span> <span class="n">context_activator</span> <span class="k">const</span> <span class="o">&</span> <span class="p">)</span> <span class="o">=</span> <span class="k">delete</span><span class="p">;</span>
|
|
|
|
<span class="nl">public:</span>
|
|
|
|
<span class="k">explicit</span> <span class="n">context_activator</span><span class="p">(</span> <span class="n">Ctx</span> <span class="o">&</span> <span class="n">ctx</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="n">context_activator</span><span class="p">(</span> <span class="n">context_activator</span> <span class="o">&&</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="o">~</span><span class="n">context_activator</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Ctx</span><span class="p">></span>
|
|
<span class="n">context_activator</span><span class="o"><</span><span class="n">Ctx</span><span class="o">></span> <span class="n">activate_context</span><span class="p">(</span> <span class="n">Ctx</span> <span class="o">&</span> <span class="n">ctx</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">R</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">is_result_type</span><span class="o">:</span> <span class="n">std</span><span class="o">::</span><span class="n">false_type</span>
|
|
<span class="p">{</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">R</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">is_result_type</span><span class="o"><</span><span class="n">R</span> <span class="k">const</span><span class="o">>:</span> <span class="n">is_result_type</span><span class="o"><</span><span class="n">R</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span>
|
|
|
|
<span class="cp">#define BOOST_LEAF_ASSIGN(v, r)\
|
|
auto && <<temp>> = r;\
|
|
if( !<<temp>> )\
|
|
return <<temp>>.error();\
|
|
v = std::forward<decltype(<<temp>>)>(<<temp>>).value()
|
|
</span>
|
|
<span class="cp">#define BOOST_LEAF_AUTO(v, r)\
|
|
BOOST_LEAF_ASSIGN(auto v, r)
|
|
</span>
|
|
<span class="cp">#if BOOST_LEAF_CFG_GNUC_STMTEXPR
|
|
</span>
|
|
<span class="cp">#define BOOST_LEAF_CHECK(r)\
|
|
({\
|
|
auto && <<temp>> = (r);\
|
|
if( !<<temp>> )\
|
|
return <<temp>>.error();\
|
|
std::move(<<temp>>);\
|
|
}).value()
|
|
</span>
|
|
<span class="cp">#else
|
|
</span>
|
|
<span class="cp">#define BOOST_LEAF_CHECK(r)\
|
|
{\
|
|
auto && <<temp>> = r;\
|
|
if( !<<temp>> )\
|
|
return <<temp>>.error()\
|
|
}
|
|
</span>
|
|
<span class="cp">#endif
|
|
</span>
|
|
<span class="cp">#define BOOST_LEAF_NEW_ERROR <<exact-definition-unspecified>></span></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="#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>BOOST_LEAF_ASSIGN</code></a> | <a href="#BOOST_LEAF_AUTO"><code>BOOST_LEAF_AUTO</code></a> | <a href="#BOOST_LEAF_CHECK"><code>BOOST_LEAF_CHECK</code></a> | <a href="#BOOST_LEAF_NEW_ERROR"><code>BOOST_LEAF_NEW_ERROR</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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Ex</span><span class="p">,</span> <span class="k">class</span><span class="o">...</span> <span class="nc">E</span><span class="p">></span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
<span class="p">[[</span><span class="n">noreturn</span><span class="p">]]</span> <span class="kt">void</span> <span class="n">throw_exception</span><span class="p">(</span> <span class="n">Ex</span> <span class="o">&&</span><span class="p">,</span> <span class="n">E</span> <span class="o">&&</span> <span class="p">...</span> <span class="p">);</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">E1</span><span class="p">,</span> <span class="k">class</span><span class="o">...</span> <span class="nc">E</span><span class="p">></span> <i class="conum" data-value="2"></i><b>(2)</b>
|
|
<span class="p">[[</span><span class="n">noreturn</span><span class="p">]]</span> <span class="kt">void</span> <span class="n">throw_exception</span><span class="p">(</span> <span class="n">E1</span> <span class="o">&&</span><span class="p">,</span> <span class="n">E</span> <span class="o">&&</span> <span class="p">...</span> <span class="p">);</span>
|
|
|
|
<span class="p">[[</span><span class="n">noreturn</span><span class="p">]]</span> <span class="kt">void</span> <span class="n">throw_exception</span><span class="p">();</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Ex</span><span class="p">,</span> <span class="k">class</span><span class="o">...</span> <span class="nc">E</span><span class="p">></span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
<span class="p">[[</span><span class="n">noreturn</span><span class="p">]]</span> <span class="kt">void</span> <span class="n">throw_exception</span><span class="p">(</span> <span class="n">error_id</span> <span class="n">id</span><span class="p">,</span> <span class="n">Ex</span> <span class="o">&&</span><span class="p">,</span> <span class="n">E</span> <span class="o">&&</span> <span class="p">...</span> <span class="p">);</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">E1</span><span class="p">,</span> <span class="k">class</span><span class="o">...</span> <span class="nc">E</span><span class="p">></span> <i class="conum" data-value="2"></i><b>(2)</b>
|
|
<span class="p">[[</span><span class="n">noreturn</span><span class="p">]]</span> <span class="kt">void</span> <span class="n">throw_exception</span><span class="p">(</span> <span class="n">error_id</span> <span class="n">id</span><span class="p">,</span> <span class="n">E1</span> <span class="o">&&</span><span class="p">,</span> <span class="n">E</span> <span class="o">&&</span> <span class="p">...</span> <span class="p">);</span>
|
|
|
|
<span class="p">[[</span><span class="n">noreturn</span><span class="p">]]</span> <span class="kt">void</span> <span class="n">throw_exception</span><span class="p">(</span> <span class="n">error_id</span> <span class="n">id</span> <span class="p">);</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">Ex</span><span class="p">,</span> <span class="k">class</span> <span class="nc">F</span><span class="p">></span>
|
|
<span class="o"><<</span><span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">>-</span><span class="n">deduced</span><span class="o">>></span> <span class="n">exception_to_result</span><span class="p">(</span> <span class="n">F</span> <span class="o">&&</span> <span class="n">f</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span>
|
|
|
|
<span class="cp">#define BOOST_LEAF_THROW_EXCEPTION <<exact-definition-unspecified>></span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph text-right">
|
|
<p>Reference: <a href="#throw_exception"><code>throw_exception</code></a> | <a href="#BOOST_LEAF_THROW_EXCEPTION"><code>BOOST_LEAF_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="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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">Item</span><span class="p">></span>
|
|
<span class="o"><<</span><span class="n">unspecified</span><span class="o">-</span><span class="n">type</span><span class="o">>></span> <span class="n">on_error</span><span class="p">(</span> <span class="n">Item</span> <span class="o">&&</span> <span class="p">...</span> <span class="n">e</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">class</span> <span class="nc">error_monitor</span>
|
|
<span class="p">{</span>
|
|
<span class="nl">public:</span>
|
|
|
|
<span class="n">error_monitor</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="n">error_id</span> <span class="n">check</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="n">error_id</span> <span class="n">assigned_error_id</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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="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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="k">class</span> <span class="nc">result</span>
|
|
<span class="p">{</span>
|
|
<span class="nl">public:</span>
|
|
|
|
<span class="k">using</span> <span class="n">value_type</span> <span class="o">=</span> <span class="n">T</span><span class="p">;</span>
|
|
|
|
<span class="c1">// NOTE: Copy constructor implicitly deleted.</span>
|
|
<span class="n">result</span><span class="p">(</span> <span class="n">result</span> <span class="o">&&</span> <span class="n">r</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">U</span><span class="p">,</span> <span class="k">class</span> <span class="o">=</span> <span class="k">typename</span> <span class="nc">std</span><span class="o">::</span><span class="n">enable_if</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">is_convertible</span><span class="o"><</span><span class="n">U</span><span class="p">,</span> <span class="n">T</span><span class="p">></span><span class="o">::</span><span class="n">value</span><span class="o">>::</span><span class="n">type</span><span class="o">></span>
|
|
<span class="n">result</span><span class="p">(</span> <span class="n">result</span><span class="o"><</span><span class="n">U</span><span class="o">></span> <span class="o">&&</span> <span class="n">r</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="n">result</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="n">result</span><span class="p">(</span> <span class="n">T</span> <span class="o">&&</span> <span class="n">v</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="n">result</span><span class="p">(</span> <span class="n">T</span> <span class="k">const</span> <span class="o">&</span> <span class="n">v</span> <span class="p">);</span>
|
|
|
|
<span class="n">result</span><span class="p">(</span> <span class="n">error_id</span> <span class="n">err</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">U</span><span class="p">,</span> <span class="k">class</span> <span class="o">=</span> <span class="k">typename</span> <span class="nc">std</span><span class="o">::</span><span class="n">enable_if</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">is_convertible</span><span class="o"><</span><span class="n">U</span><span class="p">,</span> <span class="n">T</span><span class="p">></span><span class="o">::</span><span class="n">value</span><span class="o">>::</span><span class="n">type</span><span class="o">></span>
|
|
<span class="n">result</span><span class="p">(</span> <span class="n">U</span> <span class="o">&&</span> <span class="n">u</span> <span class="p">);</span>
|
|
|
|
<span class="cp">#if BOOST_LEAF_CFG_STD_SYSTEM_ERROR
|
|
</span>
|
|
<span class="n">result</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">error_code</span> <span class="k">const</span> <span class="o">&</span> <span class="n">ec</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Enum</span><span class="p">,</span> <span class="k">class</span> <span class="o">=</span> <span class="k">typename</span> <span class="nc">std</span><span class="o">::</span><span class="n">enable_if</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">is_error_code_enum</span><span class="o"><</span><span class="n">Enum</span><span class="p">></span><span class="o">::</span><span class="n">value</span><span class="p">,</span> <span class="kt">int</span><span class="o">>::</span><span class="n">type</span><span class="o">></span>
|
|
<span class="n">result</span><span class="p">(</span> <span class="n">Enum</span> <span class="n">e</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="cp">#endif
|
|
</span>
|
|
<span class="c1">// NOTE: Assignment operator implicitly deleted.</span>
|
|
<span class="n">result</span> <span class="o">&</span> <span class="k">operator</span><span class="o">=</span><span class="p">(</span> <span class="n">result</span> <span class="o">&&</span> <span class="n">r</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">U</span><span class="p">,</span> <span class="k">class</span> <span class="o">=</span> <span class="k">typename</span> <span class="nc">std</span><span class="o">::</span><span class="n">enable_if</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">is_convertible</span><span class="o"><</span><span class="n">U</span><span class="p">,</span> <span class="n">T</span><span class="p">></span><span class="o">::</span><span class="n">value</span><span class="o">>::</span><span class="n">type</span><span class="o">></span>
|
|
<span class="n">result</span> <span class="o">&</span> <span class="k">operator</span><span class="o">=</span><span class="p">(</span> <span class="n">result</span><span class="o"><</span><span class="n">U</span><span class="o">></span> <span class="o">&&</span> <span class="n">r</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="kt">bool</span> <span class="n">has_value</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="kt">bool</span> <span class="n">has_error</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="k">explicit</span> <span class="k">operator</span> <span class="kt">bool</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="n">T</span> <span class="k">const</span> <span class="o">&</span> <span class="n">value</span><span class="p">()</span> <span class="k">const</span> <span class="o">&</span><span class="p">;</span>
|
|
<span class="n">T</span> <span class="o">&</span> <span class="n">value</span><span class="p">()</span> <span class="o">&</span><span class="p">;</span>
|
|
<span class="n">T</span> <span class="k">const</span> <span class="o">&&</span> <span class="n">value</span><span class="p">()</span> <span class="k">const</span> <span class="o">&&</span><span class="p">;</span>
|
|
<span class="n">T</span> <span class="o">&&</span> <span class="n">value</span><span class="p">()</span> <span class="o">&&</span><span class="p">;</span>
|
|
|
|
<span class="n">T</span> <span class="k">const</span> <span class="o">*</span> <span class="k">operator</span><span class="o">-></span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="n">T</span> <span class="o">*</span> <span class="k">operator</span><span class="o">-></span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="n">T</span> <span class="k">const</span> <span class="o">&</span> <span class="k">operator</span><span class="o">*</span><span class="p">()</span> <span class="k">const</span> <span class="o">&</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="n">T</span> <span class="o">&</span> <span class="k">operator</span><span class="o">*</span><span class="p">()</span> <span class="o">&</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="n">T</span> <span class="k">const</span> <span class="o">&&</span> <span class="k">operator</span><span class="o">*</span><span class="p">()</span> <span class="k">const</span> <span class="o">&&</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="n">T</span> <span class="o">&&</span> <span class="k">operator</span><span class="o">*</span><span class="p">()</span> <span class="o">&&</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="o"><<</span><span class="n">unspecified</span><span class="o">-</span><span class="n">type</span><span class="o">>></span> <span class="n">error</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">Item</span><span class="p">></span>
|
|
<span class="n">error_id</span> <span class="n">load</span><span class="p">(</span> <span class="n">Item</span> <span class="o">&&</span> <span class="p">...</span> <span class="n">item</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="kt">void</span> <span class="n">unload</span><span class="p">();</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Encoder</span><span class="p">></span>
|
|
<span class="kt">void</span> <span class="n">output_to</span><span class="p">(</span> <span class="n">Encoder</span> <span class="o">&</span> <span class="n">e</span> <span class="p">)</span> <span class="k">const</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">CharT</span><span class="p">,</span> <span class="k">class</span> <span class="nc">Traits</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="n">std</span><span class="o">::</span><span class="n">ostream</span> <span class="o">&</span> <span class="k">operator</span><span class="o"><<</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">basic_ostream</span><span class="o"><</span><span class="n">CharT</span><span class="p">,</span> <span class="n">Traits</span><span class="o">></span> <span class="o">&</span><span class="p">,</span> <span class="n">result</span> <span class="k">const</span> <span class="o">&</span> <span class="p">);</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="p">></span>
|
|
<span class="k">class</span> <span class="nc">result</span><span class="o"><</span><span class="kt">void</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="nl">public:</span>
|
|
|
|
<span class="k">using</span> <span class="n">value_type</span> <span class="o">=</span> <span class="kt">void</span><span class="p">;</span>
|
|
|
|
<span class="c1">// NOTE: Copy constructor implicitly deleted.</span>
|
|
<span class="n">result</span><span class="p">(</span> <span class="n">result</span> <span class="o">&&</span> <span class="n">r</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="n">result</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="n">result</span><span class="p">(</span> <span class="n">error_id</span> <span class="n">err</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="cp">#if BOOST_LEAF_CFG_STD_SYSTEM_ERROR
|
|
</span>
|
|
<span class="n">result</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">error_code</span> <span class="k">const</span> <span class="o">&</span> <span class="n">ec</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Enum</span><span class="p">,</span> <span class="k">typename</span> <span class="nc">std</span><span class="o">::</span><span class="n">enable_if</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">is_error_code_enum</span><span class="o"><</span><span class="n">Enum</span><span class="p">></span><span class="o">::</span><span class="n">value</span><span class="p">,</span> <span class="n">Enum</span><span class="o">>::</span><span class="n">type</span><span class="o">></span>
|
|
<span class="n">result</span><span class="p">(</span> <span class="n">Enum</span> <span class="n">e</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="cp">#endif
|
|
</span>
|
|
<span class="c1">// NOTE: Assignment operator implicitly deleted.</span>
|
|
<span class="n">result</span> <span class="o">&</span> <span class="k">operator</span><span class="o">=</span><span class="p">(</span> <span class="n">result</span> <span class="o">&&</span> <span class="n">r</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">explicit</span> <span class="k">operator</span> <span class="kt">bool</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="kt">void</span> <span class="n">value</span><span class="p">()</span> <span class="k">const</span><span class="p">;</span>
|
|
|
|
<span class="kt">void</span> <span class="k">const</span> <span class="o">*</span> <span class="k">operator</span><span class="o">-></span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="kt">void</span> <span class="o">*</span> <span class="k">operator</span><span class="o">-></span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="kt">void</span> <span class="k">operator</span><span class="o">*</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="o"><<</span><span class="n">unspecified</span><span class="o">-</span><span class="n">type</span><span class="o">>></span> <span class="n">error</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">Item</span><span class="p">></span>
|
|
<span class="n">error_id</span> <span class="n">load</span><span class="p">(</span> <span class="n">Item</span> <span class="o">&&</span> <span class="p">...</span> <span class="n">item</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="kt">void</span> <span class="n">unload</span><span class="p">();</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Encoder</span><span class="p">></span>
|
|
<span class="kt">void</span> <span class="n">output_to</span><span class="p">(</span> <span class="n">Encoder</span> <span class="o">&</span> <span class="n">e</span> <span class="p">)</span> <span class="k">const</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">CharT</span><span class="p">,</span> <span class="k">class</span> <span class="nc">Traits</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="n">std</span><span class="o">::</span><span class="n">ostream</span> <span class="o">&</span> <span class="k">operator</span><span class="o"><<</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">basic_ostream</span><span class="o"><</span><span class="n">CharT</span><span class="p">,</span> <span class="n">Traits</span><span class="o">></span> <span class="o">&</span><span class="p">,</span> <span class="n">result</span> <span class="k">const</span> <span class="o">&</span><span class="p">);</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">struct</span> <span class="nc">bad_result</span><span class="o">:</span> <span class="n">std</span><span class="o">::</span><span class="n">exception</span> <span class="p">{</span> <span class="p">};</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">is_result_type</span><span class="o"><</span><span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">>>:</span> <span class="n">std</span><span class="o">::</span><span class="n">true_type</span>
|
|
<span class="p">{</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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>
|
|
<hr>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="synopsis-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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">E</span><span class="p">></span>
|
|
<span class="k">class</span> <span class="nc">context</span>
|
|
<span class="p">{</span>
|
|
<span class="n">context</span><span class="p">(</span> <span class="n">context</span> <span class="k">const</span> <span class="o">&</span> <span class="p">)</span> <span class="o">=</span> <span class="k">delete</span><span class="p">;</span>
|
|
<span class="n">context</span> <span class="o">&</span> <span class="k">operator</span><span class="o">=</span><span class="p">(</span> <span class="n">context</span> <span class="k">const</span> <span class="o">&</span> <span class="p">)</span> <span class="o">=</span> <span class="k">delete</span><span class="p">;</span>
|
|
|
|
<span class="nl">public:</span>
|
|
|
|
<span class="n">context</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="n">context</span><span class="p">(</span> <span class="n">context</span> <span class="o">&&</span> <span class="n">x</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="o">~</span><span class="n">context</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="kt">void</span> <span class="n">activate</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="kt">void</span> <span class="n">deactivate</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="kt">bool</span> <span class="n">is_active</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="kt">void</span> <span class="n">unload</span><span class="p">(</span> <span class="n">error_id</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="kt">void</span> <span class="n">print</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">ostream</span> <span class="o">&</span> <span class="n">os</span> <span class="p">)</span> <span class="k">const</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">CharT</span><span class="p">,</span> <span class="k">class</span> <span class="nc">Traits</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="n">std</span><span class="o">::</span><span class="n">ostream</span> <span class="o">&</span> <span class="k">operator</span><span class="o"><<</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">basic_ostream</span><span class="o"><</span><span class="n">CharT</span><span class="p">,</span> <span class="n">Traits</span><span class="o">></span> <span class="o">&</span><span class="p">,</span> <span class="n">context</span> <span class="k">const</span> <span class="o">&</span> <span class="p">);</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">R</span><span class="p">,</span> <span class="k">class</span><span class="o">...</span> <span class="nc">H</span><span class="p">></span>
|
|
<span class="n">R</span> <span class="n">handle_error</span><span class="p">(</span> <span class="n">R</span> <span class="o">&</span><span class="p">,</span> <span class="n">H</span> <span class="o">&&</span> <span class="p">...</span> <span class="p">)</span> <span class="k">const</span><span class="p">;</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">H</span><span class="p">></span>
|
|
<span class="k">using</span> <span class="n">context_type_from_handlers</span> <span class="o">=</span> <span class="k">typename</span> <span class="o"><<</span><span class="n">unspecified</span><span class="o">>>::</span><span class="n">type</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">H</span><span class="p">></span>
|
|
<span class="n">BOOST_LEAF_CONSTEXPR</span> <span class="n">context_type_from_handlers</span><span class="o"><</span><span class="n">H</span><span class="p">...</span><span class="o">></span> <span class="n">make_context</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">H</span><span class="p">></span>
|
|
<span class="n">BOOST_LEAF_CONSTEXPR</span> <span class="n">context_type_from_handlers</span><span class="o"><</span><span class="n">H</span><span class="p">...</span><span class="o">></span> <span class="n">make_context</span><span class="p">(</span> <span class="n">H</span> <span class="o">&&</span> <span class="p">...</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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></p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="diagnostics.hpp"><code>diagnostics.hpp</code></h4>
|
|
<div class="exampleblock">
|
|
<div class="content">
|
|
<div class="listingblock">
|
|
<div class="title">#include <boost/leaf/diagnostics.hpp></div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">class</span> <span class="nc">diagnostic_info</span><span class="o">:</span> <span class="k">public</span> <span class="n">error_info</span>
|
|
<span class="p">{</span>
|
|
<span class="c1">//No public constructors</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">CharT</span><span class="p">,</span> <span class="k">class</span> <span class="nc">Traits</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="n">std</span><span class="o">::</span><span class="n">ostream</span> <span class="o">&</span> <span class="k">operator</span><span class="o"><<</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">basic_ostream</span><span class="o"><</span><span class="n">CharT</span><span class="p">,</span> <span class="n">Traits</span><span class="o">></span> <span class="o">&</span><span class="p">,</span> <span class="n">diagnostic_info</span> <span class="k">const</span> <span class="o">&</span> <span class="p">);</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">class</span> <span class="nc">diagnostic_details</span><span class="o">:</span> <span class="k">public</span> <span class="n">error_info</span>
|
|
<span class="p">{</span>
|
|
<span class="c1">//No public constructors</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">CharT</span><span class="p">,</span> <span class="k">class</span> <span class="nc">Traits</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="n">std</span><span class="o">::</span><span class="n">ostream</span> <span class="o">&</span> <span class="k">operator</span><span class="o"><<</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">basic_ostream</span><span class="o"><</span><span class="n">CharT</span><span class="p">,</span> <span class="n">Traits</span><span class="o">></span> <span class="o">&</span><span class="p">,</span> <span class="n">diagnostic_info</span> <span class="k">const</span> <span class="o">&</span> <span class="p">);</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph text-right">
|
|
<p>Reference: <a href="#diagnostic_info"><code>diagnostic_info</code></a> | <a href="#diagnostic_details"><code>diagnostic_details</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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">TryBlock</span><span class="p">,</span> <span class="k">class</span><span class="o">...</span> <span class="nc">H</span><span class="p">></span>
|
|
<span class="k">typename</span> <span class="n">std</span><span class="o">::</span><span class="n">decay</span><span class="o"><</span><span class="k">decltype</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">declval</span><span class="o"><</span><span class="n">TryBlock</span><span class="o">></span><span class="p">()().</span><span class="n">value</span><span class="p">())</span><span class="o">>::</span><span class="n">type</span>
|
|
<span class="n">try_handle_all</span><span class="p">(</span> <span class="n">TryBlock</span> <span class="o">&&</span> <span class="n">try_block</span><span class="p">,</span> <span class="n">H</span> <span class="o">&&</span> <span class="p">...</span> <span class="n">h</span> <span class="p">);</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">TryBlock</span><span class="p">,</span> <span class="k">class</span><span class="o">...</span> <span class="nc">H</span><span class="p">></span>
|
|
<span class="k">typename</span> <span class="n">std</span><span class="o">::</span><span class="n">decay</span><span class="o"><</span><span class="k">decltype</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">declval</span><span class="o"><</span><span class="n">TryBlock</span><span class="o">></span><span class="p">()())</span><span class="o">>::</span><span class="n">type</span>
|
|
<span class="n">try_handle_some</span><span class="p">(</span> <span class="n">TryBlock</span> <span class="o">&&</span> <span class="n">try_block</span><span class="p">,</span> <span class="n">H</span> <span class="o">&&</span> <span class="p">...</span> <span class="n">h</span> <span class="p">);</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">TryBlock</span><span class="p">,</span> <span class="k">class</span><span class="o">...</span> <span class="nc">H</span><span class="p">></span>
|
|
<span class="k">typename</span> <span class="n">std</span><span class="o">::</span><span class="n">decay</span><span class="o"><</span><span class="k">decltype</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">declval</span><span class="o"><</span><span class="n">TryBlock</span><span class="o">></span><span class="p">()())</span><span class="o">>::</span><span class="n">type</span>
|
|
<span class="n">try_catch</span><span class="p">(</span> <span class="n">TryBlock</span> <span class="o">&&</span> <span class="n">try_block</span><span class="p">,</span> <span class="n">H</span> <span class="o">&&</span> <span class="p">...</span> <span class="n">h</span> <span class="p">);</span>
|
|
|
|
<span class="cp">#if BOOST_LEAF_CFG_CAPTURE
|
|
</span> <span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">TryBlock</span><span class="p">></span>
|
|
<span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">></span> <span class="c1">// T deduced depending on TryBlock return type</span>
|
|
<span class="n">try_capture_all</span><span class="p">(</span> <span class="n">TryBlock</span> <span class="o">&&</span> <span class="n">try_block</span> <span class="p">);</span>
|
|
<span class="cp">#endif
|
|
</span>
|
|
<span class="k">class</span> <span class="nc">error_info</span>
|
|
<span class="p">{</span>
|
|
<span class="c1">//No public constructors</span>
|
|
|
|
<span class="nl">public:</span>
|
|
|
|
<span class="n">error_id</span> <span class="n">error</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="kt">bool</span> <span class="n">exception_caught</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">exception</span> <span class="k">const</span> <span class="o">*</span> <span class="n">exception</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">CharT</span><span class="p">,</span> <span class="k">class</span> <span class="nc">Traits</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="n">std</span><span class="o">::</span><span class="n">ostream</span> <span class="o">&</span> <span class="k">operator</span><span class="o"><<</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">basic_ostream</span><span class="o"><</span><span class="n">CharT</span><span class="p">,</span> <span class="n">Traits</span><span class="o">></span> <span class="o">&</span><span class="p">,</span> <span class="n">error_info</span> <span class="k">const</span> <span class="o">&</span> <span class="p">);</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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="#try_capture_all"><code>try_capture_all</code></a> | <a href="#error_info"><code>error_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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">is_predicate</span><span class="o">:</span> <span class="n">std</span><span class="o">::</span><span class="n">false_type</span>
|
|
<span class="p">{</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">E</span><span class="p">,</span> <span class="k">auto</span><span class="p">...</span> <span class="n">V</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">match</span>
|
|
<span class="p">{</span>
|
|
<span class="n">E</span> <span class="n">matched</span><span class="p">;</span>
|
|
|
|
<span class="c1">// Other members not specified</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">E</span><span class="p">,</span> <span class="k">auto</span><span class="p">...</span> <span class="n">V</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">is_predicate</span><span class="o"><</span><span class="n">match</span><span class="o"><</span><span class="n">E</span><span class="p">,</span> <span class="n">V</span><span class="p">...</span><span class="o">>>:</span> <span class="n">std</span><span class="o">::</span><span class="n">true_type</span>
|
|
<span class="p">{</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">E</span><span class="p">,</span> <span class="k">auto</span><span class="p">...</span> <span class="n">V</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">match_value</span>
|
|
<span class="p">{</span>
|
|
<span class="n">E</span> <span class="n">matched</span><span class="p">;</span>
|
|
|
|
<span class="c1">// Other members not specified</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">E</span><span class="p">,</span> <span class="k">auto</span><span class="p">...</span> <span class="n">V</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">is_predicate</span><span class="o"><</span><span class="n">match_value</span><span class="o"><</span><span class="n">E</span><span class="p">,</span> <span class="n">V</span><span class="p">...</span><span class="o">>>:</span> <span class="n">std</span><span class="o">::</span><span class="n">true_type</span>
|
|
<span class="p">{</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">auto</span><span class="p">,</span> <span class="k">auto</span><span class="p">...></span>
|
|
<span class="k">struct</span> <span class="nc">match_member</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">E</span><span class="p">,</span> <span class="k">class</span> <span class="nc">T</span><span class="p">,</span> <span class="n">T</span> <span class="n">E</span><span class="o">::*</span> <span class="n">P</span><span class="p">,</span> <span class="k">auto</span><span class="p">...</span> <span class="n">V</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">match_member</span><span class="o"><</span><span class="n">P</span><span class="p">,</span> <span class="n">V</span><span class="p">...</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="n">E</span> <span class="n">matched</span><span class="p">;</span>
|
|
|
|
<span class="c1">// Other members not specified</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">auto</span> <span class="n">P</span><span class="p">,</span> <span class="k">auto</span><span class="p">...</span> <span class="n">V</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">is_predicate</span><span class="o"><</span><span class="n">match_member</span><span class="o"><</span><span class="n">P</span><span class="p">,</span> <span class="n">V</span><span class="p">...</span><span class="o">>>:</span> <span class="n">std</span><span class="o">::</span><span class="n">true_type</span>
|
|
<span class="p">{</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">Ex</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">catch_</span>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">exception</span> <span class="k">const</span> <span class="o">&</span> <span class="n">matched</span><span class="p">;</span>
|
|
|
|
<span class="c1">// Other members not specified</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Ex</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">catch_</span><span class="o"><</span><span class="n">Ex</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="n">Ex</span> <span class="k">const</span> <span class="o">&</span> <span class="n">matched</span><span class="p">;</span>
|
|
|
|
<span class="c1">// Other members not specified</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">Ex</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">is_predicate</span><span class="o"><</span><span class="n">catch_</span><span class="o"><</span><span class="n">Ex</span><span class="p">...</span><span class="o">>>:</span> <span class="n">std</span><span class="o">::</span><span class="n">true_type</span>
|
|
<span class="p">{</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Pred</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">if_not</span>
|
|
<span class="p">{</span>
|
|
<span class="n">E</span> <span class="n">matched</span><span class="p">;</span>
|
|
|
|
<span class="c1">// Other members not specified</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Pred</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">is_predicate</span><span class="o"><</span><span class="n">if_not</span><span class="o"><</span><span class="n">Pred</span><span class="o">>>:</span> <span class="n">std</span><span class="o">::</span><span class="n">true_type</span>
|
|
<span class="p">{</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">ErrorCodeEnum</span><span class="p">></span>
|
|
<span class="kt">bool</span> <span class="n">category</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">error_code</span> <span class="k">const</span> <span class="o">&</span> <span class="n">ec</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Enum</span><span class="p">,</span> <span class="k">class</span> <span class="nc">EnumType</span> <span class="o">=</span> <span class="n">Enum</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">condition</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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 class="sect3">
|
|
<h4 id="to_variant.hpp"><code>to_variant.hpp</code></h4>
|
|
<div class="exampleblock">
|
|
<div class="content">
|
|
<div class="listingblock">
|
|
<div class="title">#include <boost/leaf/to_variant.hpp></div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="c1">// Requires at least C++17</span>
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">E</span><span class="p">,</span> <span class="k">class</span> <span class="nc">TryBlock</span><span class="p">></span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">variant</span><span class="o"><</span>
|
|
<span class="k">typename</span> <span class="n">std</span><span class="o">::</span><span class="n">decay</span><span class="o"><</span><span class="k">decltype</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">declval</span><span class="o"><</span><span class="n">TryBlock</span><span class="o">></span><span class="p">()().</span><span class="n">value</span><span class="p">())</span><span class="o">>::</span><span class="n">type</span><span class="p">,</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">tuple</span><span class="o"><</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">optional</span><span class="o"><</span><span class="n">E</span><span class="o">></span><span class="p">...</span><span class="o">>></span>
|
|
<span class="n">to_variant</span><span class="p">(</span> <span class="n">TryBlock</span> <span class="o">&&</span> <span class="n">try_block</span> <span class="p">);</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph text-right">
|
|
<p>Reference: <a href="#to_variant"><code>to_variant</code></a></p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="synopsis-serialization">Serialization</h3>
|
|
<div class="sect3">
|
|
<h4 id="json_encoder_boost.hpp"><code>json_encoder_boost.hpp</code></h4>
|
|
<div class="exampleblock">
|
|
<div class="content">
|
|
<div class="listingblock">
|
|
<div class="title">#include <boost/leaf/serialization/json_encoder_boost.hpp></div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">namespace</span> <span class="n">serialization</span>
|
|
<span class="p">{</span>
|
|
<span class="k">struct</span> <span class="nc">json_encoder_boost</span>
|
|
<span class="p">{</span>
|
|
<span class="n">boost</span><span class="o">::</span><span class="n">json</span><span class="o">::</span><span class="n">value</span> <span class="o">&</span> <span class="n">v_</span><span class="p">;</span>
|
|
|
|
<span class="c1">// Enabled if x is assignable to boost::json::value, or</span>
|
|
<span class="c1">// if tag_invoke is defined for boost::json::value_from_tag.</span>
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="kt">void</span> <span class="n">output</span><span class="p">(</span> <span class="n">json_encoder_boost</span> <span class="o">&</span><span class="p">,</span> <span class="n">T</span> <span class="k">const</span> <span class="o">&</span> <span class="n">x</span> <span class="p">);</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="kt">void</span> <span class="n">output_at</span><span class="p">(</span> <span class="n">json_encoder_boost</span> <span class="o">&</span><span class="p">,</span> <span class="n">T</span> <span class="k">const</span> <span class="o">&</span><span class="p">,</span> <span class="kt">char</span> <span class="k">const</span> <span class="o">*</span> <span class="n">name</span> <span class="p">);</span>
|
|
<span class="p">};</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph text-right">
|
|
<p>Reference: <a href="#json_encoder_boost"><code>json_encoder_boost</code></a></p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="json_encoder_nlohmann.hpp"><code>json_encoder_nlohmann.hpp</code></h4>
|
|
<div class="exampleblock">
|
|
<div class="content">
|
|
<div class="listingblock">
|
|
<div class="title">#include <boost/leaf/serialization/json_encoder_nlohmann.hpp></div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">namespace</span> <span class="n">serialization</span>
|
|
<span class="p">{</span>
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Json</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">json_encoder_nlohmann</span>
|
|
<span class="p">{</span>
|
|
<span class="n">Json</span> <span class="o">&</span> <span class="n">j_</span><span class="p">;</span>
|
|
|
|
<span class="c1">// Enabled if to_json is available for Json and T.</span>
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="kt">void</span> <span class="n">output</span><span class="p">(</span> <span class="n">json_encoder_nlohmann</span> <span class="o">&</span><span class="p">,</span> <span class="n">T</span> <span class="k">const</span> <span class="o">&</span> <span class="n">x</span> <span class="p">);</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="kt">void</span> <span class="n">output_at</span><span class="p">(</span> <span class="n">json_encoder_nlohmann</span> <span class="o">&</span><span class="p">,</span> <span class="n">T</span> <span class="k">const</span> <span class="o">&</span><span class="p">,</span> <span class="kt">char</span> <span class="k">const</span> <span class="o">*</span> <span class="n">name</span> <span class="p">);</span>
|
|
<span class="p">};</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph text-right">
|
|
<p>Reference: <a href="#json_encoder_nlohmann"><code>json_encoder_nlohmann</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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Ctx</span><span class="p">></span>
|
|
<span class="n">context_activator</span><span class="o"><</span><span class="n">Ctx</span><span class="o">></span> <span class="n">activate_context</span><span class="p">(</span> <span class="n">Ctx</span> <span class="o">&</span> <span class="n">ctx</span> <span class="p">)</span> <span class="k">noexcept</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">context_activator</span><span class="o"><</span><span class="n">Ctx</span><span class="o">></span><span class="p">(</span><span class="n">ctx</span><span class="p">);</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="n">leaf</span><span class="o">::</span><span class="n">context</span><span class="o"><</span><span class="n">E1</span><span class="p">,</span> <span class="n">E2</span><span class="p">,</span> <span class="n">E3</span><span class="o">></span> <span class="n">ctx</span><span class="p">;</span>
|
|
|
|
<span class="p">{</span>
|
|
<span class="k">auto</span> <span class="n">active_context</span> <span class="o">=</span> <span class="n">ctx</span><span class="p">.</span><span class="n">raii_activate</span><span class="p">();</span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
<span class="p">}</span> <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="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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">H</span><span class="p">></span>
|
|
<span class="k">using</span> <span class="n">context_type_from_handlers</span> <span class="o">=</span> <span class="k">typename</span> <span class="o"><<</span><span class="n">unspecified</span><span class="o">>>::</span><span class="n">type</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">Example:</div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">auto</span> <span class="n">error_handlers</span> <span class="o">=</span> <span class="n">std</span><span class="o">::</span><span class="n">make_tuple</span><span class="p">(</span>
|
|
|
|
<span class="p">[](</span><span class="n">e_this</span> <span class="k">const</span> <span class="o">&</span> <span class="n">a</span><span class="p">,</span> <span class="n">e_that</span> <span class="k">const</span> <span class="o">&</span> <span class="n">b</span><span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="p">....</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span><span class="n">leaf</span><span class="o">::</span><span class="n">diagnostic_info</span> <span class="k">const</span> <span class="o">&</span> <span class="n">info</span><span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="p">....</span>
|
|
<span class="p">},</span>
|
|
<span class="p">....</span> <span class="p">);</span>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">context_type_from_handlers</span><span class="o"><</span><span class="k">decltype</span><span class="p">(</span><span class="n">error_handlers</span><span class="p">)</span><span class="o">></span> <span class="n">ctx</span><span class="p">;</span> <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>.
|
|
</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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="n">error_id</span> <span class="n">current_error</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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_to_result"><code>exception_to_result</code></h3>
|
|
<div class="listingblock">
|
|
<div class="title">#include <boost/leaf/exception.hpp></div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">Ex</span><span class="p">,</span> <span class="k">class</span> <span class="nc">F</span><span class="p">></span>
|
|
<span class="o"><<</span><span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">>-</span><span class="n">deduced</span><span class="o">>></span> <span class="n">exception_to_result</span><span class="p">(</span> <span class="n">F</span> <span class="o">&&</span> <span class="n">f</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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"><code>result</code></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="rouge highlight nowrap"><code data-lang="c++"><span class="kt">int</span> <span class="nf">compute_answer_throws</span><span class="p">();</span>
|
|
|
|
<span class="c1">//Call compute_answer, convert exceptions to result<int></span>
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="n">compute_answer</span><span class="p">()</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">leaf</span><span class="o">::</span><span class="n">exception_to_result</span><span class="o"><</span><span class="n">ex_type1</span><span class="p">,</span> <span class="n">ex_type2</span><span class="o">></span><span class="p">(</span>
|
|
<span class="p">[]</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">compute_answer_throws</span><span class="p">();</span>
|
|
<span class="p">}</span> <span class="p">);</span>
|
|
<span class="p">}</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">return</span> <span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_some</span><span class="p">(</span>
|
|
|
|
<span class="p">[]()</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">void</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="n">BOOST_LEAF_AUTO</span><span class="p">(</span><span class="n">answer</span><span class="p">,</span> <span class="n">compute_answer</span><span class="p">());</span>
|
|
<span class="c1">//Use answer</span>
|
|
<span class="p">....</span>
|
|
<span class="k">return</span> <span class="p">{</span> <span class="p">};</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span><span class="n">ex_type1</span> <span class="o">&</span> <span class="n">ex1</span><span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="c1">//Handle ex_type1</span>
|
|
<span class="p">....</span>
|
|
<span class="k">return</span> <span class="p">{</span> <span class="p">};</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span><span class="n">ex_type2</span> <span class="o">&</span> <span class="n">ex2</span><span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="c1">//Handle ex_type2</span>
|
|
<span class="p">....</span>
|
|
<span class="k">return</span> <span class="p">{</span> <span class="p">};</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span><span class="n">std</span><span class="o">::</span><span class="n">exception_ptr</span> <span class="k">const</span> <span class="o">&</span> <span class="n">p</span><span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="c1">//Handle any other exception from compute_answer.</span>
|
|
<span class="p">....</span>
|
|
<span class="k">return</span> <span class="p">{</span> <span class="p">};</span>
|
|
<span class="p">}</span> <span class="p">);</span></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>BOOST_LEAF_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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">H</span><span class="p">></span>
|
|
<span class="n">context_type_from_handlers</span><span class="o"><</span><span class="n">H</span><span class="p">...</span><span class="o">></span> <span class="n">make_context</span><span class="p">()</span> <span class="k">noexcept</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="p">{</span> <span class="p">};</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">H</span><span class="p">></span>
|
|
<span class="n">context_type_from_handlers</span><span class="o"><</span><span class="n">H</span><span class="p">...</span><span class="o">></span> <span class="n">make_context</span><span class="p">(</span> <span class="n">H</span> <span class="o">&&</span> <span class="p">...</span> <span class="p">)</span> <span class="k">noexcept</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="p">{</span> <span class="p">};</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">auto</span> <span class="n">ctx</span> <span class="o">=</span> <span class="n">leaf</span><span class="o">::</span><span class="n">make_context</span><span class="p">(</span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
<span class="p">[](</span> <span class="n">e_this</span> <span class="p">)</span> <span class="p">{</span> <span class="p">....</span> <span class="p">},</span>
|
|
<span class="p">[](</span> <span class="n">e_that</span> <span class="p">)</span> <span class="p">{</span> <span class="p">....</span> <span class="p">}</span> <span class="p">);</span></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="new_error"><code>new_error</code></h3>
|
|
<div class="listingblock">
|
|
<div class="title">#include <boost/leaf/error.hpp></div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">Item</span><span class="p">></span>
|
|
<span class="n">error_id</span> <span class="n">new_error</span><span class="p">(</span><span class="n">Item</span> <span class="o">&&</span> <span class="p">...</span> <span class="n">item</span><span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="n">error_id</span> <span class="n">id</span> <span class="o">=</span> <span class="o"><<</span><span class="n">generate</span><span class="o">-</span><span class="k">new</span><span class="o">-</span><span class="n">unique</span><span class="o">-</span><span class="n">id</span><span class="o">>></span><span class="p">;</span>
|
|
<span class="k">return</span> <span class="n">id</span><span class="p">.</span><span class="n">load</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">forward</span><span class="o"><</span><span class="n">Item</span><span class="o">></span><span class="p">(</span><span class="n">item</span><span class="p">)...);</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">Item</span><span class="p">></span>
|
|
<span class="o"><<</span><span class="n">unspecified</span><span class="o">-</span><span class="n">type</span><span class="o">>></span> <span class="n">on_error</span><span class="p">(</span><span class="n">Item</span> <span class="o">&&</span> <span class="p">...</span> <span class="n">item</span><span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="n">err</span><span class="p">.</span><span class="n">load</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">forward</span><span class="o"><</span><span class="n">Item</span><span class="o">></span><span class="p">(</span><span class="n">item</span><span class="p">)...);</span></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="serialize"><code>serialize</code></h3>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">namespace</span> <span class="n">serialization</span>
|
|
<span class="p">{</span>
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Handle</span><span class="p">,</span> <span class="k">class</span> <span class="nc">E</span><span class="p">></span>
|
|
<span class="kt">void</span> <span class="n">serialize</span><span class="p">(</span> <span class="n">Handle</span> <span class="o">&</span><span class="p">,</span> <span class="n">E</span> <span class="k">const</span> <span class="o">&</span><span class="p">,</span> <span class="kt">char</span> <span class="k">const</span> <span class="o">*</span> <span class="n">name</span> <span class="p">);</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>serialize</code> function template is a user-defined customization point. If provided, it is called by the serialization system to output error objects; see <a href="#custom-writers">[custom-writers]</a>.</p>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="throw_exception"><code>throw_exception</code></h3>
|
|
<div class="listingblock">
|
|
<div class="title">#include <boost/leaf/exception.hpp></div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Ex</span><span class="p">,</span> <span class="k">class</span><span class="o">...</span> <span class="nc">E</span><span class="p">></span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
<span class="p">[[</span><span class="n">noreturn</span><span class="p">]]</span> <span class="kt">void</span> <span class="n">throw_exception</span><span class="p">(</span> <span class="n">Ex</span> <span class="o">&&</span> <span class="n">ex</span><span class="p">,</span> <span class="n">E</span> <span class="o">&&</span> <span class="p">...</span> <span class="n">e</span> <span class="p">);</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">E1</span><span class="p">,</span> <span class="k">class</span><span class="o">...</span> <span class="nc">E</span><span class="p">></span> <i class="conum" data-value="2"></i><b>(2)</b>
|
|
<span class="p">[[</span><span class="n">noreturn</span><span class="p">]]</span> <span class="kt">void</span> <span class="n">throw_exception</span><span class="p">(</span> <span class="n">E1</span> <span class="o">&&</span> <span class="n">e1</span><span class="p">,</span> <span class="n">E</span> <span class="o">&&</span> <span class="p">...</span> <span class="n">e</span> <span class="p">);</span>
|
|
|
|
<span class="p">[[</span><span class="n">noreturn</span><span class="p">]]</span> <span class="kt">void</span> <span class="n">throw_exception</span><span class="p">();</span> <i class="conum" data-value="3"></i><b>(3)</b>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Ex</span><span class="p">,</span> <span class="k">class</span><span class="o">...</span> <span class="nc">E</span><span class="p">></span> <i class="conum" data-value="4"></i><b>(4)</b>
|
|
<span class="p">[[</span><span class="n">noreturn</span><span class="p">]]</span> <span class="kt">void</span> <span class="n">throw_exception</span><span class="p">(</span> <span class="n">error_id</span> <span class="n">id</span><span class="p">,</span> <span class="n">Ex</span> <span class="o">&&</span> <span class="n">ex</span><span class="p">,</span> <span class="n">E</span> <span class="o">&&</span> <span class="p">...</span> <span class="n">e</span> <span class="p">);</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">E1</span><span class="p">,</span> <span class="k">class</span><span class="o">...</span> <span class="nc">E</span><span class="p">></span> <i class="conum" data-value="5"></i><b>(5)</b>
|
|
<span class="p">[[</span><span class="n">noreturn</span><span class="p">]]</span> <span class="kt">void</span> <span class="n">throw_exception</span><span class="p">(</span> <span class="n">error_id</span> <span class="n">id</span><span class="p">,</span> <span class="n">E1</span> <span class="o">&&</span> <span class="n">e1</span><span class="p">,</span> <span class="n">E</span> <span class="o">&&</span> <span class="p">...</span> <span class="n">e</span> <span class="p">);</span>
|
|
|
|
<span class="p">[[</span><span class="n">noreturn</span><span class="p">]]</span> <span class="kt">void</span> <span class="n">throw_exception</span><span class="p">(</span> <span class="n">error_id</span> <span class="n">id</span> <span class="p">);</span> <i class="conum" data-value="6"></i><b>(6)</b>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>throw_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. All overloads throw an exception:</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 thrown exception 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"><code>new_error</code></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 thrown exception 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"><code>new_error</code></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 function is invoked without arguments, the thrown exception 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"><code>new_error</code></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 thrown exception 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 thrown exception 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>throw_exception</code> is invoked with just an <code>error_id</code> object, the thrown exception 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 throw an exception object that is associated with a new <code>error_id</code>. The second three overloads throw 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="rouge highlight nowrap"><code data-lang="c++"><span class="k">struct</span> <span class="nc">my_exception</span><span class="o">:</span> <span class="n">std</span><span class="o">::</span><span class="n">exception</span> <span class="p">{</span> <span class="p">};</span>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">throw_exception</span><span class="p">(</span><span class="n">my_exception</span><span class="p">{});</span> <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="rouge highlight nowrap"><code data-lang="c++"><span class="k">enum</span> <span class="k">class</span> <span class="nc">my_error</span> <span class="p">{</span> <span class="n">e1</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">e2</span><span class="p">,</span> <span class="n">e3</span> <span class="p">};</span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">throw_exception</span><span class="p">(</span><span class="n">my_error</span><span class="o">::</span><span class="n">e1</span><span class="p">);</span></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_THROW_EXCEPTION"><code>BOOST_LEAF_THROW_EXCEPTION</code></a> instead of <code>leaf::throw_exception</code>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="to_variant"><code>to_variant</code></h3>
|
|
<div class="listingblock">
|
|
<div class="title">#include <boost/leaf/to_variant.hpp></div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">E</span><span class="p">,</span> <span class="k">class</span> <span class="nc">TryBlock</span><span class="p">></span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">variant</span><span class="o"><</span>
|
|
<span class="k">typename</span> <span class="n">std</span><span class="o">::</span><span class="n">decay</span><span class="o"><</span><span class="k">decltype</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">declval</span><span class="o"><</span><span class="n">TryBlock</span><span class="o">></span><span class="p">()().</span><span class="n">value</span><span class="p">())</span><span class="o">>::</span><span class="n">type</span><span class="p">,</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">tuple</span><span class="o"><</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">optional</span><span class="o"><</span><span class="n">E</span><span class="o">></span><span class="p">...</span><span class="o">>></span>
|
|
<span class="n">to_variant</span><span class="p">(</span> <span class="n">TryBlock</span> <span class="o">&&</span> <span class="n">try_block</span> <span class="p">);</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="dlist">
|
|
<dl>
|
|
<dt class="hdlist1">Requires: </dt>
|
|
<dd>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>This function is only available under C++-17 or newer.</p>
|
|
</li>
|
|
<li>
|
|
<p>The <code>try_block</code> function may not take any arguments.</p>
|
|
</li>
|
|
<li>
|
|
<p>The type 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"><code>result</code></a><T></code>, however this is not a requirement.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>to_variant</code> function uses <a href="#try_handle_all"><code>try_handle_all</code></a> internally to invoke the <code>try_block</code> and capture the result in a <code>std::variant</code>. On success, the variant contains the <code>T</code> object from the produced <code>result<T></code>. Otherwise, the variant contains a <code>std::tuple</code> where each <code>std::optional</code> element contains an object of type <code>E<sub>i</sub></code> from the user-supplied sequence <code>E…​</code>, or is empty if the failure did not produce an error object of that type.</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="title">Example:</div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">enum</span> <span class="k">class</span> <span class="nc">E1</span> <span class="p">{</span> <span class="n">e11</span><span class="p">,</span> <span class="n">e12</span><span class="p">,</span> <span class="n">e13</span> <span class="p">};</span>
|
|
<span class="k">enum</span> <span class="k">class</span> <span class="nc">E2</span> <span class="p">{</span> <span class="n">e21</span><span class="p">,</span> <span class="n">e22</span><span class="p">,</span> <span class="n">e23</span> <span class="p">};</span>
|
|
<span class="k">enum</span> <span class="k">class</span> <span class="nc">E3</span> <span class="p">{</span> <span class="n">e31</span><span class="p">,</span> <span class="n">e32</span><span class="p">,</span> <span class="n">e33</span> <span class="p">};</span>
|
|
|
|
<span class="p">....</span>
|
|
|
|
<span class="k">auto</span> <span class="n">v</span> <span class="o">=</span> <span class="n">leaf</span><span class="o">::</span><span class="n">to_variant</span><span class="o"><</span><span class="n">E1</span><span class="p">,</span> <span class="n">E2</span><span class="p">,</span> <span class="n">E3</span><span class="o">></span><span class="p">(</span>
|
|
<span class="p">[]()</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">int</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">leaf</span><span class="o">::</span><span class="n">new_error</span><span class="p">(</span> <span class="n">E1</span><span class="o">::</span><span class="n">e12</span><span class="p">,</span> <span class="n">E3</span><span class="o">::</span><span class="n">e33</span> <span class="p">);</span>
|
|
<span class="p">}</span> <span class="p">);</span>
|
|
|
|
<span class="n">assert</span><span class="p">(</span><span class="n">v</span><span class="p">.</span><span class="n">index</span><span class="p">()</span> <span class="o">==</span> <span class="mi">1</span><span class="p">);</span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
<span class="k">auto</span> <span class="n">t</span> <span class="o">=</span> <span class="n">std</span><span class="o">::</span><span class="n">get</span><span class="o"><</span><span class="mi">1</span><span class="o">></span><span class="p">(</span><span class="n">v</span><span class="p">);</span> <i class="conum" data-value="2"></i><b>(2)</b>
|
|
|
|
<span class="n">assert</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">get</span><span class="o"><</span><span class="mi">0</span><span class="o">></span><span class="p">(</span><span class="n">t</span><span class="p">).</span><span class="n">value</span><span class="p">()</span> <span class="o">==</span> <span class="n">E1</span><span class="o">::</span><span class="n">e12</span><span class="p">);</span> <i class="conum" data-value="3"></i><b>(3)</b>
|
|
<span class="n">assert</span><span class="p">(</span><span class="o">!</span><span class="n">std</span><span class="o">::</span><span class="n">get</span><span class="o"><</span><span class="mi">1</span><span class="o">></span><span class="p">(</span><span class="n">t</span><span class="p">).</span><span class="n">has_value</span><span class="p">());</span> <i class="conum" data-value="4"></i><b>(4)</b>
|
|
<span class="n">assert</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">get</span><span class="o"><</span><span class="mi">2</span><span class="o">></span><span class="p">(</span><span class="n">t</span><span class="p">).</span><span class="n">value</span><span class="p">()</span> <span class="o">==</span> <span class="n">E3</span><span class="o">::</span><span class="n">e33</span><span class="p">);</span> <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 report a failure, so the variant must contain the error object tuple, rather than an <code>int</code>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><i class="conum" data-value="2"></i><b>2</b></td>
|
|
<td>Grab the error tuple.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><i class="conum" data-value="3"></i><b>3</b></td>
|
|
<td>We communicated an <code>E1</code> and an <code>E3</code> error object…​</td>
|
|
</tr>
|
|
<tr>
|
|
<td><i class="conum" data-value="4"></i><b>4</b></td>
|
|
<td>…​but not an <code>E2</code> error object.</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="try_capture_all"><code>try_capture_all</code></h3>
|
|
<div class="listingblock">
|
|
<div class="title">#include <boost/leaf/handle_errors.hpp></div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="cp">#if BOOST_LEAF_CFG_CAPTURE
|
|
</span>
|
|
<span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">TryBlock</span><span class="p">></span>
|
|
<span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">></span> <span class="c1">// T deduced depending on TryBlock return type</span>
|
|
<span class="n">try_capture_all</span><span class="p">(</span> <span class="n">TryBlock</span> <span class="o">&&</span> <span class="n">try_block</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span>
|
|
|
|
<span class="cp">#endif</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="dlist">
|
|
<dl>
|
|
<dt class="hdlist1">Return type: </dt>
|
|
<dd>
|
|
<p>An instance of <code>leaf::<a href="#result"><code>result</code></a><T></code>, where T is deduced depending on the return type <code>R</code> of the <code>TryBlock</code>:</p>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>If <code>R</code> is a some type <code>Result<T></code> for which <a href="#is_result_type"><code>is_result_type</code></a> is true, <code>try_capture_all</code> returns <code>leaf::<a href="#result"><code>result</code></a><T></code>.</p>
|
|
</li>
|
|
<li>
|
|
<p>Otherwise it is assumed that the <code>TryBlock</code> reports errors by throwing exceptions, and the return value of <code>try_capture_all</code> is deduced as <code>leaf::result<R></code>.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</dd>
|
|
<dt class="hdlist1">Effects: </dt>
|
|
<dd>
|
|
<p><code>try_capture_all</code> executes <code>try_block</code>, catching and capturing all exceptions and all communicated error objects in the returned <code>leaf::result</code> object. The error objects are allocated dynamically.</p>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="admonitionblock warning">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<i class="fa icon-warning" title="Warning"></i>
|
|
</td>
|
|
<td class="content">
|
|
Calls to <code>try_capture_all</code> must not be nested in <code>try_handle_all</code>/<code>try_handle_some</code>/<code>try_catch</code> or in another <code>try_capture_all</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">
|
|
Under <code>BOOST_LEAF_CFG_CAPTURE=0</code>, <code>try_capture_all</code> is unavailable.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="dlist">
|
|
<dl>
|
|
<dt class="hdlist1">See also: </dt>
|
|
<dd>
|
|
<p><a href="#tutorial-async">Transporting Errors Between Threads</a>.</p>
|
|
</dd>
|
|
</dl>
|
|
</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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">TryBlock</span><span class="p">,</span> <span class="k">class</span><span class="o">...</span> <span class="nc">H</span><span class="p">></span>
|
|
<span class="k">typename</span> <span class="n">std</span><span class="o">::</span><span class="n">decay</span><span class="o"><</span><span class="k">decltype</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">declval</span><span class="o"><</span><span class="n">TryBlock</span><span class="o">></span><span class="p">()())</span><span class="o">>::</span><span class="n">type</span>
|
|
<span class="n">try_catch</span><span class="p">(</span> <span class="n">TryBlock</span> <span class="o">&&</span> <span class="n">try_block</span><span class="p">,</span> <span class="n">H</span> <span class="o">&&</span> <span class="p">...</span> <span class="n">h</span> <span class="p">);</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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 <a href="#tutorial-exception_handling">Exception Handling</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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">TryBlock</span><span class="p">,</span> <span class="k">class</span><span class="o">...</span> <span class="nc">H</span><span class="p">></span>
|
|
<span class="k">typename</span> <span class="n">std</span><span class="o">::</span><span class="n">decay</span><span class="o"><</span><span class="k">decltype</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">declval</span><span class="o"><</span><span class="n">TryBlock</span><span class="o">></span><span class="p">()().</span><span class="n">value</span><span class="p">())</span><span class="o">>::</span><span class="n">type</span>
|
|
<span class="n">try_handle_all</span><span class="p">(</span> <span class="n">TryBlock</span> <span class="o">&&</span> <span class="n">try_block</span><span class="p">,</span> <span class="n">H</span> <span class="o">&&</span> <span class="p">...</span> <span class="n">h</span> <span class="p">);</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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 <a href="#tutorial-error_handling">Error Handling</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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">TryBlock</span><span class="p">,</span> <span class="k">class</span><span class="o">...</span> <span class="nc">H</span><span class="p">></span>
|
|
<span class="k">typename</span> <span class="n">std</span><span class="o">::</span><span class="n">decay</span><span class="o"><</span><span class="k">decltype</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">declval</span><span class="o"><</span><span class="n">TryBlock</span><span class="o">></span><span class="p">()())</span><span class="o">>::</span><span class="n">type</span>
|
|
<span class="n">try_handle_some</span><span class="p">(</span> <span class="n">TryBlock</span> <span class="o">&&</span> <span class="n">try_block</span><span class="p">,</span> <span class="n">H</span> <span class="o">&&</span> <span class="p">...</span> <span class="n">h</span> <span class="p">);</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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"><code>result</code></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"><code>is_predicate</code></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="#diagnostic_details"><code>diagnostic_details</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"><code>context</code></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="rouge highlight nowrap"><code data-lang="c++"><span class="p">....</span>
|
|
<span class="k">auto</span> <span class="n">r</span> <span class="o">=</span> <span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_some</span><span class="p">(</span>
|
|
|
|
<span class="p">[]()</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">int</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">f</span><span class="p">();</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span><span class="n">leaf</span><span class="o">::</span><span class="n">e_file_name</span> <span class="k">const</span> <span class="o">&</span> <span class="n">fn</span><span class="p">)</span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"File Name: </span><span class="se">\"</span><span class="s">"</span> <span class="o"><<</span> <span class="n">fn</span><span class="p">.</span><span class="n">value</span> <span class="o"><<</span> <span class="sc">'"'</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span> <i class="conum" data-value="2"></i><b>(2)</b>
|
|
|
|
<span class="k">return</span> <span class="mi">1</span><span class="p">;</span>
|
|
<span class="p">}</span> <span class="p">);</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="p">....</span>
|
|
<span class="n">try_handle_some</span><span class="p">(</span>
|
|
|
|
<span class="p">[]()</span> <span class="o">-></span> <span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">int</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">f</span><span class="p">();</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span><span class="n">leaf</span><span class="o">::</span><span class="n">e_file_name</span> <span class="k">const</span> <span class="o">*</span> <span class="n">fn</span><span class="p">)</span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
<span class="p">{</span>
|
|
<span class="k">if</span><span class="p">(</span> <span class="n">fn</span> <span class="p">)</span> <i class="conum" data-value="2"></i><b>(2)</b>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"File Name: </span><span class="se">\"</span><span class="s">"</span> <span class="o"><<</span> <span class="n">fn</span><span class="o">-></span><span class="n">value</span> <span class="o"><<</span> <span class="sc">'"'</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
|
|
|
|
<span class="k">return</span> <span class="mi">1</span><span class="p">;</span>
|
|
<span class="p">}</span> <span class="p">);</span></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"><code>is_predicate</code></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="rouge highlight nowrap"><code data-lang="c++"><span class="p">....</span>
|
|
<span class="n">try_handle_some</span><span class="p">(</span>
|
|
|
|
<span class="p">[]</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">f</span><span class="p">();</span> <span class="c1">// returns leaf::result<T></span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span><span class="n">leaf</span><span class="o">::</span><span class="n">error_info</span> <span class="k">const</span> <span class="o">&</span> <span class="n">info</span><span class="p">)</span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"leaf::error_info:</span><span class="se">\n</span><span class="s">"</span> <span class="o"><<</span> <span class="n">info</span><span class="p">;</span> <i class="conum" data-value="2"></i><b>(2)</b>
|
|
<span class="k">return</span> <span class="n">info</span><span class="p">.</span><span class="n">error</span><span class="p">();</span> <i class="conum" data-value="3"></i><b>(3)</b>
|
|
<span class="p">}</span> <span class="p">);</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="p">....</span>
|
|
<span class="n">try_handle_some</span><span class="p">(</span>
|
|
|
|
<span class="p">[]</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">f</span><span class="p">();</span> <span class="c1">// throws</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span><span class="n">leaf</span><span class="o">::</span><span class="n">diagnostic_info</span> <span class="k">const</span> <span class="o">&</span> <span class="n">info</span><span class="p">)</span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"leaf::diagnostic_information:</span><span class="se">\n</span><span class="s">"</span> <span class="o"><<</span> <span class="n">info</span><span class="p">;</span> <i class="conum" data-value="2"></i><b>(2)</b>
|
|
<span class="k">return</span> <span class="n">info</span><span class="p">.</span><span class="n">error</span><span class="p">();</span> <i class="conum" data-value="3"></i><b>(3)</b>
|
|
<span class="p">}</span> <span class="p">);</span></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>diagnostic_details 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="rouge highlight nowrap"><code data-lang="c++"><span class="p">....</span>
|
|
<span class="n">try_handle_some</span><span class="p">(</span>
|
|
|
|
<span class="p">[]</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">f</span><span class="p">();</span> <span class="c1">// throws</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span><span class="n">leaf</span><span class="o">::</span><span class="n">diagnostic_details</span> <span class="k">const</span> <span class="o">&</span> <span class="n">info</span><span class="p">)</span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"leaf::diagnostic_details</span><span class="se">\n</span><span class="s">"</span> <span class="o"><<</span> <span class="n">info</span><span class="p">;</span> <i class="conum" data-value="2"></i><b>(2)</b>
|
|
<span class="k">return</span> <span class="n">info</span><span class="p">.</span><span class="n">error</span><span class="p">();</span> <i class="conum" data-value="3"></i><b>(3)</b>
|
|
<span class="p">}</span> <span class="p">);</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph text-right">
|
|
<p><a href="#result"><code>result</code></a> | <a href="#diagnostic_details"><code>diagnostic_details</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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">E</span><span class="p">></span>
|
|
<span class="k">class</span> <span class="nc">context</span>
|
|
<span class="p">{</span>
|
|
<span class="n">context</span><span class="p">(</span> <span class="n">context</span> <span class="k">const</span> <span class="o">&</span> <span class="p">)</span> <span class="o">=</span> <span class="k">delete</span><span class="p">;</span>
|
|
<span class="n">context</span> <span class="o">&</span> <span class="k">operator</span><span class="o">=</span><span class="p">(</span> <span class="n">context</span> <span class="k">const</span> <span class="o">&</span> <span class="p">)</span> <span class="o">=</span> <span class="k">delete</span><span class="p">;</span>
|
|
|
|
<span class="nl">public:</span>
|
|
|
|
<span class="n">context</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="n">context</span><span class="p">(</span> <span class="n">context</span> <span class="o">&&</span> <span class="n">x</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="o">~</span><span class="n">context</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="kt">void</span> <span class="n">activate</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="kt">void</span> <span class="n">deactivate</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="kt">bool</span> <span class="n">is_active</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="kt">void</span> <span class="n">unload</span><span class="p">(</span> <span class="n">error_id</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="kt">void</span> <span class="n">print</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">ostream</span> <span class="o">&</span> <span class="n">os</span> <span class="p">)</span> <span class="k">const</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">R</span><span class="p">,</span> <span class="k">class</span><span class="o">...</span> <span class="nc">H</span><span class="p">></span>
|
|
<span class="n">R</span> <span class="n">handle_error</span><span class="p">(</span> <span class="n">error_id</span><span class="p">,</span> <span class="n">H</span> <span class="o">&&</span> <span class="p">...</span> <span class="p">)</span> <span class="k">const</span><span class="p">;</span>
|
|
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">H</span><span class="p">></span>
|
|
<span class="k">using</span> <span class="n">context_type_from_handlers</span> <span class="o">=</span> <span class="k">typename</span> <span class="o"><<</span><span class="n">unspecified</span><span class="o">>>::</span><span class="n">type</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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::unload"><code>unload</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::unload"><code>unload</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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">E</span><span class="p">></span>
|
|
<span class="n">context</span><span class="o"><</span><span class="n">E</span><span class="p">...</span><span class="o">>::</span><span class="n">context</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">E</span><span class="p">></span>
|
|
<span class="n">context</span><span class="o"><</span><span class="n">E</span><span class="p">...</span><span class="o">>::</span><span class="n">context</span><span class="p">(</span> <span class="n">context</span> <span class="o">&&</span> <span class="n">x</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">E</span><span class="p">></span>
|
|
<span class="kt">void</span> <span class="n">context</span><span class="o"><</span><span class="n">E</span><span class="p">...</span><span class="o">>::</span><span class="n">activate</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="dlist">
|
|
<dl>
|
|
<dt class="hdlist1">Requires: </dt>
|
|
<dd>
|
|
<p><code>!<a href="#context::is_active"><code>is_active</code></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"><code>is_active</code></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">E</span><span class="p">></span>
|
|
<span class="kt">void</span> <span class="n">context</span><span class="o"><</span><span class="n">E</span><span class="p">...</span><span class="o">>::</span><span class="n">deactivate</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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"><code>is_active</code></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"><code>is_active</code></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">E</span><span class="p">></span>
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">R</span><span class="p">,</span> <span class="k">class</span><span class="o">...</span> <span class="nc">H</span><span class="p">></span>
|
|
<span class="n">R</span> <span class="n">context</span><span class="o"><</span><span class="n">E</span><span class="p">...</span><span class="o">>::</span><span class="n">handle_error</span><span class="p">(</span> <span class="n">error_id</span> <span class="n">err</span><span class="p">,</span> <span class="n">H</span> <span class="o">&&</span> <span class="p">...</span> <span class="n">h</span> <span class="p">)</span> <span class="k">const</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">E</span><span class="p">></span>
|
|
<span class="kt">bool</span> <span class="n">context</span><span class="o"><</span><span class="n">E</span><span class="p">...</span><span class="o">>::</span><span class="n">is_active</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">E</span><span class="p">></span>
|
|
<span class="kt">void</span> <span class="n">context</span><span class="o"><</span><span class="n">E</span><span class="p">...</span><span class="o">>::</span><span class="n">print</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">ostream</span> <span class="o">&</span> <span class="n">os</span> <span class="p">)</span> <span class="k">const</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">CharT</span><span class="p">,</span> <span class="k">class</span> <span class="nc">Traits</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="n">std</span><span class="o">::</span><span class="n">ostream</span> <span class="o">&</span> <span class="n">context</span><span class="o"><</span><span class="n">E</span><span class="p">...</span><span class="o">>::</span><span class="k">operator</span><span class="o"><<</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">basic_ostream</span><span class="o"><</span><span class="n">CharT</span><span class="p">,</span> <span class="n">Traits</span><span class="o">></span> <span class="o">&</span><span class="p">,</span> <span class="n">context</span> <span class="k">const</span> <span class="o">&</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="n">ctx</span><span class="p">.</span><span class="n">print</span><span class="p">(</span><span class="n">os</span><span class="p">);</span>
|
|
<span class="k">return</span> <span class="n">os</span><span class="p">;</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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::unload"><code>unload</code></h4>
|
|
<div class="listingblock">
|
|
<div class="title">#include <boost/leaf/context.hpp></div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">E</span><span class="p">></span>
|
|
<span class="kt">void</span> <span class="n">context</span><span class="o"><</span><span class="n">E</span><span class="p">...</span><span class="o">>::</span><span class="n">unload</span><span class="p">(</span> <span class="n">error_id</span> <span class="n">id</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="dlist">
|
|
<dl>
|
|
<dt class="hdlist1">Requires: </dt>
|
|
<dd>
|
|
<p><code>!<a href="#context::is_active"><code>is_active</code></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. Target objects are not overwritten if they are associated with the specified <code>id</code>, except if <code>id.value() == 0</code>.</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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Ctx</span><span class="p">></span>
|
|
<span class="k">class</span> <span class="nc">context_activator</span>
|
|
<span class="p">{</span>
|
|
<span class="n">context_activator</span><span class="p">(</span> <span class="n">context_activator</span> <span class="k">const</span> <span class="o">&</span> <span class="p">)</span> <span class="o">=</span> <span class="k">delete</span><span class="p">;</span>
|
|
<span class="n">context_activator</span> <span class="o">&</span> <span class="k">operator</span><span class="o">=</span><span class="p">(</span> <span class="n">context_activator</span> <span class="k">const</span> <span class="o">&</span> <span class="p">)</span> <span class="o">=</span> <span class="k">delete</span><span class="p">;</span>
|
|
|
|
<span class="nl">public:</span>
|
|
|
|
<span class="k">explicit</span> <span class="n">context_activator</span><span class="p">(</span> <span class="n">Ctx</span> <span class="o">&</span> <span class="n">ctx</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="n">context_activator</span><span class="p">(</span> <span class="n">context_activator</span> <span class="o">&&</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="o">~</span><span class="n">context_activator</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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>ctx.<a href="#context::is_active"><code>is_active</code></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>ctx.<a href="#context::activate"><code>activate</code></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>ctx.<a href="#context::deactivate"><code>deactivate</code></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_details"><code>diagnostic_details</code></h3>
|
|
<div class="listingblock">
|
|
<div class="title">#include <boost/leaf/diagnostics.hpp></div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">class</span> <span class="nc">diagnostic_details</span><span class="o">:</span> <span class="k">public</span> <span class="n">diagnostic_info</span>
|
|
<span class="p">{</span>
|
|
<span class="c1">//Constructors unspecified</span>
|
|
|
|
<span class="nl">public:</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Encoder</span><span class="p">></span>
|
|
<span class="kt">void</span> <span class="n">output_to</span><span class="p">(</span> <span class="n">Encoder</span> <span class="o">&</span> <span class="n">e</span> <span class="p">)</span> <span class="k">const</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">CharT</span><span class="p">,</span> <span class="k">class</span> <span class="nc">Traits</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="n">std</span><span class="o">::</span><span class="n">ostream</span> <span class="o">&</span> <span class="k">operator</span><span class="o"><<</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">basic_ostream</span><span class="o"><</span><span class="n">CharT</span><span class="p">,</span> <span class="n">Traits</span><span class="o">></span> <span class="o">&</span><span class="p">,</span> <span class="n">diagnostic_details</span> <span class="k">const</span> <span class="o">&</span> <span class="p">);</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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>diagnostic_details 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 (but see <a href="#show_in_diagnostics"><code>show_in_diagnostics</code></a>).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>output_to</code> member function is used with the serialization system; see <a href="#tutorial-serialization">Serialization</a>.</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_details</code> (and <a href="#diagnostic_info"><code>diagnostic_info</code></a>) is affected by the value of the macro <code>BOOST_LEAF_CFG_DIAGNOSTICS</code>:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>If it is 1 (the default), LEAF produces <code>diagnostic_details</code> but only if an active error handling context on the call stack takes an argument of type <code>diagnostic_details</code>;</p>
|
|
</li>
|
|
<li>
|
|
<p>If it is 0, the <code>diagnostic_details</code> functionality is stubbed out even for error handling contexts that take an argument of type <code>diagnostic_details</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>diagnostic_details</code> may allocate memory dynamically, but only if an active error handler takes an argument of type <code>diagnostic_details</code>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="diagnostic_info"><code>diagnostic_info</code></h3>
|
|
<div class="listingblock">
|
|
<div class="title">#include <boost/leaf/diagnostics.hpp></div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">class</span> <span class="nc">diagnostic_info</span><span class="o">:</span> <span class="k">public</span> <span class="n">error_info</span>
|
|
<span class="p">{</span>
|
|
<span class="c1">//Constructors unspecified</span>
|
|
|
|
<span class="nl">public:</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Encoder</span><span class="p">></span>
|
|
<span class="kt">void</span> <span class="n">output_to</span><span class="p">(</span> <span class="n">Encoder</span> <span class="o">&</span> <span class="n">e</span> <span class="p">)</span> <span class="k">const</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">CharT</span><span class="p">,</span> <span class="k">class</span> <span class="nc">Traits</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="n">std</span><span class="o">::</span><span class="n">ostream</span> <span class="o">&</span> <span class="k">operator</span><span class="o"><<</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">basic_ostream</span><span class="o"><</span><span class="n">CharT</span><span class="p">,</span> <span class="n">Traits</span><span class="o">></span> <span class="o">&</span><span class="p">,</span> <span class="n">diagnostic_info</span> <span class="k">const</span> <span class="o">&</span> <span class="p">);</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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="paragraph">
|
|
<p>The <code>output_to</code> member function is used with the serialization system; see <a href="#tutorial-serialization">Serialization</a>.</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="#diagnostic_details"><code>diagnostic_details</code></a>) is affected by the value of the macro <code>BOOST_LEAF_CFG_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>
|
|
</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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">class</span> <span class="nc">error_id</span>
|
|
<span class="p">{</span>
|
|
<span class="nl">public:</span>
|
|
|
|
<span class="n">error_id</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Enum</span><span class="p">></span>
|
|
<span class="n">error_id</span><span class="p">(</span> <span class="n">Enum</span> <span class="n">e</span><span class="p">,</span> <span class="k">typename</span> <span class="n">std</span><span class="o">::</span><span class="n">enable_if</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">is_error_code_enum</span><span class="o"><</span><span class="n">Enum</span><span class="o">>::</span><span class="n">value</span><span class="p">,</span> <span class="n">Enum</span><span class="o">>::</span><span class="n">type</span> <span class="o">*</span> <span class="o">=</span> <span class="mi">0</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="n">error_id</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">error_code</span> <span class="k">const</span> <span class="o">&</span> <span class="n">ec</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="kt">int</span> <span class="n">value</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="k">explicit</span> <span class="k">operator</span> <span class="kt">bool</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="n">std</span><span class="o">::</span><span class="n">error_code</span> <span class="n">to_error_code</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">friend</span> <span class="kt">bool</span> <span class="k">operator</span><span class="o">==</span><span class="p">(</span> <span class="n">error_id</span> <span class="n">a</span><span class="p">,</span> <span class="n">error_id</span> <span class="n">b</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="k">friend</span> <span class="kt">bool</span> <span class="k">operator</span><span class="o">!=</span><span class="p">(</span> <span class="n">error_id</span> <span class="n">a</span><span class="p">,</span> <span class="n">error_id</span> <span class="n">b</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="k">friend</span> <span class="kt">bool</span> <span class="k">operator</span><span class="o"><</span><span class="p">(</span> <span class="n">error_id</span> <span class="n">a</span><span class="p">,</span> <span class="n">error_id</span> <span class="n">b</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">Item</span><span class="p">></span>
|
|
<span class="n">error_id</span> <span class="n">load</span><span class="p">(</span> <span class="n">Item</span> <span class="o">&&</span> <span class="p">...</span> <span class="n">item</span> <span class="p">)</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">CharT</span><span class="p">,</span> <span class="k">class</span> <span class="nc">Traits</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="n">std</span><span class="o">::</span><span class="n">ostream</span> <span class="o">&</span> <span class="k">operator</span><span class="o"><<</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">basic_ostream</span><span class="o"><</span><span class="n">CharT</span><span class="p">,</span> <span class="n">Traits</span><span class="o">></span> <span class="o">&</span><span class="p">,</span> <span class="n">error_id</span> <span class="p">);</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="kt">bool</span> <span class="n">is_error_id</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">error_code</span> <span class="k">const</span> <span class="o">&</span> <span class="n">ec</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">E</span><span class="p">></span>
|
|
<span class="n">error_id</span> <span class="n">new_error</span><span class="p">(</span> <span class="n">E</span> <span class="o">&&</span> <span class="p">...</span> <span class="n">e</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="n">error_id</span> <span class="n">current_error</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="n">error_id</span><span class="o">::</span><span class="n">error_id</span><span class="p">()</span> <span class="k">noexcept</span> <span class="o">=</span> <span class="k">default</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Enum</span><span class="p">></span>
|
|
<span class="n">error_id</span><span class="o">::</span><span class="n">error_id</span><span class="p">(</span> <span class="n">Enum</span> <span class="n">e</span><span class="p">,</span> <span class="k">typename</span> <span class="n">std</span><span class="o">::</span><span class="n">enable_if</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">is_error_code_enum</span><span class="o"><</span><span class="n">Enum</span><span class="o">>::</span><span class="n">value</span><span class="p">,</span> <span class="n">Enum</span><span class="o">>::</span><span class="n">type</span> <span class="o">*</span> <span class="o">=</span> <span class="mi">0</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="n">error_id</span><span class="o">::</span><span class="n">error_id</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">error_code</span> <span class="k">const</span> <span class="o">&</span> <span class="n">ec</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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"><code>is_error_id</code></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="kt">bool</span> <span class="n">is_error_id</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">error_code</span> <span class="k">const</span> <span class="o">&</span> <span class="n">ec</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">Item</span><span class="p">></span>
|
|
<span class="n">error_id</span> <span class="n">error_id</span><span class="o">::</span><span class="n">load</span><span class="p">(</span> <span class="n">Item</span> <span class="o">&&</span> <span class="p">...</span> <span class="n">item</span> <span class="p">)</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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>this->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, that function is called to obtain an error object which is associated with <code>*this</code>, except in the special case of a <code>void</code> function, in which case it is invoked and no error object is obtained/loaded.</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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">friend</span> <span class="kt">bool</span> <span class="k">operator</span><span class="o">==</span><span class="p">(</span> <span class="n">error_id</span> <span class="n">a</span><span class="p">,</span> <span class="n">error_id</span> <span class="n">b</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="k">friend</span> <span class="kt">bool</span> <span class="k">operator</span><span class="o">!=</span><span class="p">(</span> <span class="n">error_id</span> <span class="n">a</span><span class="p">,</span> <span class="n">error_id</span> <span class="n">b</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="k">friend</span> <span class="kt">bool</span> <span class="k">operator</span><span class="o"><</span><span class="p">(</span> <span class="n">error_id</span> <span class="n">a</span><span class="p">,</span> <span class="n">error_id</span> <span class="n">b</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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> occurred 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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">explicit</span> <span class="n">error_id</span><span class="o">::</span><span class="k">operator</span> <span class="kt">bool</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="n">std</span><span class="o">::</span><span class="n">error_code</span> <span class="n">error_id</span><span class="o">::</span><span class="n">to_error_code</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="kt">int</span> <span class="n">error_id</span><span class="o">::</span><span class="n">value</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">class</span> <span class="nc">error_monitor</span>
|
|
<span class="p">{</span>
|
|
<span class="nl">public:</span>
|
|
|
|
<span class="n">error_monitor</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="n">error_id</span> <span class="n">check</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="n">error_id</span> <span class="n">assigned_error_id</span><span class="p">(</span> <span class="n">E</span> <span class="o">&&</span> <span class="p">...</span> <span class="n">e</span> <span class="p">)</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="n">error_code</span> <span class="n">compute_value</span><span class="p">(</span> <span class="kt">int</span> <span class="o">*</span> <span class="n">out_value</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="n">augmenter</span><span class="p">()</span> <span class="k">noexcept</span>
|
|
<span class="p">{</span>
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">error_monitor</span> <span class="n">cur_err</span><span class="p">;</span> <i class="conum" data-value="2"></i><b>(2)</b>
|
|
|
|
<span class="kt">int</span> <span class="n">val</span><span class="p">;</span>
|
|
<span class="k">auto</span> <span class="n">ec</span> <span class="o">=</span> <span class="n">compute_value</span><span class="p">(</span><span class="o">&</span><span class="n">val</span><span class="p">);</span>
|
|
|
|
<span class="k">if</span><span class="p">(</span> <span class="n">failure</span><span class="p">(</span><span class="n">ec</span><span class="p">)</span> <span class="p">)</span>
|
|
<span class="k">return</span> <span class="n">cur_err</span><span class="p">.</span><span class="n">assigned_error_id</span><span class="p">().</span><span class="n">load</span><span class="p">(</span><span class="n">e1</span><span class="p">,</span> <span class="n">e2</span><span class="p">,</span> <span class="p">...);</span> <i class="conum" data-value="3"></i><b>(3)</b>
|
|
<span class="k">else</span>
|
|
<span class="k">return</span> <span class="n">val</span><span class="p">;</span> <i class="conum" data-value="4"></i><b>(4)</b>
|
|
<span class="p">}</span></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 default-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 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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">struct</span> <span class="nc">e_api_function</span> <span class="p">{</span><span class="kt">char</span> <span class="k">const</span> <span class="o">*</span> <span class="n">value</span><span class="p">;};</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">struct</span> <span class="nc">e_at_line</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">value</span><span class="p">;</span> <span class="p">};</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">struct</span> <span class="nc">e_errno</span>
|
|
<span class="p">{</span>
|
|
<span class="kt">int</span> <span class="n">value</span><span class="p">;</span>
|
|
<span class="k">explicit</span> <span class="n">e_errno</span><span class="p">(</span><span class="kt">int</span> <span class="n">value</span><span class="o">=</span><span class="n">errno</span><span class="p">);</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">CharT</span><span class="p">,</span> <span class="k">class</span> <span class="nc">Traits</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="n">std</span><span class="o">::</span><span class="n">ostream</span> <span class="o">&</span> <span class="k">operator</span><span class="o"><<</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">basic_ostream</span><span class="o"><</span><span class="n">CharT</span><span class="p">,</span> <span class="n">Traits</span><span class="o">></span> <span class="o">&</span><span class="p">,</span> <span class="n">e_errno</span> <span class="k">const</span> <span class="o">&</span> <span class="p">);</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>By default, the constructor initializes <code>value</code> with <code>errno</code>, but the caller can pass a specific error code instead. When printed in automatically-generated diagnostic messages, <code>e_errno</code> objects use <code>strerror</code> to convert the error 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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">struct</span> <span class="nc">e_file_name</span> <span class="p">{</span> <span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">value</span><span class="p">;</span> <span class="p">};</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">namespace</span> <span class="n">windows</span>
|
|
<span class="p">{</span>
|
|
<span class="k">struct</span> <span class="nc">e_LastError</span>
|
|
<span class="p">{</span>
|
|
<span class="kt">unsigned</span> <span class="n">value</span><span class="p">;</span>
|
|
|
|
<span class="k">explicit</span> <span class="n">e_LastError</span><span class="p">(</span><span class="kt">unsigned</span> <span class="n">value</span><span class="p">);</span>
|
|
|
|
<span class="cp">#if BOOST_LEAF_CFG_WIN32
|
|
</span> <span class="n">e_LastError</span><span class="p">();</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">CharT</span><span class="p">,</span> <span class="k">class</span> <span class="nc">Traits</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="n">std</span><span class="o">::</span><span class="n">ostream</span> <span class="o">&</span> <span class="k">operator</span><span class="o"><<</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">basic_ostream</span><span class="o"><</span><span class="n">CharT</span><span class="p">,</span> <span class="n">Traits</span><span class="o">></span> <span class="o">&</span><span class="p">,</span> <span class="n">e_LastError</span> <span class="k">const</span> <span class="o">&</span> <span class="p">);</span>
|
|
<span class="cp">#endif
|
|
</span> <span class="p">};</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p><code>e_LastError</code> is designed to communicate <code>GetLastError()</code> values on Windows. The default constructor initializes <code>value</code> via <code>GetLastError()</code>. See <a href="#configuration">Configuration</a>.</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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">struct</span> <span class="nc">e_source_location</span>
|
|
<span class="p">{</span>
|
|
<span class="kt">char</span> <span class="k">const</span> <span class="o">*</span> <span class="n">file</span><span class="p">;</span>
|
|
<span class="kt">int</span> <span class="n">line</span><span class="p">;</span>
|
|
<span class="kt">char</span> <span class="k">const</span> <span class="o">*</span> <span class="n">function</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">CharT</span><span class="p">,</span> <span class="k">class</span> <span class="nc">Traits</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="n">std</span><span class="o">::</span><span class="n">ostream</span> <span class="o">&</span> <span class="k">operator</span><span class="o"><<</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">basic_ostream</span><span class="o"><</span><span class="n">CharT</span><span class="p">,</span> <span class="n">Traits</span><span class="o">></span> <span class="o">&</span><span class="p">,</span> <span class="n">e_source_location</span> <span class="k">const</span> <span class="o">&</span> <span class="p">);</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <a href="#BOOST_LEAF_NEW_ERROR"><code>BOOST_LEAF_NEW_ERROR</code></a> and <a href="#BOOST_LEAF_THROW_EXCEPTION"><code>BOOST_LEAF_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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">struct</span> <span class="nc">e_type_info_name</span> <span class="p">{</span> <span class="kt">char</span> <span class="k">const</span> <span class="o">*</span> <span class="n">value</span><span class="p">;</span> <span class="p">};</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">class</span> <span class="nc">error_info</span>
|
|
<span class="p">{</span>
|
|
<span class="c1">//Constructors unspecified</span>
|
|
|
|
<span class="nl">public:</span>
|
|
|
|
<span class="n">error_id</span> <span class="n">error</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="kt">bool</span> <span class="n">exception_caught</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">exception</span> <span class="k">const</span> <span class="o">*</span> <span class="n">exception</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Encoder</span><span class="p">></span>
|
|
<span class="kt">void</span> <span class="n">output_to</span><span class="p">(</span> <span class="n">Encoder</span> <span class="o">&</span> <span class="n">e</span> <span class="p">)</span> <span class="k">const</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">CharT</span><span class="p">,</span> <span class="k">class</span> <span class="nc">Traits</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="n">std</span><span class="o">::</span><span class="n">ostream</span> <span class="o">&</span> <span class="k">operator</span><span class="o"><<</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">basic_ostream</span><span class="o"><</span><span class="n">CharT</span><span class="p">,</span> <span class="n">Traits</span><span class="o">></span> <span class="o">&</span><span class="p">,</span> <span class="n">error_info</span> <span class="k">const</span> <span class="o">&</span> <span class="p">);</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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>
|
|
<div class="paragraph">
|
|
<p>The <code>output_to</code> member function is used with the serialization system; see <a href="#tutorial-serialization">Serialization</a>.</p>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="json_encoder_boost"><code>json_encoder_boost</code></h3>
|
|
<div class="listingblock">
|
|
<div class="title">#include <boost/leaf/serialization/json_encoder_boost.hpp></div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">namespace</span> <span class="n">serialization</span>
|
|
<span class="p">{</span>
|
|
<span class="k">struct</span> <span class="nc">json_encoder_boost</span>
|
|
<span class="p">{</span>
|
|
<span class="n">boost</span><span class="o">::</span><span class="n">json</span><span class="o">::</span><span class="n">value</span> <span class="o">&</span> <span class="n">v_</span><span class="p">;</span>
|
|
|
|
<span class="c1">// Enabled if x is assignable to boost::json::value, or</span>
|
|
<span class="c1">// if tag_invoke is defined for boost::json::value_from_tag.</span>
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="kt">void</span> <span class="n">output</span><span class="p">(</span> <span class="n">json_encoder_boost</span> <span class="o">&</span><span class="p">,</span> <span class="n">T</span> <span class="k">const</span> <span class="o">&</span> <span class="n">x</span> <span class="p">);</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="kt">void</span> <span class="n">output_at</span><span class="p">(</span> <span class="n">json_encoder_boost</span> <span class="o">&</span><span class="p">,</span> <span class="n">T</span> <span class="k">const</span> <span class="o">&</span><span class="p">,</span> <span class="kt">char</span> <span class="k">const</span> <span class="o">*</span> <span class="n">name</span> <span class="p">);</span>
|
|
<span class="p">};</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>json_encoder_boost</code> type serializes error objects to JSON format using <a href="https://www.boost.org/doc/libs/release/libs/json/">Boost.JSON</a>. The <code>output</code> function is enabled for:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>Types directly assignable to <code>boost::json::value</code></p>
|
|
</li>
|
|
<li>
|
|
<p>Types for which a <code>tag_invoke</code> overload for <code>value_from_tag</code> can be found via ADL</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>See <a href="#tutorial-serialization">Serialization</a>.</p>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="json_encoder_nlohmann"><code>json_encoder_nlohmann</code></h3>
|
|
<div class="listingblock">
|
|
<div class="title">#include <boost/leaf/serialization/json_encoder_nlohmann.hpp></div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">namespace</span> <span class="n">serialization</span>
|
|
<span class="p">{</span>
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Json</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">json_encoder_nlohmann</span>
|
|
<span class="p">{</span>
|
|
<span class="n">Json</span> <span class="o">&</span> <span class="n">j_</span><span class="p">;</span>
|
|
|
|
<span class="c1">// Enabled if to_json is available for Json and T.</span>
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="kt">void</span> <span class="n">output</span><span class="p">(</span> <span class="n">json_encoder_nlohmann</span> <span class="o">&</span><span class="p">,</span> <span class="n">T</span> <span class="k">const</span> <span class="o">&</span> <span class="n">x</span> <span class="p">);</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="kt">void</span> <span class="n">output_at</span><span class="p">(</span> <span class="n">json_encoder_nlohmann</span> <span class="o">&</span><span class="p">,</span> <span class="n">T</span> <span class="k">const</span> <span class="o">&</span><span class="p">,</span> <span class="kt">char</span> <span class="k">const</span> <span class="o">*</span> <span class="n">name</span> <span class="p">);</span>
|
|
<span class="p">};</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>json_encoder_nlohmann</code> type serializes error objects to JSON format using unqualified calls to <code>to_json</code>. This is compatible with <a href="https://github.com/nlohmann/json">nlohmann/json</a>; See <a href="#tutorial-serialization">Serialization</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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="k">class</span> <span class="nc">result</span>
|
|
<span class="p">{</span>
|
|
<span class="nl">public:</span>
|
|
|
|
<span class="k">using</span> <span class="n">value_type</span> <span class="o">=</span> <span class="n">T</span><span class="p">;</span>
|
|
|
|
<span class="c1">// NOTE: Copy constructor implicitly deleted.</span>
|
|
<span class="n">result</span><span class="p">(</span> <span class="n">result</span> <span class="o">&&</span> <span class="n">r</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">U</span><span class="p">,</span> <span class="k">class</span> <span class="o">=</span> <span class="k">typename</span> <span class="nc">std</span><span class="o">::</span><span class="n">enable_if</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">is_convertible</span><span class="o"><</span><span class="n">U</span><span class="p">,</span> <span class="n">T</span><span class="p">></span><span class="o">::</span><span class="n">value</span><span class="o">>::</span><span class="n">type</span><span class="o">></span>
|
|
<span class="n">result</span><span class="p">(</span> <span class="n">result</span><span class="o"><</span><span class="n">U</span><span class="o">></span> <span class="o">&&</span> <span class="n">r</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="n">result</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="n">result</span><span class="p">(</span> <span class="n">T</span> <span class="o">&&</span> <span class="n">v</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="n">result</span><span class="p">(</span> <span class="n">T</span> <span class="k">const</span> <span class="o">&</span> <span class="n">v</span> <span class="p">);</span>
|
|
|
|
<span class="n">result</span><span class="p">(</span> <span class="n">error_id</span> <span class="n">err</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">U</span><span class="p">,</span> <span class="k">class</span> <span class="o">=</span> <span class="k">typename</span> <span class="nc">std</span><span class="o">::</span><span class="n">enable_if</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">is_convertible</span><span class="o"><</span><span class="n">U</span><span class="p">,</span> <span class="n">T</span><span class="p">></span><span class="o">::</span><span class="n">value</span><span class="o">>::</span><span class="n">type</span><span class="o">></span>
|
|
<span class="n">result</span><span class="p">(</span> <span class="n">U</span> <span class="o">&&</span> <span class="n">u</span> <span class="p">);</span>
|
|
|
|
<span class="cp">#if BOOST_LEAF_CFG_STD_SYSTEM_ERROR
|
|
</span>
|
|
<span class="n">result</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">error_code</span> <span class="k">const</span> <span class="o">&</span> <span class="n">ec</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Enum</span><span class="p">,</span> <span class="k">class</span> <span class="o">=</span> <span class="k">typename</span> <span class="nc">std</span><span class="o">::</span><span class="n">enable_if</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">is_error_code_enum</span><span class="o"><</span><span class="n">Enum</span><span class="p">></span><span class="o">::</span><span class="n">value</span><span class="p">,</span> <span class="kt">int</span><span class="o">>::</span><span class="n">type</span><span class="o">></span>
|
|
<span class="n">result</span><span class="p">(</span> <span class="n">Enum</span> <span class="n">e</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="cp">#endif
|
|
</span>
|
|
<span class="c1">// NOTE: Assignment operator implicitly deleted.</span>
|
|
<span class="n">result</span> <span class="o">&</span> <span class="k">operator</span><span class="o">=</span><span class="p">(</span> <span class="n">result</span> <span class="o">&&</span> <span class="n">r</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">U</span><span class="p">,</span> <span class="k">class</span> <span class="o">=</span> <span class="k">typename</span> <span class="nc">std</span><span class="o">::</span><span class="n">enable_if</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">is_convertible</span><span class="o"><</span><span class="n">U</span><span class="p">,</span> <span class="n">T</span><span class="p">></span><span class="o">::</span><span class="n">value</span><span class="o">>::</span><span class="n">type</span><span class="o">></span>
|
|
<span class="n">result</span> <span class="o">&</span> <span class="k">operator</span><span class="o">=</span><span class="p">(</span> <span class="n">result</span><span class="o"><</span><span class="n">U</span><span class="o">></span> <span class="o">&&</span> <span class="n">r</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="kt">bool</span> <span class="n">has_value</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="kt">bool</span> <span class="n">has_error</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="k">explicit</span> <span class="k">operator</span> <span class="kt">bool</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="n">T</span> <span class="k">const</span> <span class="o">&</span> <span class="n">value</span><span class="p">()</span> <span class="k">const</span> <span class="o">&</span><span class="p">;</span>
|
|
<span class="n">T</span> <span class="o">&</span> <span class="n">value</span><span class="p">()</span> <span class="o">&</span><span class="p">;</span>
|
|
<span class="n">T</span> <span class="k">const</span> <span class="o">&&</span> <span class="n">value</span><span class="p">()</span> <span class="k">const</span> <span class="o">&&</span><span class="p">;</span>
|
|
<span class="n">T</span> <span class="o">&&</span> <span class="n">value</span><span class="p">()</span> <span class="o">&&</span><span class="p">;</span>
|
|
|
|
<span class="n">T</span> <span class="k">const</span> <span class="o">*</span> <span class="k">operator</span><span class="o">-></span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="n">T</span> <span class="o">*</span> <span class="k">operator</span><span class="o">-></span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="n">T</span> <span class="k">const</span> <span class="o">&</span> <span class="k">operator</span><span class="o">*</span><span class="p">()</span> <span class="k">const</span> <span class="o">&</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="n">T</span> <span class="o">&</span> <span class="k">operator</span><span class="o">*</span><span class="p">()</span> <span class="o">&</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="n">T</span> <span class="k">const</span> <span class="o">&&</span> <span class="k">operator</span><span class="o">*</span><span class="p">()</span> <span class="k">const</span> <span class="o">&&</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="n">T</span> <span class="o">&&</span> <span class="k">operator</span><span class="o">*</span><span class="p">()</span> <span class="o">&&</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="o"><<</span><span class="n">unspecified</span><span class="o">-</span><span class="n">type</span><span class="o">>></span> <span class="n">error</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">Item</span><span class="p">></span>
|
|
<span class="n">error_id</span> <span class="n">load</span><span class="p">(</span> <span class="n">Item</span> <span class="o">&&</span> <span class="p">...</span> <span class="n">item</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="kt">void</span> <span class="n">unload</span><span class="p">();</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Encoder</span><span class="p">></span>
|
|
<span class="kt">void</span> <span class="n">output_to</span><span class="p">(</span> <span class="n">Encoder</span> <span class="o">&</span> <span class="n">e</span> <span class="p">)</span> <span class="k">const</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">CharT</span><span class="p">,</span> <span class="k">class</span> <span class="nc">Traits</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="n">std</span><span class="o">::</span><span class="n">ostream</span> <span class="o">&</span> <span class="k">operator</span><span class="o"><<</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">basic_ostream</span><span class="o"><</span><span class="n">CharT</span><span class="p">,</span> <span class="n">Traits</span><span class="o">></span> <span class="o">&</span><span class="p">,</span> <span class="n">result</span> <span class="k">const</span> <span class="o">&</span> <span class="p">);</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="p">></span>
|
|
<span class="k">class</span> <span class="nc">result</span><span class="o"><</span><span class="kt">void</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="nl">public:</span>
|
|
|
|
<span class="k">using</span> <span class="n">value_type</span> <span class="o">=</span> <span class="kt">void</span><span class="p">;</span>
|
|
|
|
<span class="c1">// NOTE: Copy constructor implicitly deleted.</span>
|
|
<span class="n">result</span><span class="p">(</span> <span class="n">result</span> <span class="o">&&</span> <span class="n">r</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="n">result</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="n">result</span><span class="p">(</span> <span class="n">error_id</span> <span class="n">err</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="cp">#if BOOST_LEAF_CFG_STD_SYSTEM_ERROR
|
|
</span>
|
|
<span class="n">result</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">error_code</span> <span class="k">const</span> <span class="o">&</span> <span class="n">ec</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Enum</span><span class="p">,</span> <span class="k">typename</span> <span class="nc">std</span><span class="o">::</span><span class="n">enable_if</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">is_error_code_enum</span><span class="o"><</span><span class="n">Enum</span><span class="p">></span><span class="o">::</span><span class="n">value</span><span class="p">,</span> <span class="n">Enum</span><span class="o">>::</span><span class="n">type</span><span class="o">></span>
|
|
<span class="n">result</span><span class="p">(</span> <span class="n">Enum</span> <span class="n">e</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="cp">#endif
|
|
</span>
|
|
<span class="c1">// NOTE: Assignment operator implicitly deleted.</span>
|
|
<span class="n">result</span> <span class="o">&</span> <span class="k">operator</span><span class="o">=</span><span class="p">(</span> <span class="n">result</span> <span class="o">&&</span> <span class="n">r</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">explicit</span> <span class="k">operator</span> <span class="kt">bool</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="kt">void</span> <span class="n">value</span><span class="p">()</span> <span class="k">const</span><span class="p">;</span>
|
|
|
|
<span class="kt">void</span> <span class="k">const</span> <span class="o">*</span> <span class="k">operator</span><span class="o">-></span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="kt">void</span> <span class="o">*</span> <span class="k">operator</span><span class="o">-></span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="kt">void</span> <span class="k">operator</span><span class="o">*</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="o"><<</span><span class="n">unspecified</span><span class="o">-</span><span class="n">type</span><span class="o">>></span> <span class="n">error</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">Item</span><span class="p">></span>
|
|
<span class="n">error_id</span> <span class="n">load</span><span class="p">(</span> <span class="n">Item</span> <span class="o">&&</span> <span class="p">...</span> <span class="n">item</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="kt">void</span> <span class="n">unload</span><span class="p">();</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Encoder</span><span class="p">></span>
|
|
<span class="kt">void</span> <span class="n">output_to</span><span class="p">(</span> <span class="n">Encoder</span> <span class="o">&</span> <span class="n">e</span> <span class="p">)</span> <span class="k">const</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">CharT</span><span class="p">,</span> <span class="k">class</span> <span class="nc">Traits</span><span class="p">></span>
|
|
<span class="k">friend</span> <span class="n">std</span><span class="o">::</span><span class="n">ostream</span> <span class="o">&</span> <span class="k">operator</span><span class="o"><<</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">basic_ostream</span><span class="o"><</span><span class="n">CharT</span><span class="p">,</span> <span class="n">Traits</span><span class="o">></span> <span class="o">&</span><span class="p">,</span> <span class="n">result</span> <span class="k">const</span> <span class="o">&</span><span class="p">);</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">struct</span> <span class="nc">bad_result</span><span class="o">:</span> <span class="n">std</span><span class="o">::</span><span class="n">exception</span> <span class="p">{</span> <span class="p">};</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">is_result_type</span><span class="o"><</span><span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">>>:</span> <span class="n">std</span><span class="o">::</span><span class="n">true_type</span>
|
|
<span class="p">{</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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::has_value"><code>has_value</code></a> | <a href="#result::has_error"><code>has_error</code></a> | <a href="#result::operator_bool"><code>operator bool</code></a> | <a href="#result::value"><code>value</code></a> | <a href="#result::operator_ptr"><code>operator-></code></a> | <a href="#result::operator_deref"><code>operator*</code></a> | <a href="#result::error"><code>error</code></a> | <a href="#result::load"><code>load</code></a> | <a href="#result::output_to"><code>output_to</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 <a href="#result::value"><code>value</code></a> / <a href="#result::operator_deref"><code>operator*</code></a> / <a href="#result::operator_ptr"><code>operator-></code></a> can be used to access the contained value.</p>
|
|
</li>
|
|
<li>
|
|
<p>Error state, in which case it contains an error ID, and calling <a href="#result::value"><code>value</code></a> throws <code>leaf::bad_result</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p>Dynamic capture state, which is the same as the Error state, but in addition to the error ID, it holds a list of dynamically captured error objects; see <a href="#try_capture_all"><code>try_capture_all</code></a>.</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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="c1">// NOTE: Copy constructor implicitly deleted.</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">>::</span><span class="n">result</span><span class="p">(</span> <span class="n">result</span> <span class="o">&&</span> <span class="n">r</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">U</span><span class="p">,</span> <span class="k">class</span> <span class="o">=</span> <span class="k">typename</span> <span class="nc">std</span><span class="o">::</span><span class="n">enable_if</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">is_convertible</span><span class="o"><</span><span class="n">U</span><span class="p">,</span> <span class="n">T</span><span class="p">></span><span class="o">::</span><span class="n">value</span><span class="o">>::</span><span class="n">type</span><span class="o">></span>
|
|
<span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">>::</span><span class="n">result</span><span class="p">(</span> <span class="n">result</span><span class="o"><</span><span class="n">U</span><span class="o">></span> <span class="o">&&</span> <span class="n">r</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">>::</span><span class="n">result</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">>::</span><span class="n">result</span><span class="p">(</span> <span class="n">T</span> <span class="o">&&</span> <span class="n">v</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">>::</span><span class="n">result</span><span class="p">(</span> <span class="n">T</span> <span class="k">const</span> <span class="o">&</span> <span class="n">v</span> <span class="p">);</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">>::</span><span class="n">result</span><span class="p">(</span> <span class="n">error_id</span> <span class="n">err</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">U</span><span class="p">,</span> <span class="k">class</span> <span class="o">=</span> <span class="k">typename</span> <span class="nc">std</span><span class="o">::</span><span class="n">enable_if</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">is_convertible</span><span class="o"><</span><span class="n">U</span><span class="p">,</span> <span class="n">T</span><span class="p">></span><span class="o">::</span><span class="n">value</span><span class="o">>::</span><span class="n">type</span><span class="o">></span>
|
|
<span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">>::</span><span class="n">result</span><span class="p">(</span> <span class="n">U</span> <span class="o">&&</span> <span class="n">u</span> <span class="p">);</span>
|
|
|
|
<span class="cp">#if BOOST_LEAF_CFG_STD_SYSTEM_ERROR
|
|
</span>
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">>::</span><span class="n">result</span><span class="p">(</span> <span class="n">std</span><span class="o">::</span><span class="n">error_code</span> <span class="k">const</span> <span class="o">&</span> <span class="n">ec</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Enum</span><span class="p">,</span> <span class="k">class</span> <span class="o">=</span> <span class="k">typename</span> <span class="nc">std</span><span class="o">::</span><span class="n">enable_if</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">is_error_code_enum</span><span class="o"><</span><span class="n">Enum</span><span class="p">></span><span class="o">::</span><span class="n">value</span><span class="p">,</span> <span class="kt">int</span><span class="o">>::</span><span class="n">type</span><span class="o">></span>
|
|
<span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">>::</span><span class="n">result</span><span class="p">(</span> <span class="n">Enum</span> <span class="n">e</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="cp">#endif
|
|
</span>
|
|
<span class="p">}</span> <span class="p">}</span></code></pre>
|
|
</div>
|
|
</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> invariants:</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">dynamic capture state</a>, call <a href="#try_capture_all"><code>try_capture_all</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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">E</span><span class="p">></span>
|
|
<span class="o"><<</span><span class="n">unspecified</span><span class="o">-</span><span class="n">type</span><span class="o">>></span> <span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">>::</span><span class="n">error</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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::has_error"><code>has_error</code></h4>
|
|
<div class="listingblock">
|
|
<div class="title">#include <boost/leaf/result.hpp></div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="kt">bool</span> <span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">>::</span><span class="n">has_error</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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>false</code>, otherwise returns <code>true</code>.</p>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="result::has_value"><code>has_value</code></h4>
|
|
<div class="listingblock">
|
|
<div class="title">#include <boost/leaf/result.hpp></div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="kt">bool</span> <span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">>::</span><span class="n">has_value</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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::load"><code>load</code></h4>
|
|
<div class="listingblock">
|
|
<div class="title">#include <boost/leaf/result.hpp></div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">Item</span><span class="p">></span>
|
|
<span class="n">error_id</span> <span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">>::</span><span class="n">load</span><span class="p">(</span> <span class="n">Item</span> <span class="o">&&</span> <span class="p">...</span> <span class="n">item</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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_bool"><code>operator bool</code></h4>
|
|
<div class="listingblock">
|
|
<div class="title">#include <boost/leaf/result.hpp></div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">>::</span><span class="k">operator</span> <span class="kt">bool</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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::operator_deref"><code>operator*</code></h4>
|
|
<div class="listingblock">
|
|
<div class="title">#include <boost/leaf/result.hpp></div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="n">T</span> <span class="k">const</span> <span class="o">&</span> <span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">>::</span><span class="k">operator</span><span class="o">*</span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="n">T</span> <span class="o">&</span> <span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">>::</span><span class="k">operator</span><span class="o">*</span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="dlist">
|
|
<dl>
|
|
<dt class="hdlist1">Requires: </dt>
|
|
<dd>
|
|
<p><code>*this</code> must be in <a href="#result">value state</a>.</p>
|
|
</dd>
|
|
<dt class="hdlist1">Returns </dt>
|
|
<dd>
|
|
<p>a reference to the stored value.</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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">></span> <span class="o">&</span> <span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">>::</span><span class="k">operator</span><span class="o">=</span><span class="p">(</span> <span class="n">result</span> <span class="o">&&</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">U</span><span class="p">></span>
|
|
<span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">></span> <span class="o">&</span> <span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">>::</span><span class="k">operator</span><span class="o">=</span><span class="p">(</span> <span class="n">result</span><span class="o"><</span><span class="n">U</span><span class="o">></span> <span class="o">&&</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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_ptr"><code>operator-></code></h4>
|
|
<div class="listingblock">
|
|
<div class="title">#include <boost/leaf/result.hpp></div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="n">T</span> <span class="k">const</span> <span class="o">*</span> <span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">>::</span><span class="k">operator</span><span class="o">-></span><span class="p">()</span> <span class="k">const</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="n">T</span> <span class="o">*</span> <span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">>::</span><span class="k">operator</span><span class="o">-></span><span class="p">()</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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 a pointer to the stored value; otherwise returns <code>nullptr</code>.</p>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="result::value"><code>value</code></h4>
|
|
<div class="listingblock">
|
|
<div class="title">#include <boost/leaf/result.hpp></div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="kt">void</span> <span class="n">result</span><span class="o"><</span><span class="kt">void</span><span class="o">>::</span><span class="n">value</span><span class="p">()</span> <span class="k">const</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="n">T</span> <span class="k">const</span> <span class="o">&</span> <span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">>::</span><span class="n">value</span><span class="p">()</span> <span class="k">const</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="n">T</span> <span class="o">&</span> <span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">>::</span><span class="n">value</span><span class="p">();</span>
|
|
|
|
<span class="k">struct</span> <span class="nc">bad_result</span><span class="o">:</span> <span class="n">std</span><span class="o">::</span><span class="n">exception</span> <span class="p">{</span> <span class="p">};</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Effects:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>If <code>*this</code> is in <a href="#result">value state</a>, returns a reference to the stored value.</p>
|
|
</li>
|
|
<li>
|
|
<p>If <code>*this</code> is in <a href="#result">dynamic capture state</a>, the captured error objects are unloaded, and:</p>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>If <code>*this</code> contains a captured exception object <code>ex</code>, the behavior is equivalent to <code><a href="#throw_exception"><code>throw_exception</code></a>(ex)</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p>Otherwise, the behavior is equivalent to <code><a href="#throw_exception"><code>throw_exception</code></a>(bad_result{})</code>.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<p>If <code>*this</code> is in any other state, the behavior is equivalent to <code><a href="#throw_exception"><code>throw_exception</code></a>(bad_result{})</code>.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="result::value_type"><code>value_type</code></h4>
|
|
<div class="paragraph">
|
|
<p>A member type of <code>result<T></code>, defined as a synonym for <code>T</code>.</p>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="result::output_to"><code>output_to</code></h4>
|
|
<div class="listingblock">
|
|
<div class="title">#include <boost/leaf/result.hpp></div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Encoder</span><span class="p">></span>
|
|
<span class="kt">void</span> <span class="n">result</span><span class="o"><</span><span class="n">T</span><span class="o">>::</span><span class="n">output_to</span><span class="p">(</span> <span class="n">Encoder</span> <span class="o">&</span> <span class="n">e</span> <span class="p">)</span> <span class="k">const</span><span class="p">;</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The <code>output_to</code> member function is used with the serialization system; see <a href="#tutorial-serialization">Serialization</a>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If the result is in <a href="#result">value state</a>, outputs the value. If it is in <a href="#result">error state</a>, outputs the <a href="#error_id"><code>error_id</code></a>. If the result holds <a href="#try_capture_all">captured error objects</a>, outputs them as well.</p>
|
|
</div>
|
|
<div class="admonitionblock note">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<i class="fa icon-note" title="Note"></i>
|
|
</td>
|
|
<td class="content">
|
|
Result objects carry error objects only when in <a href="#try_capture_all">capture state</a>. Otherwise, to output error objects, use <code>output_to</code> on <a href="#diagnostic_details"><code>diagnostic_details</code></a> in an error handling scope.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="show_in_diagnostics"><code>show_in_diagnostics</code></h3>
|
|
<div class="listingblock">
|
|
<div class="title">#include <boost/leaf/handle_errors.hpp></div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">E</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">show_in_diagnostics</span><span class="o">:</span> <span class="n">std</span><span class="o">::</span><span class="n">true_type</span>
|
|
<span class="p">{</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>This template can be specialized to prevent error objects of sensitive types from appearing in automatically generated diagnostic messages. Example:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">struct</span> <span class="nc">e_user_name</span>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">value</span><span class="p">;</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">show_in_diagnostics</span><span class="o"><</span><span class="n">e_user_name</span><span class="o">>:</span> <span class="n">std</span><span class="o">::</span><span class="n">false_type</span>
|
|
<span class="p">{</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></code></pre>
|
|
</div>
|
|
</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"><code>is_predicate</code></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">enum</span> <span class="k">class</span> <span class="nc">my_error</span> <span class="p">{</span> <span class="n">e1</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span> <span class="n">e2</span><span class="p">,</span> <span class="n">e3</span> <span class="p">};</span>
|
|
|
|
<span class="k">struct</span> <span class="nc">my_pred</span>
|
|
<span class="p">{</span>
|
|
<span class="k">using</span> <span class="n">error_type</span> <span class="o">=</span> <span class="n">my_error</span><span class="p">;</span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
|
|
<span class="k">static</span> <span class="kt">bool</span> <span class="n">evaluate</span><span class="p">(</span><span class="n">my_error</span><span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span> <i class="conum" data-value="2"></i><b>(2)</b>
|
|
|
|
<span class="n">my_error</span> <span class="n">matched</span><span class="p">;</span> <i class="conum" data-value="3"></i><b>(3)</b>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">is_predicate</span><span class="o"><</span><span class="n">my_pred</span><span class="o">>:</span> <span class="n">std</span><span class="o">::</span><span class="n">true_type</span>
|
|
<span class="p">{</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">struct</span> <span class="nc">my_pred</span>
|
|
<span class="p">{</span>
|
|
<span class="k">using</span> <span class="n">error_type</span> <span class="o">=</span> <span class="n">leaf</span><span class="o">::</span><span class="n">e_errno</span><span class="p">;</span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
|
|
<span class="k">static</span> <span class="kt">bool</span> <span class="n">evaluate</span><span class="p">(</span><span class="n">leaf</span><span class="o">::</span><span class="n">e_errno</span> <span class="k">const</span> <span class="o">&</span><span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span> <i class="conum" data-value="2"></i><b>(2)</b>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">e_errno</span> <span class="k">const</span> <span class="o">&</span> <span class="n">matched</span><span class="p">;</span> <i class="conum" data-value="3"></i><b>(3)</b>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">is_predicate</span><span class="o"><</span><span class="n">my_pred</span><span class="o">>:</span> <span class="n">std</span><span class="o">::</span><span class="n">true_type</span>
|
|
<span class="p">{</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">Ex</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">catch_</span>
|
|
<span class="p">{</span>
|
|
<span class="n">std</span><span class="o">::</span><span class="n">exception</span> <span class="k">const</span> <span class="o">&</span> <span class="n">matched</span><span class="p">;</span>
|
|
|
|
<span class="c1">// Other members not specified</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">Ex</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">catch_</span><span class="o"><</span><span class="n">Ex</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="n">Ex</span> <span class="k">const</span> <span class="o">&</span> <span class="n">matched</span><span class="p">;</span>
|
|
|
|
<span class="c1">// Other members not specified</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span><span class="o">...</span> <span class="nc">Ex</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">is_predicate</span><span class="o"><</span><span class="n">catch_</span><span class="o"><</span><span class="n">Ex</span><span class="p">...</span><span class="o">>>:</span> <span class="n">std</span><span class="o">::</span><span class="n">true_type</span>
|
|
<span class="p">{</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">struct</span> <span class="nc">ex1</span><span class="o">:</span> <span class="n">std</span><span class="o">::</span><span class="n">exception</span> <span class="p">{</span> <span class="p">};</span>
|
|
<span class="k">struct</span> <span class="nc">ex2</span><span class="o">:</span> <span class="n">std</span><span class="o">::</span><span class="n">exception</span> <span class="p">{</span> <span class="p">};</span>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">try_catch</span><span class="p">(</span>
|
|
|
|
<span class="p">[]</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">f</span><span class="p">();</span> <span class="c1">// throws</span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span><span class="n">leaf</span><span class="o">::</span><span class="n">catch_</span><span class="o"><</span><span class="n">ex1</span><span class="p">,</span> <span class="n">ex2</span><span class="o">></span> <span class="n">c</span><span class="p">)</span>
|
|
<span class="p">{</span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
<span class="n">assert</span><span class="p">(</span><span class="k">dynamic_cast</span><span class="o"><</span><span class="n">ex1</span> <span class="k">const</span> <span class="o">*></span><span class="p">(</span><span class="o">&</span><span class="n">c</span><span class="p">.</span><span class="n">matched</span><span class="p">)</span> <span class="o">||</span> <span class="k">dynamic_cast</span><span class="o"><</span><span class="n">ex2</span> <span class="k">const</span> <span class="o">*></span><span class="p">(</span><span class="o">&</span><span class="n">c</span><span class="p">.</span><span class="n">matched</span><span class="p">));</span>
|
|
<span class="p">....</span>
|
|
<span class="p">}</span> <span class="p">);</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">struct</span> <span class="nc">ex1</span><span class="o">:</span> <span class="n">std</span><span class="o">::</span><span class="n">exception</span> <span class="p">{</span> <span class="p">};</span>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_some</span><span class="p">(</span>
|
|
|
|
<span class="p">[]</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">f</span><span class="p">();</span> <span class="c1">// returns leaf::result<T></span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span><span class="n">ex1</span> <span class="o">&</span> <span class="n">e</span><span class="p">)</span>
|
|
<span class="p">{</span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
<span class="p">....</span>
|
|
<span class="p">}</span> <span class="p">);</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">P</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">if_not</span>
|
|
<span class="p">{</span>
|
|
<span class="o"><<</span><span class="n">deduced</span><span class="o">>></span> <span class="n">matched</span><span class="p">;</span>
|
|
|
|
<span class="c1">// Other members not specified</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">P</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">is_predicate</span><span class="o"><</span><span class="n">if_not</span><span class="o"><</span><span class="n">P</span><span class="o">>>:</span> <span class="n">std</span><span class="o">::</span><span class="n">true_type</span>
|
|
<span class="p">{</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">enum</span> <span class="k">class</span> <span class="nc">my_enum</span> <span class="p">{</span> <span class="n">e1</span><span class="p">,</span> <span class="n">e2</span><span class="p">,</span> <span class="n">e3</span> <span class="p">};</span>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_some</span><span class="p">(</span>
|
|
|
|
<span class="p">[]</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">f</span><span class="p">();</span> <span class="c1">// returns leaf::result<T></span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">leaf</span><span class="o">::</span><span class="n">if_not</span><span class="o"><</span><span class="n">leaf</span><span class="o">::</span><span class="n">match</span><span class="o"><</span><span class="n">my_enum</span><span class="p">,</span> <span class="n">my_enum</span><span class="o">::</span><span class="n">e1</span><span class="p">,</span> <span class="n">my_enum</span><span class="o">::</span><span class="n">e2</span><span class="o">>></span> <span class="p">)</span>
|
|
<span class="p">{</span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
<span class="p">....</span>
|
|
<span class="p">}</span> <span class="p">);</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">E</span><span class="p">,</span> <span class="k">auto</span><span class="p">...</span> <span class="n">V</span><span class="p">></span>
|
|
<span class="k">class</span> <span class="nc">match</span>
|
|
<span class="p">{</span>
|
|
<span class="o"><<</span><span class="n">deduced</span><span class="o">>></span> <span class="n">matched</span><span class="p">;</span>
|
|
|
|
<span class="c1">// Other members not specified</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">E</span><span class="p">,</span> <span class="k">auto</span><span class="p">...</span> <span class="n">V</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">is_predicate</span><span class="o"><</span><span class="n">match</span><span class="o"><</span><span class="n">E</span><span class="p">,</span> <span class="n">V</span><span class="p">...</span><span class="o">>>:</span> <span class="n">std</span><span class="o">::</span><span class="n">true_type</span>
|
|
<span class="p">{</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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>Where <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 then <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="rouge highlight nowrap"><code data-lang="c++"><span class="k">enum</span> <span class="k">class</span> <span class="nc">my_enum</span> <span class="p">{</span> <span class="n">e1</span><span class="p">,</span> <span class="n">e2</span><span class="p">,</span> <span class="n">e3</span> <span class="p">};</span>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_some</span><span class="p">(</span>
|
|
|
|
<span class="p">[]</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">f</span><span class="p">();</span> <span class="c1">// returns leaf::result<T></span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">leaf</span><span class="o">::</span><span class="n">match</span><span class="o"><</span><span class="n">my_enum</span><span class="p">,</span> <span class="n">my_enum</span><span class="o">::</span><span class="n">e1</span><span class="p">,</span> <span class="n">my_enum</span><span class="o">::</span><span class="n">e2</span><span class="o">></span> <span class="n">m</span> <span class="p">)</span>
|
|
<span class="p">{</span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
<span class="k">static_assert</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">is_same</span><span class="o"><</span><span class="n">my_enum</span><span class="p">,</span> <span class="k">decltype</span><span class="p">(</span><span class="n">m</span><span class="p">.</span><span class="n">matched</span><span class="p">)</span><span class="o">>::</span><span class="n">value</span><span class="p">);</span>
|
|
<span class="n">assert</span><span class="p">(</span><span class="n">m</span><span class="p">.</span><span class="n">matched</span> <span class="o">==</span> <span class="n">my_enum</span><span class="o">::</span><span class="n">e1</span> <span class="o">||</span> <span class="n">m</span><span class="p">.</span><span class="n">matched</span> <span class="o">==</span> <span class="n">my_enum</span><span class="o">::</span><span class="n">e2</span><span class="p">);</span>
|
|
<span class="p">....</span>
|
|
<span class="p">}</span> <span class="p">);</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">enum</span> <span class="k">class</span> <span class="nc">my_enum</span> <span class="p">{</span> <span class="n">e1</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">e2</span><span class="p">,</span> <span class="n">e3</span> <span class="p">};</span>
|
|
|
|
<span class="k">namespace</span> <span class="n">std</span>
|
|
<span class="p">{</span>
|
|
<span class="k">template</span> <span class="o"><</span><span class="p">></span> <span class="k">struct</span> <span class="nc">is_error_code_enum</span><span class="o"><</span><span class="n">my_enum</span><span class="o">>:</span> <span class="n">std</span><span class="o">::</span><span class="n">true_type</span> <span class="p">{</span> <span class="p">};</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_some</span><span class="p">(</span>
|
|
|
|
<span class="p">[]</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">f</span><span class="p">();</span> <span class="c1">// returns leaf::result<T></span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">leaf</span><span class="o">::</span><span class="n">match</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">error_code</span><span class="p">,</span> <span class="n">my_enum</span><span class="o">::</span><span class="n">e1</span><span class="p">,</span> <span class="n">my_enum</span><span class="o">::</span><span class="n">e2</span><span class="o">></span> <span class="n">m</span> <span class="p">)</span>
|
|
<span class="p">{</span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
<span class="k">static_assert</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">is_same</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">error_code</span> <span class="k">const</span> <span class="o">&</span><span class="p">,</span> <span class="k">decltype</span><span class="p">(</span><span class="n">m</span><span class="p">.</span><span class="n">matched</span><span class="p">)</span><span class="o">>::</span><span class="n">value</span><span class="p">);</span>
|
|
<span class="n">assert</span><span class="p">(</span><span class="n">m</span><span class="p">.</span><span class="n">matched</span> <span class="o">==</span> <span class="n">my_enum</span><span class="o">::</span><span class="n">e1</span> <span class="o">||</span> <span class="n">m</span><span class="p">.</span><span class="n">matched</span> <span class="o">==</span> <span class="n">my_enum</span><span class="o">::</span><span class="n">e2</span><span class="p">);</span>
|
|
<span class="p">....</span>
|
|
<span class="p">}</span> <span class="p">);</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">enum</span> <span class="k">class</span> <span class="nc">enum_a</span> <span class="p">{</span> <span class="n">a1</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">a2</span><span class="p">,</span> <span class="n">a3</span> <span class="p">};</span>
|
|
<span class="k">enum</span> <span class="k">class</span> <span class="nc">enum_b</span> <span class="p">{</span> <span class="n">b1</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">b2</span><span class="p">,</span> <span class="n">b3</span> <span class="p">};</span>
|
|
|
|
<span class="k">namespace</span> <span class="n">std</span>
|
|
<span class="p">{</span>
|
|
<span class="k">template</span> <span class="o"><</span><span class="p">></span> <span class="k">struct</span> <span class="nc">is_error_code_enum</span><span class="o"><</span><span class="n">enum_a</span><span class="o">>:</span> <span class="n">std</span><span class="o">::</span><span class="n">true_type</span> <span class="p">{</span> <span class="p">};</span>
|
|
<span class="k">template</span> <span class="o"><</span><span class="p">></span> <span class="k">struct</span> <span class="nc">is_error_code_enum</span><span class="o"><</span><span class="n">enum_b</span><span class="o">>:</span> <span class="n">std</span><span class="o">::</span><span class="n">true_type</span> <span class="p">{</span> <span class="p">};</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_some</span><span class="p">(</span>
|
|
|
|
<span class="p">[]</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">f</span><span class="p">();</span> <span class="c1">// returns leaf::result<T></span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">leaf</span><span class="o">::</span><span class="n">match</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">error_code</span><span class="p">,</span> <span class="n">leaf</span><span class="o">::</span><span class="n">category</span><span class="o"><</span><span class="n">enum_a</span><span class="o">></span><span class="p">,</span> <span class="n">enum_b</span><span class="o">::</span><span class="n">b2</span><span class="o">></span> <span class="n">m</span> <span class="p">)</span>
|
|
<span class="p">{</span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
<span class="k">static_assert</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">is_same</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">error_code</span> <span class="k">const</span> <span class="o">&</span><span class="p">,</span> <span class="k">decltype</span><span class="p">(</span><span class="n">m</span><span class="p">.</span><span class="n">matched</span><span class="p">)</span><span class="o">>::</span><span class="n">value</span><span class="p">);</span>
|
|
<span class="n">assert</span><span class="p">(</span><span class="o">&</span><span class="n">m</span><span class="p">.</span><span class="n">matched</span><span class="p">.</span><span class="n">category</span><span class="p">()</span> <span class="o">==</span> <span class="o">&</span><span class="n">std</span><span class="o">::</span><span class="n">error_code</span><span class="p">(</span><span class="n">enum_a</span><span class="p">{}).</span><span class="n">category</span><span class="p">()</span> <span class="o">||</span> <span class="n">m</span><span class="p">.</span><span class="n">matched</span> <span class="o">==</span> <span class="n">enum_b</span><span class="o">::</span><span class="n">b2</span><span class="p">);</span>
|
|
<span class="p">....</span>
|
|
<span class="p">}</span> <span class="p">);</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">enum</span> <span class="k">class</span> <span class="nc">my_enum</span> <span class="p">{</span> <span class="n">e1</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">e2</span><span class="p">,</span> <span class="n">e3</span> <span class="p">};</span>
|
|
|
|
<span class="k">namespace</span> <span class="n">std</span>
|
|
<span class="p">{</span>
|
|
<span class="k">template</span> <span class="o"><</span><span class="p">></span> <span class="k">struct</span> <span class="nc">is_error_code_enum</span><span class="o"><</span><span class="n">my_enum</span><span class="o">>:</span> <span class="n">std</span><span class="o">::</span><span class="n">true_type</span> <span class="p">{</span> <span class="p">};</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_some</span><span class="p">(</span>
|
|
|
|
<span class="p">[]</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">f</span><span class="p">();</span> <span class="c1">// returns leaf::result<T></span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">leaf</span><span class="o">::</span><span class="n">match</span><span class="o"><</span><span class="n">leaf</span><span class="o">::</span><span class="n">condition</span><span class="o"><</span><span class="n">my_enum</span><span class="o">></span><span class="p">,</span> <span class="n">my_enum</span><span class="o">::</span><span class="n">e1</span><span class="p">,</span> <span class="n">my_enum</span><span class="o">::</span><span class="n">e2</span><span class="o">></span> <span class="n">m</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="k">static_assert</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">is_same</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">error_code</span> <span class="k">const</span> <span class="o">&</span><span class="p">,</span> <span class="k">decltype</span><span class="p">(</span><span class="n">m</span><span class="p">.</span><span class="n">matched</span><span class="p">)</span><span class="o">>::</span><span class="n">value</span><span class="p">);</span>
|
|
<span class="n">assert</span><span class="p">(</span><span class="n">m</span><span class="p">.</span><span class="n">matched</span> <span class="o">==</span> <span class="n">my_enum</span><span class="o">::</span><span class="n">e1</span> <span class="o">||</span> <span class="n">m</span><span class="p">.</span><span class="n">matched</span> <span class="o">==</span> <span class="n">my_enum</span><span class="o">::</span><span class="n">e2</span><span class="p">);</span>
|
|
<span class="p">....</span>
|
|
<span class="p">}</span> <span class="p">);</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">struct</span> <span class="nc">severity</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">value</span><span class="p">;</span> <span class="p">};</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="kt">int</span> <span class="n">S</span><span class="p">></span>
|
|
<span class="k">constexpr</span> <span class="kt">bool</span> <span class="n">severity_greater_than</span><span class="p">(</span> <span class="n">severity</span> <span class="k">const</span> <span class="o">&</span> <span class="n">e</span> <span class="p">)</span> <span class="k">noexcept</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">e</span><span class="p">.</span><span class="n">value</span> <span class="o">></span> <span class="n">S</span><span class="p">;</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_some</span><span class="p">(</span>
|
|
|
|
<span class="p">[]</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">f</span><span class="p">();</span> <span class="c1">// returns leaf::result<T></span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">leaf</span><span class="o">::</span><span class="n">match</span><span class="o"><</span><span class="n">severity</span><span class="p">,</span> <span class="n">severity_greater_than</span><span class="o"><</span><span class="mi">4</span><span class="o">>></span> <span class="n">m</span> <span class="p">)</span>
|
|
<span class="p">{</span>
|
|
<span class="k">static_assert</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">is_same</span><span class="o"><</span><span class="n">severity</span> <span class="k">const</span> <span class="o">&</span><span class="p">,</span> <span class="k">decltype</span><span class="p">(</span><span class="n">m</span><span class="p">.</span><span class="n">matched</span><span class="p">)</span><span class="o">>::</span><span class="n">value</span><span class="p">);</span>
|
|
<span class="n">assert</span><span class="p">(</span><span class="n">m</span><span class="p">.</span><span class="n">matched</span><span class="p">.</span><span class="n">value</span> <span class="o">></span> <span class="mi">4</span><span class="p">);</span>
|
|
<span class="p">....</span>
|
|
<span class="p">}</span> <span class="p">);</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">auto</span><span class="p">,</span> <span class="k">auto</span><span class="p">...</span> <span class="n">V</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">match_member</span><span class="p">;</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">E</span><span class="p">,</span> <span class="k">class</span> <span class="nc">T</span><span class="p">,</span> <span class="n">T</span> <span class="n">E</span><span class="o">::*</span> <span class="n">P</span><span class="p">,</span> <span class="k">auto</span><span class="p">...</span> <span class="n">V</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">match_member</span><span class="o"><</span><span class="n">P</span><span class="p">,</span> <span class="n">V</span><span class="p">...</span><span class="o">></span>
|
|
<span class="p">{</span>
|
|
<span class="n">E</span> <span class="k">const</span> <span class="o">&</span> <span class="n">matched</span><span class="p">;</span>
|
|
|
|
<span class="c1">// Other members not specified</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">auto</span> <span class="n">P</span><span class="p">,</span> <span class="k">auto</span><span class="p">...</span> <span class="n">V</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">is_predicate</span><span class="o"><</span><span class="n">match_member</span><span class="o"><</span><span class="n">P</span><span class="p">,</span> <span class="n">V</span><span class="p">...</span><span class="o">>>:</span> <span class="n">std</span><span class="o">::</span><span class="n">true_type</span>
|
|
<span class="p">{</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">E</span><span class="p">,</span> <span class="k">auto</span><span class="p">...</span> <span class="n">V</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">match_value</span>
|
|
<span class="p">{</span>
|
|
<span class="n">E</span> <span class="k">const</span> <span class="o">&</span> <span class="n">matched</span><span class="p">;</span>
|
|
|
|
<span class="c1">// Other members not specified</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">E</span><span class="p">,</span> <span class="k">auto</span><span class="p">...</span> <span class="n">V</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">is_predicate</span><span class="o"><</span><span class="n">match_value</span><span class="o"><</span><span class="n">E</span><span class="p">,</span> <span class="n">V</span><span class="p">...</span><span class="o">>>:</span> <span class="n">std</span><span class="o">::</span><span class="n">true_type</span>
|
|
<span class="p">{</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">struct</span> <span class="nc">e_errno</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">value</span><span class="p">;</span> <span class="p">}</span>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">try_handle_some</span><span class="p">(</span>
|
|
|
|
<span class="p">[]</span>
|
|
<span class="p">{</span>
|
|
<span class="k">return</span> <span class="n">f</span><span class="p">();</span> <span class="c1">// returns leaf::result<T></span>
|
|
<span class="p">},</span>
|
|
|
|
<span class="p">[](</span> <span class="n">leaf</span><span class="o">::</span><span class="n">match_value</span><span class="o"><</span><span class="n">e_errno</span><span class="p">,</span> <span class="n">ENOENT</span><span class="o">></span> <span class="n">m</span> <span class="p">)</span>
|
|
<span class="p">{</span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
<span class="k">static_assert</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">is_same</span><span class="o"><</span><span class="n">e_errno</span> <span class="k">const</span> <span class="o">&</span><span class="p">,</span> <span class="k">decltype</span><span class="p">(</span><span class="n">m</span><span class="p">.</span><span class="n">matched</span><span class="p">)</span><span class="o">>::</span><span class="n">value</span><span class="p">);</span>
|
|
<span class="n">assert</span><span class="p">(</span><span class="n">m</span><span class="p">.</span><span class="n">matched</span><span class="p">.</span><span class="n">value</span> <span class="o">==</span> <span class="n">ENOENT</span><span class="p">);</span>
|
|
<span class="p">....</span>
|
|
<span class="p">}</span> <span class="p">);</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">is_predicate</span><span class="o">:</span> <span class="n">std</span><span class="o">::</span><span class="n">false_type</span>
|
|
<span class="p">{</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">R</span><span class="p">></span>
|
|
<span class="k">struct</span> <span class="nc">is_result_type</span><span class="o">:</span> <span class="n">std</span><span class="o">::</span><span class="n">false_type</span>
|
|
<span class="p">{</span>
|
|
<span class="p">};</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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"><code>result</code></a><T></code> class template satisfies these requirements. In addition, it allows error objects to be transported across thread boundaries, using a <a href="#try_capture_all"><code>try_capture_all</code></a>.</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_ASSIGN"><code>BOOST_LEAF_ASSIGN</code></h3>
|
|
<div class="listingblock">
|
|
<div class="title">#include <boost/leaf/error.hpp></div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="cp">#define BOOST_LEAF_ASSIGN(v, r)\
|
|
auto && <<temp>> = r;\
|
|
if( !<<temp>> )\
|
|
return <<temp>>.error();\
|
|
v = std::forward<decltype(<<temp>>)>(<<temp>>).value()</span></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>BOOST_LEAF_AUTO</code></a>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="BOOST_LEAF_AUTO"><code>BOOST_LEAF_AUTO</code></h3>
|
|
<div class="listingblock">
|
|
<div class="title">#include <boost/leaf/error.hpp></div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="cp">#define BOOST_LEAF_AUTO(v, r)\
|
|
BOOST_LEAF_ASSIGN(auto v, r)</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph text-right">
|
|
<p><a href="#BOOST_LEAF_ASSIGN"><code>BOOST_LEAF_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="rouge highlight nowrap"><code data-lang="c++"><span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="n">compute_value</span><span class="p">();</span>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">float</span><span class="o">></span> <span class="n">add_values</span><span class="p">()</span>
|
|
<span class="p">{</span>
|
|
<span class="n">BOOST_LEAF_AUTO</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span> <span class="n">compute_value</span><span class="p">());</span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
<span class="n">BOOST_LEAF_AUTO</span><span class="p">(</span><span class="n">v2</span><span class="p">,</span> <span class="n">compute_value</span><span class="p">());</span> <i class="conum" data-value="2"></i><b>(2)</b>
|
|
<span class="k">return</span> <span class="n">v1</span> <span class="o">+</span> <span class="n">v2</span><span class="p">;</span>
|
|
<span class="p">}</span></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>BOOST_LEAF_ASSIGN</code></a>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="BOOST_LEAF_CHECK"><code>BOOST_LEAF_CHECK</code></h3>
|
|
<div class="listingblock">
|
|
<div class="title">#include <boost/leaf/error.hpp></div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="cp">#if BOOST_LEAF_CFG_GNUC_STMTEXPR
|
|
</span>
|
|
<span class="cp">#define BOOST_LEAF_CHECK(r)\
|
|
({\
|
|
auto && <<temp>> = (r);\
|
|
if( !<<temp>> )\
|
|
return <<temp>>.error();\
|
|
std::move(<<temp>>);\
|
|
}).value()
|
|
</span>
|
|
<span class="cp">#else
|
|
</span>
|
|
<span class="cp">#define BOOST_LEAF_CHECK(r)\
|
|
{\
|
|
auto && <<temp>> = (r);\
|
|
if( !<<temp>> )\
|
|
return <<temp>>.error();\
|
|
}
|
|
</span>
|
|
<span class="cp">#endif</span></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="rouge highlight nowrap"><code data-lang="c++"><span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">void</span><span class="o">></span> <span class="n">send_message</span><span class="p">(</span> <span class="kt">char</span> <span class="k">const</span> <span class="o">*</span> <span class="n">msg</span> <span class="p">);</span>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="n">compute_value</span><span class="p">();</span>
|
|
|
|
<span class="n">leaf</span><span class="o">::</span><span class="n">result</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="n">say_hello_and_compute_value</span><span class="p">()</span>
|
|
<span class="p">{</span>
|
|
<span class="n">BOOST_LEAF_CHECK</span><span class="p">(</span><span class="n">send_message</span><span class="p">(</span><span class="s">"Hello!"</span><span class="p">));</span> <i class="conum" data-value="1"></i><b>(1)</b>
|
|
<span class="k">return</span> <span class="n">compute_value</span><span class="p">();</span>
|
|
<span class="p">}</span></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>
|
|
<div class="paragraph">
|
|
<p>If <code>BOOST_LEAF_CFG_GNUC_STMTEXPR</code> is <code>1</code> (which is the default under <code>__GNUC__</code>), <code>BOOST_LEAF_CHECK</code> expands to a <a href="https://gcc.gnu.org/onlinedocs/gcc/Statement-Exprs.html">GNU C statement expression</a>, which allows its use with non-<code>void</code> result types in any expression; see <a href="#checking_for_errors">Checking for Errors</a>.</p>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="BOOST_LEAF_THROW_EXCEPTION"><code>BOOST_LEAF_THROW_EXCEPTION</code></h3>
|
|
<div class="listingblock">
|
|
<div class="title">#include <boost/leaf/exception.hpp></div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="cp">#define BOOST_LEAF_THROW_EXCEPTION <<exact-dedfinition-unspecified>></span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="dlist">
|
|
<dl>
|
|
<dt class="hdlist1">Effects: </dt>
|
|
<dd>
|
|
<p><code>BOOST_LEAF_THROW_EXCEPTION(e…​)</code> is equivalent to <code>leaf::<a href="#throw_exception"><code>throw_exception</code></a>(e…​)</code>, except the current source location is automatically communicated with the thrown exception, 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="sect2">
|
|
<h3 id="BOOST_LEAF_NEW_ERROR"><code>BOOST_LEAF_NEW_ERROR</code></h3>
|
|
<div class="listingblock">
|
|
<div class="title">#include <boost/leaf/error.hpp></div>
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="cp">#define BOOST_LEAF_NEW_ERROR <<exact-definition-unspecified>></span></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"><code>new_error</code></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>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="configuration">Configuration</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_CFG_DIAGNOSTICS</code>: Defining this macro as <code>0</code> stubs out both <a href="#diagnostic_info"><code>diagnostic_info</code></a> and <a href="#diagnostic_details"><code>diagnostic_details</code></a> (if the macro is left undefined, LEAF defines it as <code>1</code>).</p>
|
|
</li>
|
|
<li>
|
|
<p><code>BOOST_LEAF_CFG_STD_SYSTEM_ERROR</code>: Defining this macro as <code>0</code> disables the <code>std::error_code</code> / <code>std::error_condition</code> integration. In this case LEAF does not <code>#include <system_error></code>, which may be too heavy for embedded platforms (if the macro is left undefined, LEAF defines it as <code>1</code>).</p>
|
|
</li>
|
|
<li>
|
|
<p><code>BOOST_LEAF_CFG_STD_STRING</code>: Defining this macro as <code>0</code> disables all use of <code>std::string</code> (this requires <code>BOOST_LEAF_CFG_DIAGNOSTICS=0</code> as well). In this case LEAF does not <code>#include <string></code> which may be too heavy for embedded platforms (if the macro is left undefined, LEAF defines it as <code>1</code>).</p>
|
|
</li>
|
|
<li>
|
|
<p><code>BOOST_LEAF_CFG_CAPTURE</code>: Defining this macro as <code>0</code> disables <a href="#try_capture_all"><code>try_capture_all</code></a>, which (only if used) allocates memory dynamically (if the macro is left undefined, LEAF defines it as <code>1</code>).</p>
|
|
</li>
|
|
<li>
|
|
<p><code>BOOST_LEAF_CFG_GNUC_STMTEXPR</code>: This macro controls whether or not <a href="#BOOST_LEAF_CHECK"><code>BOOST_LEAF_CHECK</code></a> is defined in terms of a <a href="https://gcc.gnu.org/onlinedocs/gcc/Statement-Exprs.html">GNU C statement expression</a>, which enables its use to check for errors similarly to how the questionmark operator works in some languages (see <a href="#checking_for_errors">Checking for Errors</a>). By default the macro is defined as <code>1</code> under <code>__GNUC__</code>, otherwise as <code>0</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>BOOST_LEAF_CFG_WIN32</code>: This macro controls the use of Win32 APIs. If left undefined, LEAF defines it as <code>0</code> (even on Windows, since including <code>windows.h</code> is generally not desirable). The possible values are:</p>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p><code>0</code>: Disables all Win32-specific features.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>1</code>: Includes <code>windows.h</code> and enables <a href="#e_LastError"><code>e_LastError</code></a> support, which is otherwise stubbed out.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>2</code>: In addition, switches LEAF to using the Win32 TLS API instead of C++11 <code>thread_local</code>, enabling error objects to be used across DLL boundaries.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<p><code>BOOST_LEAF_NO_EXCEPTIONS</code>: Disables all exception handling support. If left undefined, LEAF defines it automatically based on the compiler configuration (e.g. <code>-fno-exceptions</code>).</p>
|
|
</li>
|
|
<li>
|
|
<p><code>BOOST_LEAF_NO_THREADS</code>: Disables all thread safety in LEAF.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="configuring_tls_access">Configuring TLS Access</h3>
|
|
<div class="paragraph">
|
|
<p>LEAF requires support for thread-local <code>void</code> pointers. The available TLS implementations are:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>C++11 <code>thread_local</code> keyword (the default).</p>
|
|
</li>
|
|
<li>
|
|
<p>Win32 TLS API: selected by defining <code>BOOST_LEAF_CFG_WIN32=2</code>. This enables error objects to be used across DLL boundaries.</p>
|
|
</li>
|
|
<li>
|
|
<p>Custom TLS array: selected by defining <code>BOOST_LEAF_USE_TLS_ARRAY</code>. This is intended for <a href="#embedded_platforms">embedded platforms</a> where the C++11 <code>thread_local</code> keyword is not available or not suitable.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>When using <code>BOOST_LEAF_USE_TLS_ARRAY</code>, the user is required to define the following two functions to implement the required TLS access:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">namespace</span> <span class="n">boost</span> <span class="p">{</span> <span class="k">namespace</span> <span class="n">leaf</span> <span class="p">{</span>
|
|
|
|
<span class="k">namespace</span> <span class="n">tls</span>
|
|
<span class="p">{</span>
|
|
<span class="kt">void</span> <span class="o">*</span> <span class="n">read_void_ptr</span><span class="p">(</span> <span class="kt">int</span> <span class="n">tls_index</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="kt">void</span> <span class="n">write_void_ptr</span><span class="p">(</span> <span class="kt">int</span> <span class="n">tls_index</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span> <span class="n">p</span> <span class="p">)</span> <span class="k">noexcept</span><span class="p">;</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="p">}</span> <span class="p">}</span></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">
|
|
For efficiency, <code>read_void_ptr</code> and <code>write_void_ptr</code> should be defined <code>inline</code>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Under <code>BOOST_LEAF_USE_TLS_ARRAY</code> the following additional configuration macros are recognized:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p><code>BOOST_LEAF_CFG_TLS_ARRAY_START_INDEX</code> specifies the start TLS array index available to LEAF (if the macro is left undefined, LEAF defines it as <code>0</code>).</p>
|
|
</li>
|
|
<li>
|
|
<p><code>BOOST_LEAF_CFG_TLS_ARRAY_SIZE</code> may be defined to specify the size of the TLS array. In this case TLS indices are validated via <code>BOOST_LEAF_ASSERT</code> before being passed to <code>read_void_ptr</code> / <code>write_void_ptr</code>.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>BOOST_LEAF_CFG_TLS_INDEX_TYPE</code> may be defined to specify the integral type used to store assigned TLS indices (if the macro is left undefined, LEAF defines it as <code>unsigned char</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">
|
|
TLS slots are allocated only for types used in error handlers. The minimum size of the TLS pointer array required by LEAF is the total number of different types used as arguments to error handlers (in the entire program), plus one.
|
|
</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">
|
|
Beware of <code>read_void_ptr</code>/<code>write_void_ptr</code> accessing thread local pointers beyond the static boundaries of the thread local pointer array; this will likely result in undefined behavior.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="embedded_platforms">Embedded Platforms</h3>
|
|
<div class="paragraph">
|
|
<p>Defining <code>BOOST_LEAF_EMBEDDED</code> is equivalent to the following:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="cp">#ifndef BOOST_LEAF_CFG_DIAGNOSTICS
|
|
# define BOOST_LEAF_CFG_DIAGNOSTICS 0
|
|
#endif
|
|
</span>
|
|
<span class="cp">#ifndef BOOST_LEAF_CFG_STD_SYSTEM_ERROR
|
|
# define BOOST_LEAF_CFG_STD_SYSTEM_ERROR 0
|
|
#endif
|
|
</span>
|
|
<span class="cp">#ifndef BOOST_LEAF_CFG_STD_STRING
|
|
# define BOOST_LEAF_CFG_STD_STRING 0
|
|
#endif
|
|
</span>
|
|
<span class="cp">#ifndef BOOST_LEAF_CFG_CAPTURE
|
|
# define BOOST_LEAF_CFG_CAPTURE 0
|
|
#endif</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>LEAF supports FreeRTOS out of the box, define <code>BOOST_LEAF_TLS_FREERTOS</code> (in which case LEAF automatically defines <code>BOOST_LEAF_EMBEDDED</code>, if it is not defined already).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>For other embedded platforms, define <code>BOOST_LEAF_USE_TLS_ARRAY</code>, see <a href="#configuring_tls_access">Configuring TLS Access</a>.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>If your program does not use concurrency at all, simply define <code>BOOST_LEAF_NO_THREADS</code>, which requires no TLS support at all (but is NOT thread-safe).</p>
|
|
</div>
|
|
<div class="admonitionblock tip">
|
|
<table>
|
|
<tr>
|
|
<td class="icon">
|
|
<i class="fa icon-tip" title="Tip"></i>
|
|
</td>
|
|
<td class="content">
|
|
Contrary to popular belief, exception handling works great on embedded platforms. In <a href="https://www.youtube.com/watch?v=BGmzMuSDt-Y">this talk</a> Khalil Estell demonstrates that using exceptions to handle errors leads to a significant reduction in firmware code size (of course LEAF works with or without exception handling).
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="portability">Portability</h2>
|
|
<div class="sectionbody">
|
|
<div class="paragraph">
|
|
<p>The source code is compatible with C++11 or newer.</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="rouge highlight nowrap"><code data-lang="sh"><span class="nb">cd </span>leaf
|
|
meson setup _bld/debug
|
|
<span class="nb">cd </span>_bld/debug
|
|
meson <span class="nb">test</span></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="rouge highlight nowrap"><code data-lang="sh">../../b2 <span class="nb">test</span></code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="rationale">Design Rationale</h2>
|
|
<div class="sectionbody">
|
|
<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 reserves storage for these types (using automatic storage duration) until they are passed to a suitable handler.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>When an error is reported, LEAF checks if storage is available for each error object type:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>If storage is available, the object is stored directly in the error handling scope, bypassing all <em>error neutral</em> functions in between.</p>
|
|
</li>
|
|
<li>
|
|
<p>If storage is not available, the error object is discarded, since no error handling function makes any use of it — saving resources.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Each error occurrence is assigned a unique <a href="#error_id"><code>error_id</code></a>, which prevents handlers from accessing stale error objects from previous failures. To handle a failure, LEAF matches the available error objects (by their <code>error_id</code>) with the argument types required by each handler.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sect1">
|
|
<h2 id="_dynamic_linking">Dynamic Linking</h2>
|
|
<div class="sectionbody">
|
|
<div class="sect2">
|
|
<h3 id="_posix">POSIX</h3>
|
|
<div class="paragraph">
|
|
<p>When compiling with <code>-fvisibility=hidden</code>, error types must be declared with <code>default</code> visibility. It is recommended to use <code>BOOST_LEAF_SYMBOL_VISIBLE</code>, which expands to the appropriate attribute on POSIX and to nothing on Windows:</p>
|
|
</div>
|
|
<div class="listingblock">
|
|
<div class="content">
|
|
<pre class="rouge highlight nowrap"><code data-lang="c++"><span class="k">struct</span> <span class="nc">BOOST_LEAF_SYMBOL_VISIBLE</span> <span class="n">my_error_info</span>
|
|
<span class="p">{</span>
|
|
<span class="kt">int</span> <span class="n">value</span><span class="p">;</span>
|
|
<span class="p">};</span></code></pre>
|
|
</div>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>LEAF declares the following types with <code>BOOST_LEAF_SYMBOL_VISIBLE</code>: <code>error_id</code>, <code>error_info</code>, <code>diagnostic_info</code>, <code>diagnostic_details</code>, <code>e_api_function</code>, <code>e_file_name</code>, <code>e_errno</code>, <code>e_type_info_name</code>, <code>e_at_line</code>, <code>e_source_location</code>, <code>bad_result</code>, <code>result<T></code>.</p>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="_windows">Windows</h3>
|
|
<div class="paragraph">
|
|
<p>To use error objects across DLL boundaries, define <code>BOOST_LEAF_CFG_WIN32=2</code>. This switches LEAF to using the Win32 TLS API instead of C++11 <code>thread_local</code>. Dynamic unloading of DLLs is not supported.</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Modules linked against different CRT configurations (static or dynamic) can share LEAF error objects. However, for two modules to share error objects, they must be compiled with the same compiler (not necessarily the same compiler version). For example, if one module is compiled with MSVC and another with GCC, error objects will not be shared between them.</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://en.cppreference.com/w/cpp/utility/expected"><code>std::expected</code></a> (C++23)</p>
|
|
</li>
|
|
<li>
|
|
<p><a href="https://ned14.github.io/outcome">Boost Outcome</a></p>
|
|
</li>
|
|
<li>
|
|
<p><a href="https://www.boost.org/doc/libs/release/libs/exception/doc/boost-exception.html">Boost Exception</a></p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>Below we offer a comparison of Boost LEAF to these alternatives.</p>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="std_expected">Comparison to <code>std::expected</code></h3>
|
|
<div class="paragraph">
|
|
<p><code>std::expected<T, E></code>, introduced in C++23, is a vocabulary type for functions that return either a value of type <code>T</code> or an error of type <code>E</code>. It is similar to <code>leaf::result<T></code> in purpose but differs in design:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p><code>std::expected<T, E></code> encodes the error type <code>E</code> in the function signature. <code>leaf::result<T></code> does not specify an error type; error objects are transported separately.</p>
|
|
</li>
|
|
<li>
|
|
<p>With <code>std::expected</code>, a function can only return a single error object of type <code>E</code>. LEAF allows associating multiple error objects of different types with a single failure.</p>
|
|
</li>
|
|
<li>
|
|
<p>LEAF’s <a href="#on_error"><code>on_error</code></a> allows intermediate functions to attach additional context as errors propagate, without modifying function signatures.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The choice between them depends on whether encoding error types in function signatures is desired, and whether associating multiple error objects with a single failure is needed.</p>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="boost_outcome">Comparison to Boost Outcome</h3>
|
|
<div class="paragraph">
|
|
<p>Like LEAF, <a href="https://ned14.github.io/outcome">Boost Outcome</a> is designed for low latency environments. It provides <code>result<T,EC,NVP></code> and <code>outcome<T,EC,EP,NVP></code>, where <code>EC</code> is an error code type (defaulting to <code>std::error_code</code>) and <code>EP</code> is a pointer type for additional error information (defaulting to <code>std::exception_ptr</code>).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>The key design difference is in how error information is transported:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>Outcome encodes error types in function signatures via the <code>EC</code> and <code>EP</code> template parameters, giving callers explicit visibility of possible error types.</p>
|
|
</li>
|
|
<li>
|
|
<p>LEAF decouples <code>leaf::result<T></code> from error types entirely. Error objects are transported separately to error handling scopes, where the handlers determine which types are needed.</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/example/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">
|
|
LEAF is compatible with <code>outcome::result<T></code>; you don’t have to use <code>leaf::result<T></code>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="sect3">
|
|
<h4 id="interoperability">The Interoperability Problem</h4>
|
|
<div class="paragraph">
|
|
<p>The Boost Outcome documentation discusses the challenge of integrating multiple libraries with different error types:</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>Boost Outcome addresses this by providing converters in the <code>outcome::convert</code> namespace to translate between error types (option 2).</p>
|
|
</div>
|
|
<div class="paragraph">
|
|
<p>LEAF takes a different approach: error objects are transported directly to error handling scopes where storage is allocated statically, implementing option 3 without dynamic allocation.</p>
|
|
</div>
|
|
<hr>
|
|
</div>
|
|
</div>
|
|
<div class="sect2">
|
|
<h3 id="boost_exception">Comparison to Boost Exception</h3>
|
|
<div class="paragraph">
|
|
<p>Both LEAF and <a href="https://www.boost.org/doc/libs/release/libs/exception/doc/boost-exception.html">Boost Exception</a> allow transporting arbitrary error information with exceptions. The key design differences:</p>
|
|
</div>
|
|
<div class="ulist">
|
|
<ul>
|
|
<li>
|
|
<p>Boost Exception stores error objects in the exception object itself (requiring dynamic allocation). LEAF stores error objects in the error handling scope, discarding those not needed by handlers.</p>
|
|
</li>
|
|
<li>
|
|
<p>Boost Exception can only augment exceptions deriving from <code>boost::exception</code>. LEAF can augment any exception type.</p>
|
|
</li>
|
|
<li>
|
|
<p>Boost Exception automatically captures error objects across thread boundaries via <code>boost::exception_ptr</code>. LEAF requires explicit use of <a href="#capture">[capture]</a>.</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 can access Boost Exception error information using its error handling interface. See <a href="#tutorial-boost_exception_integration">Boost Exception Integration</a>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</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="footer">
|
|
<div id="footer-text">
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html> |