<html>

<head>
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<title>Hybrid Error Handling</title>
<link rel="stylesheet" type="text/css" href="../../../doc/html/minimal.css">
</head>

<body>

<p>Document number: &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; N2828=09-0018<br>
Date:&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%Y-%m-%d" startspan -->2009-02-05<!--webbot bot="Timestamp" endspan i-checksum="12164" --><br>
Project:&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 
Programming Language C++, Library Working Group<br>
Reply-to:&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 
Beman Dawes &lt;bdawes at acm.org&gt;<br>
&nbsp;</p>

<h1>Library Support for Hybrid Error Handling (Rev 1)</h1>
<h2>Introduction</h2>
<p>This proposal provides standard library clause 17 support for functions that allow 
users to choose whether errors should be reported via exception or via <code>
std::error_code</code> object.</p>
<p>The impact is to ensure that a function specified like this:</p>
<blockquote>
  <pre>void f(error_code&amp; ec=throws());</pre>
</blockquote>
<p>acts as if it had been specified like this:</p>
<blockquote>
  <pre>void f();                // throws on error
void f(error_code&amp; ec);  // never throws</pre>
</blockquote>
<p>The benefit of a single signature providing both throwing and error reporting 
semantics is that it eliminates a doubling of the number of signatures, yet 
allows very efficient implementations. This is 
particularly beneficial where a function already has an uncomfortably large 
number of overloads. The intent is that this defaulted argument approach be applied uniformly 
throughout the standard library because it is less confusing if all hybrid error handling 
interfaces are consistent.</p>
<p>The proposal makes no change to any current standard library components. It 
just adds material to clause 17 specifying the 
semantics implied by an argument specified as <kbd>error_code&amp; ec=throws()</kbd>.</p>
<p>The original plan was to hold this proposal for TR2, where libraries like 
filesystem will make extensive use of this error handling idiom. A C++0x use (LWG 
issue 935, <i>clock error handling needs to be specified</i>) has now 
arisen, so it may be desirable to add it for C++0x.</p>
<h2>Revision history</h2>
<p><b>Rev. 1 == N2828 </b>Changed 
default argument specification from unspecified name to a function call, thus allowing users to use the idiom in their own code 
and giving implementers a mechanism to detect (and presumably report) misuse.</p>
<p><b>Rev. 0 ==
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2809.html">
N2809</a> </b>&nbsp;Initial proposal.</p>
<h2>Motivating example</h2>
<p>Each of the three clocks specified in 20.9.5 Clocks [time.clock] provides the 
member function:</p>
<blockquote>
  <pre>static time_point now();</pre>
</blockquote>
<p>The semantics are specified by 20.9.1 Clock requirements [time.clock.req], 
which as of CD1 makes no mention of error handling. Thus the function may throw
<kbd>bad_alloc</kbd> or an implementation-defined exception (see [res.on.exception.handling] 
paragraph 4). Since the function is sometimes used in cases where exceptions are 
not appropriate or where the specifics of the exception or cause of error need 
to be available to the user, further options are needed.  </p>
<p>Indeed, this is an example of a class of errors where use cases require that three 
possible semantic actions be supported:</p>
<ul>
  <li>Throw an exception of of type <code>system_error</code> or of a type derived from <code>system_error</code>.</li>
</ul>
<blockquote>
  <blockquote>
    <p>This is the most appropriate default behavior, since it covers the very 
    common use case where errors are not expected and the user does not wish to 
    or have the knowledge to code anything dealing with error handling. Because 
    the exception hierarchy is specified to derive from <kbd>system_error</kbd>, 
    information about the cause of an error is provided should an exception 
    occur.</p>
    <p>For clocks, this semantic action needs to be provided by <code>now()</code> because 
    it is often used in cases where errors are truly 
    exceptional and if they do occur are best handled further up the call chain. 
    Thus this option does need to be available for clock users and is the 
    appropriate default.</p>
  </blockquote>
</blockquote>
<ul>
  <li>Report the error via an object of type <kbd>error_code</kbd>.</li>
</ul>
<blockquote>
  <blockquote>
    <p>This allows users to process errors, including details, yet does not 
    incur the runtime and code complexity cost of try/catch blocks. Without this 
    option, users report code becomes so littered with try/catch blocks that it 
    is unreadable and unmaintainable.</p>
    <p>For clocks, this option is particularly attractive for code that must be 
    robust across a wide variety of platforms, including embedded and legacy 
    systems.</p>
  </blockquote>
</blockquote>
<ul>
  <li>Ignore the error.</li>
</ul>
<blockquote>
  <blockquote>
    <p>This is just a subset of reporting via <kbd>error_code</kbd> object; the 
    object is simply ignored. It is particularly appropriate in destructors.</p>
    <p><code>now()</code> is often used in destructors, so having this semantic 
    action makes 
    life simpler for clock users.</p>
  </blockquote>
</blockquote>
<p>The proposed wording gives the user the choice of these three semantic 
actions on an error, yet does not require a doubling or tripling of the number 
of function signatures that must be specified in the standard or in actual 
interfaces. Applying this to the 
clock example, the <code>now</code> function specification becomes:</p>
<blockquote>
  <p><kbd>static time_point now(<font color="#008080"><span style="text-decoration: underline">error_code</span><span style="text-decoration: underline">&amp; ec=throws()</span></font>);</kbd></p>
</blockquote>
<p>Implementations are permitted to actually implement this as one or two 
signatures.</p>
<h2>Implementation experience</h2>
<p>The general idea of hybrid error handling has been in use by several Boost 
libraries for several years. The specifics of this proposal have been 
implemented and tested internally, and are scheduled for the next public Boost 
release..</p>

<h2>Proposed wording</h2>
  <p><i>After 17.6.5.12 Value of error codes [value.error.codes], add a new 
  subsection:</i></p>
    <blockquote>
  <p><b>17.6.5.13&nbsp; Semantics of <code>error_code&amp;</code><kbd> </kbd></b> <code>
  <b><kbd>ec=throws()</kbd></b><i> </i></code><b>arguments&nbsp; [semantics.throws]</b></p>
  <p>Certain standard library functions are specified as having an argument <code>error_code&amp; 
  ec=throws()</code>.</p>
  <p>Such functions shall behave as if specified as two separate signatures:</p>
      <blockquote>
  <p>A function signature without an <code>error_code&amp;</code> argument. If an error 
  occurs, this function shall throw an exception of type <code>system_error</code>, or of a type derived from <code>system_error</code>, 
  whose <kbd>code()</kbd> member function shall identify the reason for the 
  error.</p>
  <p>A function signature with an <code>error_code&amp; 
  ec</code> argument. This function shall not throw exceptions. Unless otherwise 
  specified, it shall have these implicit additions to its elements:</p>
      <blockquote>
  <p><i>Requires:</i> <code>&amp;ec != &amp;throws()</code>. <i>[Note:</i> this 
  precondition allows more efficient implementation and allows implementations 
  to detect misuse. <i>-- end note]</i></p>
  <p><i><span style="background-color: #C0C0C0">When the Boost implementation 
  added deliberate reference poisoning to detect precondition violations, 
  several silent bugs in Boost Filesystem Version 3 code became noisy test 
  failures.</span></i></p>
  <p><i>Postconditions:</i> If an error occurs,&nbsp; <kbd>
  ec.value()</kbd>and <kbd>ec.category()</kbd> identify the error specifics. 
  Otherwise, <kbd>!ec</kbd> is true.</p>
  <p><i>Returns:</i> If an error occurs, the return value (if any) is unspecified.</p>
      </blockquote>
      </blockquote>
  <p>Whether or not implementations actually provide two signatures is unspecified.</p>
</blockquote>

  <p><i>At the end of&nbsp; Header &lt;system_error&gt; synopsis in 19.4 System error 
  support [syserr], add:</i></p>
<blockquote>
  <pre>error_code&amp; throws();</pre>
</blockquote>

<p><i>After 19.4.1.5 Error category objects [syserr.errcat.objects], add a new 
subsection:</i></p>
<blockquote>

<p><b>19.4.1.5 Error code objects [syserr.errcat.objects]</b></p>
  <pre>error_code&amp; throws();</pre>
  <p><i>Returns:</i> A reference that can be used as a default function argument 
  to signify an exception should be thrown when an error is detected ([semantics.throws]).</p>
</blockquote>

<h2>Acknowledgements</h2>
<p>Howard Hinnant suggested use of an unspecified name rather than a specific 
name to denote the default 
case, and thus discourage misuse. He also provided other helpful suggestions and comments that have been 
incorporated into this proposal. Although the unspecified name approach was 
abandoned because it didn't support use in user written libraries, it led to 
approach taken by the final proposal.</p>

<hr>

<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%B %d, %Y" startspan -->February 05, 2009<!--webbot bot="Timestamp" endspan i-checksum="41413" --></p>

<p> Copyright Beman Dawes, 2008</p>

<p>Distributed under the Boost Software License, Version 1.0.
(See file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a>
or&nbsp; <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>) </p>

</body>

</html>