<p>Traditionally, when using exceptions to report failures, the throw site:</p>
<div><ul><li>creates an exception object of the appropriate type, and</li>
<li>stuffs it with data relevant to the detected error.</li>
</ul></div>
<p>A higher context in the program contains a catch statement which:</p>
<div><ul><li>selects failures based on exception types, and</li>
<li>inspects exception objects for data required to deal with the problem.</li>
</ul></div>
<p>The main issue with this "traditional" approach is that often, the data available at the point of the throw is insufficient for the catch site to handle the failure.</p>
<p>Here is an example of a catch statement:</p>
<pre>catch( file_read_error & e )
{
std::cerr << e.file_name();
}</pre>
<p>And here is a possible matching throw:</p>
<pre>void
read_file( FILE * f )
{
....
size_t nr=fread(buf,1,count,f);
if( ferror(f) )
throw file_read_error(???);
....
}</pre>
<p>Clearly, the problem is that the handler requires a file name but the read_file function does not have a file name to put in the exception object; all it has is a FILE pointer!</p>
<p>In an attempt to deal with this problem, we could modify read_file to accept a file name:</p>
<pre>void
read_file( FILE * f, char const * name )
{
....
size_t nr=fread(buf,1,count,f);
if( ferror(f) )
throw file_read_error(name);
....
}</pre>
<p>This is not a real solution: it simply shifts the burden of supplying a file name to the immediate caller of the read_file function.</p>
<blockquote><p><i>In general, the data required to handle a given library-emitted exception depends on the program that links to it. Many contexts between the throw and the catch may have relevant information which must be transported to the exception handler.</i></p></blockquote>
<h3>Exception wrapping</h3>
<p>The idea of exception wrapping is to catch an exception from a lower level function (such as the read_file function above), and throw a new exception object that contains the original exception (and also carries a file name.) This method seems to be particularly popular with C++ programmers with Java background.</p>
<p>Exception wrapping leads to the following problems:</p>
<p>The second point is actually special case of violating the exception neutrality principle. Most contexts in a program can not handle exceptions; such contexts should not interfere with the process of exception handling.</p>
<li>Confidently limit the throw site to provide only data that is available naturally.</li>
<li>Use exception-neutral contexts between the throw and the catch to augment exceptions with more relevant data as they bubble up.</li>
</ul></div>
<p>For example, in the throw statement below we only add the errno code, since this is the only failure-relevant information available in this context:</p>
<p>In a higher exception-neutral context, we add the file name to <i>any</i> exception that derives from boost::<spanclass="RenoLink"><ahref="exception.html">exception</a></span>:</p>
<p>Finally here is how the handler retrieves data from exceptions that derive from boost::<spanclass="RenoLink"><ahref="exception.html">exception</a></span>:</p>
<p>In addition, boost::<spanclass="RenoLink"><ahref="diagnostic_information.html">diagnostic_information</a></span> can be used to compose an automatic (if not user-friendly) message that contains all of the <spanclass="RenoLink"><ahref="error_info.html">error_info</a></span> objects added to a boost::<spanclass="RenoLink"><ahref="exception.html">exception</a></span>. This is useful for inclusion in logs and other diagnostic objects.</p>
