boostorg/exception
1
0
Fork 1
mirror of https://github.com/boostorg/exception.git synced 2025-07-13 12:36:37 +02:00
Code Issues Packages Projects Releases Wiki Activity

Boost Exception documentation update

Browse Source 
[SVN r44444]
This commit is contained in:
Emil Dotchevski
2008-04-15 21:56:34 +00:00
parent 4ae983f5f0
commit b1b9478cbc
23 changed files with 3398 additions and 2812 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
doc/adding_data_at_throw.html Normal file
View File

@ -0,0 +1,73 @@
<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN'
'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>
<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'>
<head>
<meta http-equiv='Content-Type' content='text/html; charset=utf-8'/>
<title>Tutorial: Adding of Arbitrary Data at the Point of the Throw</title>
<link href='reno.css' type='text/css' rel='stylesheet'/>
</head>
<body>
<div class="body-0">
<div class="body-1">
<div class="body-2">
<div>
<div id="boost_logo">
<a href="http://www.boost.org"><img style="border:0" src="http://www.boost.org/boost.png" alt="Boost" width="277" height="86"/></a>
</div>
<h1>Boost Exception</h1>
</div>
<div class="RenoIncludeDIV"><h3>Adding of Arbitrary Data at the Point of the Throw</h3>
<p>The following example demonstrates how <tt>errno</tt> can be stored in exception objects using Boost Exception:</p>
<pre>#include &lt;<span class="RenoLink"><a href="exception_hpp.html">boost/exception.hpp</a></span>&gt;
#include &lt;errno.h&gt;
#include &lt;iostream&gt;
typedef boost::<span class="RenoLink"><a href="error_info.html">error_info</a></span>&lt;struct tag_errno,int&gt; errno_info; //(1)
class my_error: public boost::<span class="RenoLink"><a href="exception.html">exception</a></span>, public std::exception { }; //(2)
void
f()
{
throw my_error() &lt;&lt; errno_info(errno); //(3)
}
</pre>
<p>First, we instantiate the <tt><span class="RenoLink"><a href="error_info.html">error_info</a></span></tt> template using a unique identifier -- <tt>tag_errno</tt>, and the type of the info it identifies -- <tt>int</tt>. This provides compile-time type safety for the various values stored in exception objects.</p>
<p>Second, we define class <tt>my_error</tt>, which derives from <tt>boost::<span class="RenoLink"><a href="exception.html">exception</a></span></tt>.</p>
<p>Finally, (3) illustrates how the <tt>typedef</tt> from (1) can be used with <tt><span class="RenoLink"><a href="operator_shl_exception.html">operator&lt;&lt;</a></span>()</tt> to store values in exception objects at the point of the throw.</p>
<p>The stored <tt>errno</tt> value can be recovered at a later time like this:</p>
<pre>// ...continued
void
g()
{
try
{
f();
}
catch(
my_error &amp; x )
{
if( boost::shared_ptr&lt;int const&gt; err=boost::<span class="RenoLink"><a href="get_error_info.html">get_error_info</a></span>&lt;errno_info&gt;(x) )
std::cerr &lt;&lt; "Error code: " &lt;&lt; *err;
}
}</pre>
<p>The <tt><span class="RenoLink"><a href="get_error_info.html">get_error_info</a></span>()</tt> function template is instantiated with the <tt>typedef</tt> from (1), and is passed an exception object of any type that derives publicly from <tt>boost::<span class="RenoLink"><a href="exception.html">exception</a></span></tt>. If the exception object contains the requested value, the returned <tt><span class="RenoLink"><a href="http://www.boost.org/libs/smart_ptr/shared_ptr.htm">shared_ptr</a></span></tt> will point to it; otherwise an empty <tt><span class="RenoLink"><a href="http://www.boost.org/libs/smart_ptr/shared_ptr.htm">shared_ptr</a></span></tt> is returned.</p>
</div><h3>See also:</h3>
<div class="RenoPageList"><a href="transporting_data.html">Tutorial: Transporting of Arbitrary Data to the Catch Site<br/>
</a></div>
<div id="footer">
<p>&nbsp;</p>
<hr/>
<p>
<a class="logo" href="http://jigsaw.w3.org/css-validator/validator?uri=http://revergestudios.com/boost-exception/reno.css"><img class="logo_pic" src="valid-css.png" alt="Valid CSS" height="31" width="88"/></a>
<a class="logo" href="http://validator.w3.org/check?uri=referer"><img class="logo_pic" src="valid-xhtml.png" alt="Valid XHTML 1.0" height="31" width="88"/></a>
<small>Copyright (c) 2006-2008 by Emil Dotchevski and Reverge Studios, Inc.<br/>
Distributed under the <a href="http://www.boost.org/LICENSE_1_0.txt">Boost Software License, Version 1.0</a>.</small>
</p>
</div>
</div>
</div>
</div>
</body>
</html>

116
doc/adding_data_later.html Normal file
View File

@ -0,0 +1,116 @@
<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN'
'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>
<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'>
<head>
<meta http-equiv='Content-Type' content='text/html; charset=utf-8'/>
<title>Tutorial: Adding of Arbitrary Data to Active Exception Objects</title>
<link href='reno.css' type='text/css' rel='stylesheet'/>
</head>
<body>
<div class="body-0">
<div class="body-1">
<div class="body-2">
<div>
<div id="boost_logo">
<a href="http://www.boost.org"><img style="border:0" src="http://www.boost.org/boost.png" alt="Boost" width="277" height="86"/></a>
</div>
<h1>Boost Exception</h1>
</div>
<div class="RenoIncludeDIV"><h3>Adding of Arbitrary Data to Active Exception Objects</h3>
<p>Sometimes the throw site does not have all the information that is needed at the catch site to make sense of what went wrong. Here is an example:</p>
<pre>#include &lt;stdio.h&gt;
#include &lt;string&gt;
class
file_read_error
{
public:
explicit
file_read_error( std::string const &amp; fn ):
fn_(fn)
{
};
std::string const &amp;
file_name() const
{
return fn_;
}
private:
std::string fn_;
};
void
file_read( FILE * f, void * buffer, size_t size )
{
if( size!=fread(buffer,1,size,f) )
throw file_read_error("????");
}</pre>
<p>We have defined an exception class <tt>file_read_error</tt> which can store a file name, so that when we catch a <tt>file_read_error</tt> object, we know which file the failure is related to. However, the <tt>file_read</tt> function does not have the file name at the time of the throw; all it has is a <tt>FILE</tt> handle.</p>
<p>One possible solution is to not use <tt>FILE</tt> handles directly. We could have our own <tt>class file</tt> which stores both a <tt>FILE</tt> handle and a file name, and pass that to <tt>file_read()</tt>. However, this could be problematic if we communicate with 3rd party code that does not use our <tt>class file</tt> (probably because they have their own similar class.)</p>
<p>A better solution is to make class <tt>file_read_error</tt> derive (possibly indirectly) from <tt>boost::<span class="RenoLink"><a href="exception.html">exception</a></span></tt>, and free the <tt>file_read()</tt> function from the burden of storing the file name in exceptions it throws:</p>
<pre>#include &lt;<span class="RenoLink"><a href="exception_hpp.html">boost/exception.hpp</a></span>&gt;
#include &lt;stdio.h&gt;
#include &lt;errno.h&gt;
typedef boost::<span class="RenoLink"><a href="error_info.html">error_info</a></span>&lt;struct tag_errno,int&gt; errno_info;
class file_read_error: public boost::<span class="RenoLink"><a href="exception.html">exception</a></span> { };
void
file_read( FILE * f, void * buffer, size_t size )
{
if( size!=fread(buffer,1,size,f) )
throw file_read_error() &lt;&lt; errno_info(errno);
}</pre>
<p>If <tt>file_read()</tt> detects a failure, it throws an exception which contains the information that is available at the time, namely the <tt>errno</tt>. Other relevant information, such as the file name, can be added in a context higher up the call stack, where it is known naturally:</p>
<pre>#include &lt;<span class="RenoLink"><a href="exception_hpp.html">boost/exception.hpp</a></span>&gt;
#include &lt;boost/shared_ptr.hpp&gt;
#include &lt;stdio.h&gt;
#include &lt;string&gt;
typedef boost::<span class="RenoLink"><a href="error_info.html">error_info</a></span>&lt;struct tag_file_name,std::string&gt; file_name_info;
boost::shared_ptr&lt;FILE&gt; file_open( char const * file_name, char const * mode );
void file_read( FILE * f, void * buffer, size_t size );
void
parse_file( char const * file_name )
{
boost::shared_ptr&lt;FILE&gt; f = file_open(file_name,"rb");
assert(f);
try
{
char buf[1024];
file_read( f.get(), buf, sizeof(buf) );
}
catch(
boost::<span class="RenoLink"><a href="exception.html">exception</a></span> &amp; e )
{
e &lt;&lt; file_name_info(file_name);
throw;
}
}</pre>
<p>The above function is (almost) exception-neutral -- if an exception is emitted by any function call within the <tt>try</tt> block, <tt>parse_file()</tt> does not need to do any real work, but it intercepts any <tt>boost::<span class="RenoLink"><a href="exception.html">exception</a></span></tt> object, stores the file name, and re-throws using a throw-expression with no operand (15.1.6). The rationale for catching any <tt>boost::<span class="RenoLink"><a href="exception.html">exception</a></span></tt> object is that the file name is relevant to any failure that occurs in <tt>parse_file()</tt>, <i>even if the failure is unrelated to file I/O</i>.</p>
<p>As usual, the stored data can be retrieved using <tt><span class="RenoLink"><a href="get_error_info.html">get_error_info</a></span>()</tt>.</p>
</div><h3>See also:</h3>
<div class="RenoPageList"><a href="transporting_data.html">Tutorial: Transporting of Arbitrary Data to the Catch Site<br/>
</a></div>
<div id="footer">
<p>&nbsp;</p>
<hr/>
<p>
<a class="logo" href="http://jigsaw.w3.org/css-validator/validator?uri=http://revergestudios.com/boost-exception/reno.css"><img class="logo_pic" src="valid-css.png" alt="Valid CSS" height="31" width="88"/></a>
<a class="logo" href="http://validator.w3.org/check?uri=referer"><img class="logo_pic" src="valid-xhtml.png" alt="Valid XHTML 1.0" height="31" width="88"/></a>
<small>Copyright (c) 2006-2008 by Emil Dotchevski and Reverge Studios, Inc.<br/>
Distributed under the <a href="http://www.boost.org/LICENSE_1_0.txt">Boost Software License, Version 1.0</a>.</small>
</p>
</div>
</div>
</div>
</div>
</body>
</html>

78
doc/boost-exception.html
View File

@ -22,7 +22,7 @@
<p>The ability to add data to exception objects after they have been passed to <tt>throw</tt> is important, because often some of the information needed to handle an exception is unavailable in the context where the failure is detected. </p> <p>The ability to add data to exception objects after they have been passed to <tt>throw</tt> is important, because often some of the information needed to handle an exception is unavailable in the context where the failure is detected. </p>
<p>Boost Exception also supports <span class="RenoLink"><a href="cloning.html">cloning</a></span> of exception objects, implemented non-intrusively and automatically by the <tt>boost::<span class="RenoLink"><a href="throw_exception.html">throw_exception</a></span>()</tt> function.</p> <p>Boost Exception also supports <span class="RenoLink"><a href="cloning.html">cloning</a></span> of exception objects, implemented non-intrusively and automatically by the <tt>boost::<span class="RenoLink"><a href="throw_exception.html">throw_exception</a></span>()</tt> function.</p>
<h4>Note:</h4> <h4>Note:</h4>
<p>Boost Exception was accepted as a Boost library on November 7, 2007; however it has not yet been part of an official Boost release.</p> <p>Boost Exception was accepted as a Boost library on November 7 2007, however it has not yet been part of an official Boost release. Current version can be downloaded from <span class="RenoLink"><a href="http://svn.boost.org/svn/boost/trunk"> Boost SVN</a></span>.</p>
<h2>Contents</h2> <h2>Contents</h2>
<div><ol><li>Tutorial<div><ol><li><span class="RenoLink"><a href="transporting_data.html">Tutorial: Transporting of Arbitrary Data to the Catch Site</a></span></li> <div><ol><li>Tutorial<div><ol><li><span class="RenoLink"><a href="transporting_data.html">Tutorial: Transporting of Arbitrary Data to the Catch Site</a></span></li>
<li><span class="RenoLink"><a href="using_enable_error_info.html">Tutorial: Integrating Boost Exception in Existing Exception Class Hierarchies</a></span></li> <li><span class="RenoLink"><a href="using_enable_error_info.html">Tutorial: Integrating Boost Exception in Existing Exception Class Hierarchies</a></span></li>
@ -39,28 +39,28 @@
</ol></div> </ol></div>
</li> </li>
<li>Transporting of Exceptions between Threads<div><ol><li><tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt></li> <li>Transporting of Exceptions between Threads<div><ol><li><tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt></li>
<li><tt><span class="RenoLink"><a href="enable_exception_cloning.html">enable_exception_cloning</a></span>()</tt></li> <li><tt><span class="RenoLink"><a href="enable_current_exception.html">enable_current_exception</a></span>()</tt></li>
<li><tt><span class="RenoLink"><a href="clone_exception.html">clone_exception</a></span>()</tt></li> <li><tt><span class="RenoLink"><a href="current_exception.html">current_exception</a></span>()</tt></li>
<li><tt><span class="RenoLink"><a href="copy_exception.html">copy_exception</a></span>()</tt></li>
<li><tt><span class="RenoLink"><a href="rethrow_exception.html">rethrow_exception</a></span>()</tt></li> <li><tt><span class="RenoLink"><a href="rethrow_exception.html">rethrow_exception</a></span>()</tt></li>
<li><tt><span class="RenoLink"><a href="unknown_exception.html">unknown_exception</a></span></tt></li> <li><tt><span class="RenoLink"><a href="unknown_exception.html">unknown_exception</a></span></tt></li>
</ol></div> </ol></div>
</li> </li>
<li><tt><span class="RenoLink"><a href="throw_exception.html">throw_exception</a></span>()</tt></li> <li><tt><span class="RenoLink"><a href="throw_exception.html">throw_exception</a></span>()</tt></li>
<li>Headers<div><ol><li><tt><span class="RenoLink"><a href="exception_hpp.html">boost/exception.hpp</a></span></tt></li> <li>Headers<div><ol><li><tt><span class="RenoLink"><a href="exception_hpp.html">boost/exception.hpp</a></span></tt></li>
<li><tt><span class="RenoLink"><a href="exception_enable_exception_cloning_hpp.html">boost/exception/enable_exception_cloning.hpp</a></span></tt></li> <li><tt><span class="RenoLink"><a href="exception_cloning_hpp.html">boost/exception_ptr.hpp</a></span></tt></li>
<li><tt><span class="RenoLink"><a href="throw_exception_hpp.html">boost/throw_exception.hpp</a></span></tt></li>
<li><tt><span class="RenoLink"><a href="exception_enable_exception_cloning_hpp.html">boost/exception/enable_current_exception.hpp</a></span></tt></li>
<li><tt><span class="RenoLink"><a href="exception_enable_error_info_hpp.html">boost/exception/enable_error_info.hpp</a></span></tt></li> <li><tt><span class="RenoLink"><a href="exception_enable_error_info_hpp.html">boost/exception/enable_error_info.hpp</a></span></tt></li>
<li><tt><span class="RenoLink"><a href="exception_error_info_hpp.html">boost/exception/info.hpp</a></span></tt></li> <li><tt><span class="RenoLink"><a href="exception_error_info_hpp.html">boost/exception/info.hpp</a></span></tt></li>
<li><tt><span class="RenoLink"><a href="exception_error_info_group_hpp.html">boost/exception/info_tuple.hpp</a></span></tt></li> <li><tt><span class="RenoLink"><a href="exception_error_info_group_hpp.html">boost/exception/info_tuple.hpp</a></span></tt></li>
<li><tt><span class="RenoLink"><a href="exception_error_info_value_hpp.html">boost/exception/error_info.hpp</a></span></tt></li> <li><tt><span class="RenoLink"><a href="exception_error_info_value_hpp.html">boost/exception/error_info.hpp</a></span></tt></li>
<li><tt><span class="RenoLink"><a href="exception_exception_hpp.html">boost/exception/exception.hpp</a></span></tt></li> <li><tt><span class="RenoLink"><a href="exception_exception_hpp.html">boost/exception/exception.hpp</a></span></tt></li>
<li><tt><span class="RenoLink"><a href="throw_exception_hpp.html">boost/throw_exception.hpp</a></span></tt></li>
</ol></div> </ol></div>
</li> </li>
</ol></div> </ol></div>
</li> </li>
<li><span class="RenoLink"><a href="name_idx.html">Index</a></span></li> <li><span class="RenoLink"><a href="name_idx.html">Index</a></span></li>
<li><span class="RenoLink"><a href="boost-exception.zip">Download</a></span></li>
<li><span class="RenoLink"><a href="source">Browse source code</a></span></li>
</ol></div> </ol></div>
<h2>Synopsis</h2> <h2>Synopsis</h2>
<p><tt>#include &lt;<span class="RenoLink"><a href="exception_hpp.html">boost/exception.hpp</a></span>&gt;</tt></p> <p><tt>#include &lt;<span class="RenoLink"><a href="exception_hpp.html">boost/exception.hpp</a></span>&gt;</tt></p>
@ -128,10 +128,11 @@ boost
<span class="RenoIncludeSPAN"> typedef ---unspecified--- <span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span>;</span> <span class="RenoIncludeSPAN"> typedef ---unspecified--- <span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span>;</span>
<span class="RenoIncludeSPAN"> template &lt;class T&gt; <span class="RenoIncludeSPAN"> template &lt;class T&gt;
---unspecified--- <span class="RenoLink"><a href="enable_exception_cloning.html">enable_exception_cloning</a></span>( T const &amp; e );</span> ---unspecified--- <span class="RenoLink"><a href="enable_current_exception.html">enable_current_exception</a></span>( T const &amp; e );</span>
<span class="RenoIncludeSPAN"> <span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span> <span class="RenoLink"><a href="current_exception.html">current_exception</a></span>();</span>
<span class="RenoIncludeSPAN"> template &lt;class T&gt; <span class="RenoIncludeSPAN"> template &lt;class T&gt;
<span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span> <span class="RenoLink"><a href="clone_exception.html">clone_exception</a></span>( T const &amp; e );</span> <span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span> <span class="RenoLink"><a href="copy_exception.html">copy_exception</a></span>( T const &amp; e );</span>
<span class="RenoIncludeSPAN"> void <span class="RenoLink"><a href="rethrow_exception.html">rethrow_exception</a></span>( <span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span> const &amp; ep );</span> <span class="RenoIncludeSPAN"> void <span class="RenoLink"><a href="rethrow_exception.html">rethrow_exception</a></span>( <span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span> const &amp; ep );</span>
<span class="RenoIncludeSPAN"> class <span class="RenoIncludeSPAN"> class
@ -299,22 +300,24 @@ boost
</div><p>This macro is designed to be used with <tt><span class="RenoLink"><a href="operator_shl_exception.html">operator&lt;&lt;</a></span>()</tt> when throwing a <tt>boost::<span class="RenoLink"><a href="exception.html">exception</a></span></tt>, to store information about the location of the throw statement. It can be chained with other <tt><span class="RenoLink"><a href="error_info.html">error_info</a></span></tt>s in a single throw expression.</p> </div><p>This macro is designed to be used with <tt><span class="RenoLink"><a href="operator_shl_exception.html">operator&lt;&lt;</a></span>()</tt> when throwing a <tt>boost::<span class="RenoLink"><a href="exception.html">exception</a></span></tt>, to store information about the location of the throw statement. It can be chained with other <tt><span class="RenoLink"><a href="error_info.html">error_info</a></span></tt>s in a single throw expression.</p>
</div><h2>Transporting of Exceptions between Threads</h2> </div><h2>Transporting of Exceptions between Threads</h2>
<div class="RenoIncludeDIV"><h3>exception_ptr</h3> <div class="RenoIncludeDIV"><h3>exception_ptr</h3>
<div class="RenoIncludeDIV"><p><tt>#include &lt;<span class="RenoLink"><a href="exception_cloning_hpp.html">boost/exception/cloning.hpp</a></span>&gt;</tt></p> <div class="RenoIncludeDIV"><p><tt>#include &lt;<span class="RenoLink"><a href="exception_cloning_hpp.html">boost/exception_ptr.hpp</a></span>&gt;</tt></p>
<pre>namespace <pre>namespace
boost boost
{ {
<span class="RenoIncludeSPAN"> typedef ---unspecified--- <span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span>;</span> <span class="RenoIncludeSPAN"> typedef ---unspecified--- <span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span>;</span>
}</pre> }</pre>
</div><p>The <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> type can be used to refer to a copy of a <tt>boost::<span class="RenoLink"><a href="exception.html">exception</a></span></tt> object. It is Default Constructible, Copy Constructible, Assignable and Equality Comparable; <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt>'s operations do not throw.</p> </div><p>The <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> type can be used to refer to a copy of an exception object. It is Default Constructible, Copy Constructible, Assignable and Equality Comparable; <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt>'s operations do not throw.</p>
<p>Two instances of <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> are equivalent and compare equal if and only if they refer to the same exception.</p> <p>Two instances of <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> are equivalent and compare equal if and only if they refer to the same exception.</p>
<p>The default constructor of <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> produces the null value of the type. The null value is equivalent only to itself.</p> <p>The default constructor of <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> produces the null value of the type. The null value is equivalent only to itself.</p>
</div><div class="RenoIncludeDIV"><h3>enable_exception_cloning()</h3> <h4>Note:</h4>
<div class="RenoIncludeDIV"><p><tt>#include &lt;<span class="RenoLink"><a href="exception_enable_exception_cloning_hpp.html">boost/exception/enable_exception_cloning.hpp</a></span>&gt;</tt></p> <p><tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> objects are returned by <tt><span class="RenoLink"><a href="current_exception.html">current_exception</a></span>()</tt> and <tt><span class="RenoLink"><a href="copy_exception.html">copy_exception</a></span>()</tt>.</p>
</div><div class="RenoIncludeDIV"><h3>enable_current_exception()</h3>
<div class="RenoIncludeDIV"><p><tt>#include &lt;<span class="RenoLink"><a href="exception_enable_exception_cloning_hpp.html">boost/exception/enable_current_exception.hpp</a></span>&gt;</tt></p>
<pre>namespace <pre>namespace
boost boost
{ {
<span class="RenoIncludeSPAN"> template &lt;class T&gt; <span class="RenoIncludeSPAN"> template &lt;class T&gt;
---unspecified--- <span class="RenoLink"><a href="enable_exception_cloning.html">enable_exception_cloning</a></span>( T const &amp; e );</span> ---unspecified--- <span class="RenoLink"><a href="enable_current_exception.html">enable_current_exception</a></span>( T const &amp; e );</span>
}</pre> }</pre>
</div><h4>Requirements:</h4> </div><h4>Requirements:</h4>
<p><tt>T</tt> must have an accessible no-throw copy constructor</p> <p><tt>T</tt> must have an accessible no-throw copy constructor</p>
@ -329,29 +332,39 @@ my_exception:
}; };
.... ....
throw boost::<span class="RenoLink"><a href="enable_exception_cloning.html">enable_exception_cloning</a></span>(my_exception());</pre> throw boost::<span class="RenoLink"><a href="enable_current_exception.html">enable_current_exception</a></span>(my_exception());</pre>
<p>Unless <tt><span class="RenoLink"><a href="enable_exception_cloning.html">enable_exception_cloning</a></span>()</tt> is called at the time an exception object is used in a throw-expression, any attempt to copy it using <tt><span class="RenoLink"><a href="clone_exception.html">clone_exception</a></span>()</tt> returns an <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> which refers to an instance of <tt><span class="RenoLink"><a href="unknown_exception.html">unknown_exception</a></span></tt>.</p> <p>Unless <tt><span class="RenoLink"><a href="enable_current_exception.html">enable_current_exception</a></span>()</tt> is called at the time an exception object is used in a throw-expression, any attempt to copy it using <tt><span class="RenoLink"><a href="current_exception.html">current_exception</a></span>()</tt> returns an <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> which refers to an instance of <tt><span class="RenoLink"><a href="unknown_exception.html">unknown_exception</a></span></tt>.</p>
<h4>Note:</h4> <h4>Note:</h4>
<p>Instead of using the <tt>throw</tt> keyword directly, it is preferable to call <tt>boost::<span class="RenoLink"><a href="throw_exception.html">throw_exception</a></span>()</tt>. This is guaranteed to throw an exception that derives from <tt>boost::<span class="RenoLink"><a href="exception.html">exception</a></span></tt> and supports cloning.</p> <p>Instead of using the <tt>throw</tt> keyword directly, it is preferable to call <tt>boost::<span class="RenoLink"><a href="throw_exception.html">throw_exception</a></span>()</tt>. This is guaranteed to throw an exception that derives from <tt>boost::<span class="RenoLink"><a href="exception.html">exception</a></span></tt> and supports cloning.</p>
</div><div class="RenoIncludeDIV"><h3>clone_exception()</h3> </div><div class="RenoIncludeDIV"><h3>current_exception()</h3>
<div class="RenoIncludeDIV"><p><tt>#include &lt;<span class="RenoLink"><a href="exception_cloning_hpp.html">boost/exception/cloning.hpp</a></span>&gt;</tt></p> <div class="RenoIncludeDIV"><p><tt>#include &lt;<span class="RenoLink"><a href="exception_cloning_hpp.html">boost/exception_ptr.hpp</a></span>&gt;</tt></p>
<pre>namespace
boost
{
<span class="RenoIncludeSPAN"> <span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span> <span class="RenoLink"><a href="current_exception.html">current_exception</a></span>();</span>
}</pre>
</div><h4>Requirements:</h4>
<p>The <tt><span class="RenoLink"><a href="current_exception.html">current_exception</a></span>()</tt> function must not be called outside of a <tt>catch</tt> block.</p>
<h4>Returns:</h4>
<div><ul><li> An <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> that refers to the currently handled exception or a copy of the currently handled exception.</li>
<li> If the function needs to allocate memory and the attempt fails, it returns an <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> that refers to an instance of <tt>std::bad_alloc</tt>.</li>
</ul></div>
<h4>Notes:</h4>
<div><ul><li> It is unspecified whether the return values of two successive calls to <tt><span class="RenoLink"><a href="current_exception.html">current_exception</a></span>()</tt> refer to the same exception object.</li>
<li> Correct implementation of <tt><span class="RenoLink"><a href="current_exception.html">current_exception</a></span>()</tt> may require compiler support, unless <tt><span class="RenoLink"><a href="enable_current_exception.html">enable_current_exception</a></span>()</tt> is used at the time the currently handled exception object was passed to <tt>throw</tt>. If <tt><span class="RenoLink"><a href="enable_current_exception.html">enable_current_exception</a></span>()</tt> is not used, and if the compiler does not provide the necessary support, then <tt><span class="RenoLink"><a href="current_exception.html">current_exception</a></span>()</tt> may return an <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> that refers to an instance of <tt><span class="RenoLink"><a href="unknown_exception.html">unknown_exception</a></span></tt>. In this case, if the original exception object derives from <tt>boost::<span class="RenoLink"><a href="exception.html">exception</a></span></tt>, then the <tt>boost::<span class="RenoLink"><a href="exception.html">exception</a></span></tt> sub-object of the <tt><span class="RenoLink"><a href="unknown_exception.html">unknown_exception</a></span></tt> object is initialized by the <tt>boost::<span class="RenoLink"><a href="exception.html">exception</a></span></tt> copy constructor.</li>
</ul></div>
</div><div class="RenoIncludeDIV"><h3>copy_exception()</h3>
<div class="RenoIncludeDIV"><p><tt>#include &lt;<span class="RenoLink"><a href="exception_cloning_hpp.html">boost/exception_ptr.hpp</a></span>&gt;</tt></p>
<pre>namespace <pre>namespace
boost boost
{ {
<span class="RenoIncludeSPAN"> template &lt;class T&gt; <span class="RenoIncludeSPAN"> template &lt;class T&gt;
<span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span> <span class="RenoLink"><a href="clone_exception.html">clone_exception</a></span>( T const &amp; e );</span> <span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span> <span class="RenoLink"><a href="copy_exception.html">copy_exception</a></span>( T const &amp; e );</span>
}</pre> }</pre>
</div><h4>Requirements:</h4> </div><h4>Effects:</h4>
<p><tt>T</tt> must be polymorphic.</p> <p>As if <tt>try { throw e; } catch( ... ) { return <span class="RenoLink"><a href="current_exception.html">current_exception</a></span>(); }</tt></p>
<h4>Returns:</h4>
<div><ul><li> If <tt><span class="RenoLink"><a href="enable_exception_cloning.html">enable_exception_cloning</a></span>()</tt> was not used at the time the exception object was passed to <tt>throw</tt>, the returned <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> refers to an instance of <tt><span class="RenoLink"><a href="unknown_exception.html">unknown_exception</a></span></tt>. In this case, if the original exception object derives from <tt>boost::<span class="RenoLink"><a href="exception.html">exception</a></span></tt>, then the <tt>boost::<span class="RenoLink"><a href="exception.html">exception</a></span></tt> sub-object of the <tt><span class="RenoLink"><a href="unknown_exception.html">unknown_exception</a></span></tt> object is initialized by the <tt>boost::<span class="RenoLink"><a href="exception.html">exception</a></span></tt> copy constructor;</li>
<li> Otherwise, if the attempt to clone the exception results in a <tt>std::bad_alloc</tt> exception, the returned <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> refers to an instance of <tt>std::bad_alloc</tt>;</li>
<li> Otherwise, the returned <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> refers to a copy of <tt>e</tt>.</li>
</ul></div>
<h4>Note:</h4>
<p>It is unspecified whether the return values of two successive calls to <tt><span class="RenoLink"><a href="clone_exception.html">clone_exception</a></span>()</tt> refer to the same exception object.</p>
</div><div class="RenoIncludeDIV"><h3>rethrow_exception()</h3> </div><div class="RenoIncludeDIV"><h3>rethrow_exception()</h3>
<div class="RenoIncludeDIV"><p><tt>#include &lt;<span class="RenoLink"><a href="exception_cloning_hpp.html">boost/exception/cloning.hpp</a></span>&gt;</tt></p> <div class="RenoIncludeDIV"><p><tt>#include &lt;<span class="RenoLink"><a href="exception_cloning_hpp.html">boost/exception_ptr.hpp</a></span>&gt;</tt></p>
<pre>namespace <pre>namespace
boost boost
{ {
@ -362,7 +375,7 @@ boost
<h4>Throws:</h4> <h4>Throws:</h4>
<p>The exception to which <tt>ep</tt> refers.</p> <p>The exception to which <tt>ep</tt> refers.</p>
</div><div class="RenoIncludeDIV"><h3>unknown_exception</h3> </div><div class="RenoIncludeDIV"><h3>unknown_exception</h3>
<div class="RenoIncludeDIV"><p><tt>#include &lt;<span class="RenoLink"><a href="exception_cloning_hpp.html">boost/exception/cloning.hpp</a></span>&gt;</tt></p> <div class="RenoIncludeDIV"><p><tt>#include &lt;<span class="RenoLink"><a href="exception_cloning_hpp.html">boost/exception_ptr.hpp</a></span>&gt;</tt></p>
<pre>namespace <pre>namespace
boost boost
{ {
@ -374,8 +387,7 @@ boost
---unspecified--- ---unspecified---
};</span> };</span>
}</pre> }</pre>
</div><p>This type is used by the <span class="RenoLink"><a href="cloning.html">cloning</a></span> support in Boost Exception.</p> </div><p>This type is used by the <span class="RenoLink"><a href="cloning.html">cloning</a></span> support in Boost Exception. Please see <tt><span class="RenoLink"><a href="current_exception.html">current_exception</a></span>()</tt>.</p>
<p>To allow an exception to be cloned, <tt><span class="RenoLink"><a href="enable_exception_cloning.html">enable_exception_cloning</a></span>()</tt> must be used at the time the exception object is passed to <tt>throw</tt>. Otherwise, calling <tt><span class="RenoLink"><a href="clone_exception.html">clone_exception</a></span>()</tt> returns an <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> which refers to an instance of <tt><span class="RenoLink"><a href="unknown_exception.html">unknown_exception</a></span></tt>.</p>
</div><h2>Throwing Exceptions</h2> </div><h2>Throwing Exceptions</h2>
<div class="RenoIncludeDIV"><h3>throw_exception()</h3> <div class="RenoIncludeDIV"><h3>throw_exception()</h3>
<div class="RenoIncludeDIV"><p><tt>#include &lt;<span class="RenoLink"><a href="throw_exception_hpp.html">boost/throw_exception.hpp</a></span>&gt;</tt></p> <div class="RenoIncludeDIV"><p><tt>#include &lt;<span class="RenoLink"><a href="throw_exception_hpp.html">boost/throw_exception.hpp</a></span>&gt;</tt></p>
@ -390,7 +402,7 @@ boost
#endif</span> #endif</span>
}</pre> }</pre>
</div><h4>Effects:</h4> </div><h4>Effects:</h4>
<div><ul><li> If <tt>BOOST_NO_EXCEPTIONS</tt> is not defined, <tt>boost::<span class="RenoLink"><a href="throw_exception.html">throw_exception</a></span>(e)</tt> is equivalent to <tt>throw boost::<span class="RenoLink"><a href="enable_exception_cloning.html">enable_exception_cloning</a></span>(boost::<span class="RenoLink"><a href="enable_error_info.html">enable_error_info</a></span>(e))</tt>, unless <tt>BOOST_EXCEPTION_DISABLE</tt> is defined, in which case <tt>boost::<span class="RenoLink"><a href="throw_exception.html">throw_exception</a></span>(e)</tt> is equivalent to <tt>throw e;</tt></li> <div><ul><li> If <tt>BOOST_NO_EXCEPTIONS</tt> is not defined, <tt>boost::<span class="RenoLink"><a href="throw_exception.html">throw_exception</a></span>(e)</tt> is equivalent to <tt>throw boost::<span class="RenoLink"><a href="enable_current_exception.html">enable_current_exception</a></span>(boost::<span class="RenoLink"><a href="enable_error_info.html">enable_error_info</a></span>(e))</tt>, unless <tt>BOOST_EXCEPTION_DISABLE</tt> is defined, in which case <tt>boost::<span class="RenoLink"><a href="throw_exception.html">throw_exception</a></span>(e)</tt> is equivalent to <tt>throw e;</tt></li>
<li> If <tt>BOOST_NO_EXCEPTIONS</tt> is defined, the function is left undefined, and the user is expected to supply an appropriate definition. Callers of <tt>throw_exception</tt> are allowed to assume that the function never returns; therefore, if the user-defined <tt>throw_exception</tt> returns, the behavior is undefined.</li> <li> If <tt>BOOST_NO_EXCEPTIONS</tt> is defined, the function is left undefined, and the user is expected to supply an appropriate definition. Callers of <tt>throw_exception</tt> are allowed to assume that the function never returns; therefore, if the user-defined <tt>throw_exception</tt> returns, the behavior is undefined.</li>
</ul></div> </ul></div>
</div><div id="footer"> </div><div id="footer">

24
doc/cloning.html
View File

@ -17,12 +17,12 @@
<h1>Boost Exception</h1> <h1>Boost Exception</h1>
</div> </div>
<div class="RenoIncludeDIV"><h2>Transporting of Exceptions between Threads</h2> <div class="RenoIncludeDIV"><h2>Transporting of Exceptions between Threads</h2>
<p>Boost Exception supports transporting of exception objects between threads through cloning. This system is similar to <span class="RenoLink"><a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2179.html">N2179</a></span>, but because Boost Exception can not rely on language support, the use of <tt><span class="RenoLink"><a href="enable_exception_cloning.html">enable_exception_cloning</a></span>()</tt> at the time of the throw is required in order to use cloning.</p> <p>Boost Exception supports transporting of exception objects between threads through cloning. This system is similar to <span class="RenoLink"><a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2179.html">N2179</a></span>, but because Boost Exception can not rely on language support, the use of <tt><span class="RenoLink"><a href="enable_current_exception.html">enable_current_exception</a></span>()</tt> at the time of the throw is required in order to use cloning.</p>
<h4>Note:</h4> <h4>Note:</h4>
<p>All exceptions emitted by the familiar function <tt>boost::<span class="RenoLink"><a href="throw_exception.html">throw_exception</a></span>()</tt> are guaranteed to derive from <tt>boost::<span class="RenoLink"><a href="exception.html">exception</a></span></tt> and to support cloning.</p> <p>All exceptions emitted by the familiar function <tt>boost::<span class="RenoLink"><a href="throw_exception.html">throw_exception</a></span>()</tt> are guaranteed to derive from <tt>boost::<span class="RenoLink"><a href="exception.html">exception</a></span></tt> and to support cloning.</p>
<div class="RenoIncludeDIV"><h3>Using enable_exception_cloning() at the Time of the Throw</h3> <div class="RenoIncludeDIV"><h3>Using enable_current_exception() at the Time of the Throw</h3>
<p>Here is how cloning can be enabled in a throw-expression (15.1):</p> <p>Here is how cloning can be enabled in a throw-expression (15.1):</p>
<pre>#include &lt;<span class="RenoLink"><a href="exception_enable_exception_cloning_hpp.html">boost/exception/enable_exception_cloning.hpp</a></span>&gt; <pre>#include &lt;<span class="RenoLink"><a href="exception_enable_exception_cloning_hpp.html">boost/exception/enable_current_exception.hpp</a></span>&gt;
#include &lt;<span class="RenoLink"><a href="exception_error_info_hpp.html">boost/exception/info.hpp</a></span>&gt; #include &lt;<span class="RenoLink"><a href="exception_error_info_hpp.html">boost/exception/info.hpp</a></span>&gt;
#include &lt;stdio.h&gt; #include &lt;stdio.h&gt;
#include &lt;errno.h&gt; #include &lt;errno.h&gt;
@ -35,12 +35,12 @@ void
file_read( FILE * f, void * buffer, size_t size ) file_read( FILE * f, void * buffer, size_t size )
{ {
if( size!=fread(buffer,1,size,f) ) if( size!=fread(buffer,1,size,f) )
throw boost::<span class="RenoLink"><a href="enable_exception_cloning.html">enable_exception_cloning</a></span>(file_read_error()) &lt;&lt; throw boost::<span class="RenoLink"><a href="enable_current_exception.html">enable_current_exception</a></span>(file_read_error()) &lt;&lt;
errno_info(errno); errno_info(errno);
}</pre> }</pre>
</div><div class="RenoIncludeDIV"><h3>Cloning and Re-throwing an Exception</h3> </div><div class="RenoIncludeDIV"><h3>Cloning and Re-throwing an Exception</h3>
<p>When you catch a <tt>boost::<span class="RenoLink"><a href="exception.html">exception</a></span></tt>, you can call <tt><span class="RenoLink"><a href="clone_exception.html">clone_exception</a></span>()</tt> to get an <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> object:</p> <p>When you catch a <tt>boost::<span class="RenoLink"><a href="exception.html">exception</a></span></tt>, you can call <tt><span class="RenoLink"><a href="current_exception.html">current_exception</a></span>()</tt> to get an <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> object:</p>
<pre>#include &lt;<span class="RenoLink"><a href="exception_cloning_hpp.html">boost/exception/cloning.hpp</a></span>&gt; <pre>#include &lt;<span class="RenoLink"><a href="exception_cloning_hpp.html">boost/exception_ptr.hpp</a></span>&gt;
#include &lt;boost/thread.hpp&gt; #include &lt;boost/thread.hpp&gt;
#include &lt;boost/bind.hpp&gt; #include &lt;boost/bind.hpp&gt;
@ -55,12 +55,12 @@ worker_thread( boost::<span class="RenoLink"><a href="exception_ptr.html">except
error = boost::<span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span>(); error = boost::<span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span>();
} }
catch( catch(
boost::<span class="RenoLink"><a href="exception.html">exception</a></span> &amp; e ) ... )
{ {
error = boost::<span class="RenoLink"><a href="clone_exception.html">clone_exception</a></span>(e); error = boost::<span class="RenoLink"><a href="current_exception.html">current_exception</a></span>();
} }
}</pre> }</pre>
<p>In the above example, note that <tt><span class="RenoLink"><a href="clone_exception.html">clone_exception</a></span>()</tt> captures the original type of the exception object, even though <tt>e</tt> refers to the base type <tt>boost::<span class="RenoLink"><a href="exception.html">exception</a></span></tt>. This original type can be thrown again using the <tt><span class="RenoLink"><a href="rethrow_exception.html">rethrow_exception</a></span>()</tt> function:</p> <p>In the above example, note that <tt><span class="RenoLink"><a href="current_exception.html">current_exception</a></span>()</tt> captures the original type of the exception object, even though <tt>e</tt> refers to the base type <tt>boost::<span class="RenoLink"><a href="exception.html">exception</a></span></tt>. This original type can be thrown again using the <tt><span class="RenoLink"><a href="rethrow_exception.html">rethrow_exception</a></span>()</tt> function:</p>
<pre>// ...continued <pre>// ...continued
void void
@ -72,11 +72,11 @@ work()
if( error ) if( error )
boost::<span class="RenoLink"><a href="rethrow_exception.html">rethrow_exception</a></span>(error); boost::<span class="RenoLink"><a href="rethrow_exception.html">rethrow_exception</a></span>(error);
}</pre> }</pre>
<p><tt><span class="RenoLink"><a href="clone_exception.html">Clone_exception</a></span>()</tt> could fail to copy the original exception object in the following cases:</p> <p><tt><span class="RenoLink"><a href="current_exception.html">Clone_exception</a></span>()</tt> could fail to copy the original exception object in the following cases:</p>
<div><ul><li> if there is not enough memory, in which case the returned <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> points to an instance of <tt>std::bad_alloc</tt>, or</li> <div><ul><li> if there is not enough memory, in which case the returned <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> points to an instance of <tt>std::bad_alloc</tt>, or</li>
<li> if <tt><span class="RenoLink"><a href="enable_exception_cloning.html">enable_exception_cloning</a></span>()</tt> was not used in the throw-expression passed to the original <tt>throw</tt> statement, in which case the returned <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> points to an instance of <tt><span class="RenoLink"><a href="unknown_exception.html">unknown_exception</a></span></tt>.</li> <li> if <tt><span class="RenoLink"><a href="enable_current_exception.html">enable_current_exception</a></span>()</tt> was not used in the throw-expression passed to the original <tt>throw</tt> statement, in which case the returned <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> points to an instance of <tt><span class="RenoLink"><a href="unknown_exception.html">unknown_exception</a></span></tt>.</li>
</ul></div> </ul></div>
<p>Regardless, the use of <tt><span class="RenoLink"><a href="clone_exception.html">clone_exception</a></span>()</tt> and <tt><span class="RenoLink"><a href="rethrow_exception.html">rethrow_exception</a></span>()</tt> in the above examples is well-formed.</p> <p>Regardless, the use of <tt><span class="RenoLink"><a href="current_exception.html">current_exception</a></span>()</tt> and <tt><span class="RenoLink"><a href="rethrow_exception.html">rethrow_exception</a></span>()</tt> in the above examples is well-formed.</p>
</div></div><h3>See also:</h3> </div></div><h3>See also:</h3>
<div class="RenoPageList"><a href="boost-exception.html">Boost Exception<br/> <div class="RenoPageList"><a href="boost-exception.html">Boost Exception<br/>
</a><a href="unknown_exception.html">unknown_exception<br/> </a><a href="unknown_exception.html">unknown_exception<br/>

75
doc/cloning_and_rethrowing.html Normal file
View File

@ -0,0 +1,75 @@
<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN'
'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>
<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'>
<head>
<meta http-equiv='Content-Type' content='text/html; charset=utf-8'/>
<title>Tutorial: Cloning and Re-throwing an Exception</title>
<link href='reno.css' type='text/css' rel='stylesheet'/>
</head>
<body>
<div class="body-0">
<div class="body-1">
<div class="body-2">
<div>
<div id="boost_logo">
<a href="http://www.boost.org"><img style="border:0" src="http://www.boost.org/boost.png" alt="Boost" width="277" height="86"/></a>
</div>
<h1>Boost Exception</h1>
</div>
<div class="RenoIncludeDIV"><h3>Cloning and Re-throwing an Exception</h3>
<p>When you catch a <tt>boost::<span class="RenoLink"><a href="exception.html">exception</a></span></tt>, you can call <tt><span class="RenoLink"><a href="current_exception.html">current_exception</a></span>()</tt> to get an <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> object:</p>
<pre>#include &lt;<span class="RenoLink"><a href="exception_cloning_hpp.html">boost/exception_ptr.hpp</a></span>&gt;
#include &lt;boost/thread.hpp&gt;
#include &lt;boost/bind.hpp&gt;
void do_work(); //throws cloning-enabled boost::<span class="RenoLink"><a href="exception.html">exception</a></span>s
void
worker_thread( boost::<span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span> &amp; error )
{
try
{
do_work();
error = boost::<span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span>();
}
catch(
... )
{
error = boost::<span class="RenoLink"><a href="current_exception.html">current_exception</a></span>();
}
}</pre>
<p>In the above example, note that <tt><span class="RenoLink"><a href="current_exception.html">current_exception</a></span>()</tt> captures the original type of the exception object, even though <tt>e</tt> refers to the base type <tt>boost::<span class="RenoLink"><a href="exception.html">exception</a></span></tt>. This original type can be thrown again using the <tt><span class="RenoLink"><a href="rethrow_exception.html">rethrow_exception</a></span>()</tt> function:</p>
<pre>// ...continued
void
work()
{
boost::<span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span> error;
boost::<span class="RenoLink"><a href="http://www.boost.org/doc/html/boost/thread.html">thread</a></span> t( boost::<span class="RenoLink"><a href="http://www.boost.org/libs/bind/bind.html">bind</a></span>(worker_thread,boost::<span class="RenoLink"><a href="http://www.boost.org/doc/html/ref.html">ref</a></span>(error)) );
t.<span class="RenoLink"><a href="http://www.boost.org/doc/html/boost/thread.html">join</a></span>();
if( error )
boost::<span class="RenoLink"><a href="rethrow_exception.html">rethrow_exception</a></span>(error);
}</pre>
<p><tt><span class="RenoLink"><a href="current_exception.html">Clone_exception</a></span>()</tt> could fail to copy the original exception object in the following cases:</p>
<div><ul><li> if there is not enough memory, in which case the returned <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> points to an instance of <tt>std::bad_alloc</tt>, or</li>
<li> if <tt><span class="RenoLink"><a href="enable_current_exception.html">enable_current_exception</a></span>()</tt> was not used in the throw-expression passed to the original <tt>throw</tt> statement, in which case the returned <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> points to an instance of <tt><span class="RenoLink"><a href="unknown_exception.html">unknown_exception</a></span></tt>.</li>
</ul></div>
<p>Regardless, the use of <tt><span class="RenoLink"><a href="current_exception.html">current_exception</a></span>()</tt> and <tt><span class="RenoLink"><a href="rethrow_exception.html">rethrow_exception</a></span>()</tt> in the above examples is well-formed.</p>
</div><h3>See also:</h3>
<div class="RenoPageList"><a href="cloning.html">Tutorial: Transporting of Exceptions between Threads<br/>
</a></div>
<div id="footer">
<p>&nbsp;</p>
<hr/>
<p>
<a class="logo" href="http://jigsaw.w3.org/css-validator/validator?uri=http://revergestudios.com/boost-exception/reno.css"><img class="logo_pic" src="valid-css.png" alt="Valid CSS" height="31" width="88"/></a>
<a class="logo" href="http://validator.w3.org/check?uri=referer"><img class="logo_pic" src="valid-xhtml.png" alt="Valid XHTML 1.0" height="31" width="88"/></a>
<small>Copyright (c) 2006-2008 by Emil Dotchevski and Reverge Studios, Inc.<br/>
Distributed under the <a href="http://www.boost.org/LICENSE_1_0.txt">Boost Software License, Version 1.0</a>.</small>
</p>
</div>
</div>
</div>
</div>
</body>
</html>

47
doc/copy_exception.html Normal file
View File

@ -0,0 +1,47 @@
<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN'
'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>
<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'>
<head>
<meta http-equiv='Content-Type' content='text/html; charset=utf-8'/>
<title>copy_exception</title>
<link href='reno.css' type='text/css' rel='stylesheet'/>
</head>
<body>
<div class="body-0">
<div class="body-1">
<div class="body-2">
<div>
<div id="boost_logo">
<a href="http://www.boost.org"><img style="border:0" src="http://www.boost.org/boost.png" alt="Boost" width="277" height="86"/></a>
</div>
<h1>Boost Exception</h1>
</div>
<div class="RenoIncludeDIV"><h3>copy_exception()</h3>
<div class="RenoIncludeDIV"><p><tt>#include &lt;<span class="RenoLink"><a href="exception_cloning_hpp.html">boost/exception_ptr.hpp</a></span>&gt;</tt></p>
<pre>namespace
boost
{
<span class="RenoIncludeSPAN"> template &lt;class T&gt;
<span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span> <span class="RenoLink"><a href="copy_exception.html">copy_exception</a></span>( T const &amp; e );</span>
}</pre>
</div><h4>Effects:</h4>
<p>As if <tt>try { throw e; } catch( ... ) { return <span class="RenoLink"><a href="current_exception.html">current_exception</a></span>(); }</tt></p>
</div><h3>See also:</h3>
<div class="RenoPageList"><a href="boost-exception.html">Boost Exception<br/>
</a><a href="exception_ptr.html">exception_ptr<br/>
</a></div>
<div id="footer">
<p>&nbsp;</p>
<hr/>
<p>
<a class="logo" href="http://jigsaw.w3.org/css-validator/validator?uri=http://revergestudios.com/boost-exception/reno.css"><img class="logo_pic" src="valid-css.png" alt="Valid CSS" height="31" width="88"/></a>
<a class="logo" href="http://validator.w3.org/check?uri=referer"><img class="logo_pic" src="valid-xhtml.png" alt="Valid XHTML 1.0" height="31" width="88"/></a>
<small>Copyright (c) 2006-2008 by Emil Dotchevski and Reverge Studios, Inc.<br/>
Distributed under the <a href="http://www.boost.org/LICENSE_1_0.txt">Boost Software License, Version 1.0</a>.</small>
</p>
</div>
</div>
</div>
</div>
</body>
</html>

57
doc/current_exception.html Normal file
View File

@ -0,0 +1,57 @@
<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN'
'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>
<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'>
<head>
<meta http-equiv='Content-Type' content='text/html; charset=utf-8'/>
<title>current_exception</title>
<link href='reno.css' type='text/css' rel='stylesheet'/>
</head>
<body>
<div class="body-0">
<div class="body-1">
<div class="body-2">
<div>
<div id="boost_logo">
<a href="http://www.boost.org"><img style="border:0" src="http://www.boost.org/boost.png" alt="Boost" width="277" height="86"/></a>
</div>
<h1>Boost Exception</h1>
</div>
<div class="RenoIncludeDIV"><h3>current_exception()</h3>
<div class="RenoIncludeDIV"><p><tt>#include &lt;<span class="RenoLink"><a href="exception_cloning_hpp.html">boost/exception_ptr.hpp</a></span>&gt;</tt></p>
<pre>namespace
boost
{
<span class="RenoIncludeSPAN"> <span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span> <span class="RenoLink"><a href="current_exception.html">current_exception</a></span>();</span>
}</pre>
</div><h4>Requirements:</h4>
<p>The <tt><span class="RenoLink"><a href="current_exception.html">current_exception</a></span>()</tt> function must not be called outside of a <tt>catch</tt> block.</p>
<h4>Returns:</h4>
<div><ul><li> An <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> that refers to the currently handled exception or a copy of the currently handled exception.</li>
<li> If the function needs to allocate memory and the attempt fails, it returns an <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> that refers to an instance of <tt>std::bad_alloc</tt>.</li>
</ul></div>
<h4>Notes:</h4>
<div><ul><li> It is unspecified whether the return values of two successive calls to <tt><span class="RenoLink"><a href="current_exception.html">current_exception</a></span>()</tt> refer to the same exception object.</li>
<li> Correct implementation of <tt><span class="RenoLink"><a href="current_exception.html">current_exception</a></span>()</tt> may require compiler support, unless <tt><span class="RenoLink"><a href="enable_current_exception.html">enable_current_exception</a></span>()</tt> is used at the time the currently handled exception object was passed to <tt>throw</tt>. If <tt><span class="RenoLink"><a href="enable_current_exception.html">enable_current_exception</a></span>()</tt> is not used, and if the compiler does not provide the necessary support, then <tt><span class="RenoLink"><a href="current_exception.html">current_exception</a></span>()</tt> may return an <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> that refers to an instance of <tt><span class="RenoLink"><a href="unknown_exception.html">unknown_exception</a></span></tt>. In this case, if the original exception object derives from <tt>boost::<span class="RenoLink"><a href="exception.html">exception</a></span></tt>, then the <tt>boost::<span class="RenoLink"><a href="exception.html">exception</a></span></tt> sub-object of the <tt><span class="RenoLink"><a href="unknown_exception.html">unknown_exception</a></span></tt> object is initialized by the <tt>boost::<span class="RenoLink"><a href="exception.html">exception</a></span></tt> copy constructor.</li>
</ul></div>
</div><h3>See also:</h3>
<div class="RenoPageList"><a href="boost-exception.html">Boost Exception<br/>
</a><a href="copy_exception.html">copy_exception<br/>
</a><a href="enable_current_exception.html">enable_current_exception<br/>
</a><a href="exception_ptr.html">exception_ptr<br/>
</a><a href="unknown_exception.html">unknown_exception<br/>
</a></div>
<div id="footer">
<p>&nbsp;</p>
<hr/>
<p>
<a class="logo" href="http://jigsaw.w3.org/css-validator/validator?uri=http://revergestudios.com/boost-exception/reno.css"><img class="logo_pic" src="valid-css.png" alt="Valid CSS" height="31" width="88"/></a>
<a class="logo" href="http://validator.w3.org/check?uri=referer"><img class="logo_pic" src="valid-xhtml.png" alt="Valid XHTML 1.0" height="31" width="88"/></a>
<small>Copyright (c) 2006-2008 by Emil Dotchevski and Reverge Studios, Inc.<br/>
Distributed under the <a href="http://www.boost.org/LICENSE_1_0.txt">Boost Software License, Version 1.0</a>.</small>
</p>
</div>
</div>
</div>
</div>
</body>
</html>

64
doc/enable_current_exception.html Normal file
View File

@ -0,0 +1,64 @@
<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN'
'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>
<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'>
<head>
<meta http-equiv='Content-Type' content='text/html; charset=utf-8'/>
<title>enable_current_exception</title>
<link href='reno.css' type='text/css' rel='stylesheet'/>
</head>
<body>
<div class="body-0">
<div class="body-1">
<div class="body-2">
<div>
<div id="boost_logo">
<a href="http://www.boost.org"><img style="border:0" src="http://www.boost.org/boost.png" alt="Boost" width="277" height="86"/></a>
</div>
<h1>Boost Exception</h1>
</div>
<div class="RenoIncludeDIV"><h3>enable_current_exception()</h3>
<div class="RenoIncludeDIV"><p><tt>#include &lt;<span class="RenoLink"><a href="exception_enable_exception_cloning_hpp.html">boost/exception/enable_current_exception.hpp</a></span>&gt;</tt></p>
<pre>namespace
boost
{
<span class="RenoIncludeSPAN"> template &lt;class T&gt;
---unspecified--- <span class="RenoLink"><a href="enable_current_exception.html">enable_current_exception</a></span>( T const &amp; e );</span>
}</pre>
</div><h4>Requirements:</h4>
<p><tt>T</tt> must have an accessible no-throw copy constructor</p>
<h4>Returns:</h4>
<p>An object of <i>unspecified</i> type which derives publicly from <tt>T</tt>. That is, the returned object can be intercepted by a <tt>catch(T &amp;)</tt>.</p>
<h4>Description:</h4>
<p>This function is designed to be used directly in a throw-expression to enable the cloning support in Boost Exception. For example:</p>
<pre>class
my_exception:
public std::exception
{
};
....
throw boost::<span class="RenoLink"><a href="enable_current_exception.html">enable_current_exception</a></span>(my_exception());</pre>
<p>Unless <tt><span class="RenoLink"><a href="enable_current_exception.html">enable_current_exception</a></span>()</tt> is called at the time an exception object is used in a throw-expression, any attempt to copy it using <tt><span class="RenoLink"><a href="current_exception.html">current_exception</a></span>()</tt> returns an <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> which refers to an instance of <tt><span class="RenoLink"><a href="unknown_exception.html">unknown_exception</a></span></tt>.</p>
<h4>Note:</h4>
<p>Instead of using the <tt>throw</tt> keyword directly, it is preferable to call <tt>boost::<span class="RenoLink"><a href="throw_exception.html">throw_exception</a></span>()</tt>. This is guaranteed to throw an exception that derives from <tt>boost::<span class="RenoLink"><a href="exception.html">exception</a></span></tt> and supports cloning.</p>
</div><h3>See also:</h3>
<div class="RenoPageList"><a href="boost-exception.html">Boost Exception<br/>
</a><a href="current_exception.html">current_exception<br/>
</a><a href="cloning.html">Tutorial: Transporting of Exceptions between Threads<br/>
</a><a href="throw_exception.html">throw_exception<br/>
</a></div>
<div id="footer">
<p>&nbsp;</p>
<hr/>
<p>
<a class="logo" href="http://jigsaw.w3.org/css-validator/validator?uri=http://revergestudios.com/boost-exception/reno.css"><img class="logo_pic" src="valid-css.png" alt="Valid CSS" height="31" width="88"/></a>
<a class="logo" href="http://validator.w3.org/check?uri=referer"><img class="logo_pic" src="valid-xhtml.png" alt="Valid XHTML 1.0" height="31" width="88"/></a>
<small>Copyright (c) 2006-2008 by Emil Dotchevski and Reverge Studios, Inc.<br/>
Distributed under the <a href="http://www.boost.org/LICENSE_1_0.txt">Boost Software License, Version 1.0</a>.</small>
</p>
</div>
</div>
</div>
</div>
</body>
</html>

5
doc/exception.html
View File

@ -68,11 +68,10 @@ boost
</div></div></div><h3>See also:</h3> </div></div></div><h3>See also:</h3>
<div class="RenoPageList"><a href="BOOST_ERROR_INFO.html">BOOST_ERROR_INFO<br/> <div class="RenoPageList"><a href="BOOST_ERROR_INFO.html">BOOST_ERROR_INFO<br/>
</a><a href="boost-exception.html">Boost Exception<br/> </a><a href="boost-exception.html">Boost Exception<br/>
</a><a href="clone_exception.html">clone_exception<br/> </a><a href="current_exception.html">current_exception<br/>
</a><a href="enable_current_exception.html">enable_current_exception<br/>
</a><a href="enable_error_info.html">enable_error_info<br/> </a><a href="enable_error_info.html">enable_error_info<br/>
</a><a href="enable_exception_cloning.html">enable_exception_cloning<br/>
</a><a href="error_info.html">error_info<br/> </a><a href="error_info.html">error_info<br/>
</a><a href="exception_ptr.html">exception_ptr<br/>
</a><a href="get_error_info.html">get_error_info<br/> </a><a href="get_error_info.html">get_error_info<br/>
</a><a href="operator_shl_exception.html">operator&lt;&lt;/exception<br/> </a><a href="operator_shl_exception.html">operator&lt;&lt;/exception<br/>
</a><a href="using_enable_error_info.html">Tutorial: Integrating Boost Exception in Existing Exception Class Hierarchies<br/> </a><a href="using_enable_error_info.html">Tutorial: Integrating Boost Exception in Existing Exception Class Hierarchies<br/>

7
doc/exception_cloning_hpp.html
View File

@ -3,7 +3,7 @@
<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'> <html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'>
<head> <head>
<meta http-equiv='Content-Type' content='text/html; charset=utf-8'/> <meta http-equiv='Content-Type' content='text/html; charset=utf-8'/>
<title>boost/exception/cloning.hpp</title> <title>boost/exception_ptr.hpp</title>
<link href='reno.css' type='text/css' rel='stylesheet'/> <link href='reno.css' type='text/css' rel='stylesheet'/>
</head> </head>
<body> <body>
@ -16,9 +16,10 @@
</div> </div>
<h1>Boost Exception</h1> <h1>Boost Exception</h1>
</div> </div>
<h3>boost/exception/cloning.hpp</h3> <h3>boost/exception_ptr.hpp</h3>
<p>This header file contains the following definitions/declarations:</p> <p>This header file contains the following definitions/declarations:</p>
<div class="RenoPageList"><a href="clone_exception.html">clone_exception<br/> <div class="RenoPageList"><a href="copy_exception.html">copy_exception<br/>
</a><a href="current_exception.html">current_exception<br/>
</a><a href="exception_ptr.html">exception_ptr<br/> </a><a href="exception_ptr.html">exception_ptr<br/>
</a><a href="rethrow_exception.html">rethrow_exception<br/> </a><a href="rethrow_exception.html">rethrow_exception<br/>
</a><a href="unknown_exception.html">unknown_exception<br/> </a><a href="unknown_exception.html">unknown_exception<br/>

6
doc/exception_enable_exception_cloning_hpp.html
View File

@ -3,7 +3,7 @@
<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'> <html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'>
<head> <head>
<meta http-equiv='Content-Type' content='text/html; charset=utf-8'/> <meta http-equiv='Content-Type' content='text/html; charset=utf-8'/>
<title>boost/exception/enable_exception_cloning.hpp</title> <title>boost/exception/enable_current_exception.hpp</title>
<link href='reno.css' type='text/css' rel='stylesheet'/> <link href='reno.css' type='text/css' rel='stylesheet'/>
</head> </head>
<body> <body>
@ -16,9 +16,9 @@
</div> </div>
<h1>Boost Exception</h1> <h1>Boost Exception</h1>
</div> </div>
<h3>boost/exception/enable_exception_cloning.hpp</h3> <h3>boost/exception/enable_current_exception.hpp</h3>
<p>This header file contains the following definitions/declarations:</p> <p>This header file contains the following definitions/declarations:</p>
<div class="RenoPageList"><a href="enable_exception_cloning.html">enable_exception_cloning<br/> <div class="RenoPageList"><a href="enable_current_exception.html">enable_current_exception<br/>
</a></div> </a></div>
<div id="footer"> <div id="footer">
<p>&nbsp;</p> <p>&nbsp;</p>

4
doc/exception_hpp.html
View File

@ -19,13 +19,13 @@
<h3>boost/exception.hpp</h3> <h3>boost/exception.hpp</h3>
<p>This header file includes all other header files of Boost Exception:</p> <p>This header file includes all other header files of Boost Exception:</p>
<div class="RenoPageList"><a href="exception_hpp.html">boost/exception.hpp<br/> <div class="RenoPageList"><a href="exception_hpp.html">boost/exception.hpp<br/>
</a><a href="exception_cloning_hpp.html">boost/exception/cloning.hpp<br/> </a><a href="exception_enable_exception_cloning_hpp.html">boost/exception/enable_current_exception.hpp<br/>
</a><a href="exception_enable_error_info_hpp.html">boost/exception/enable_error_info.hpp<br/> </a><a href="exception_enable_error_info_hpp.html">boost/exception/enable_error_info.hpp<br/>
</a><a href="exception_enable_exception_cloning_hpp.html">boost/exception/enable_exception_cloning.hpp<br/>
</a><a href="exception_error_info_value_hpp.html">boost/exception/error_info.hpp<br/> </a><a href="exception_error_info_value_hpp.html">boost/exception/error_info.hpp<br/>
</a><a href="exception_exception_hpp.html">boost/exception/exception.hpp<br/> </a><a href="exception_exception_hpp.html">boost/exception/exception.hpp<br/>
</a><a href="exception_error_info_hpp.html">boost/exception/info.hpp<br/> </a><a href="exception_error_info_hpp.html">boost/exception/info.hpp<br/>
</a><a href="exception_error_info_group_hpp.html">boost/exception/info_tuple.hpp<br/> </a><a href="exception_error_info_group_hpp.html">boost/exception/info_tuple.hpp<br/>
</a><a href="exception_cloning_hpp.html">boost/exception_ptr.hpp<br/>
</a><a href="throw_exception_hpp.html">boost/throw_exception.hpp<br/> </a><a href="throw_exception_hpp.html">boost/throw_exception.hpp<br/>
</a></div> </a></div>
<div id="footer"> <div id="footer">

12
doc/exception_ptr.html
View File

@ -17,21 +17,23 @@
<h1>Boost Exception</h1> <h1>Boost Exception</h1>
</div> </div>
<div class="RenoIncludeDIV"><h3>exception_ptr</h3> <div class="RenoIncludeDIV"><h3>exception_ptr</h3>
<div class="RenoIncludeDIV"><p><tt>#include &lt;<span class="RenoLink"><a href="exception_cloning_hpp.html">boost/exception/cloning.hpp</a></span>&gt;</tt></p> <div class="RenoIncludeDIV"><p><tt>#include &lt;<span class="RenoLink"><a href="exception_cloning_hpp.html">boost/exception_ptr.hpp</a></span>&gt;</tt></p>
<pre>namespace <pre>namespace
boost boost
{ {
<span class="RenoIncludeSPAN"> typedef ---unspecified--- <span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span>;</span> <span class="RenoIncludeSPAN"> typedef ---unspecified--- <span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span>;</span>
}</pre> }</pre>
</div><p>The <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> type can be used to refer to a copy of a <tt>boost::<span class="RenoLink"><a href="exception.html">exception</a></span></tt> object. It is Default Constructible, Copy Constructible, Assignable and Equality Comparable; <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt>'s operations do not throw.</p> </div><p>The <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> type can be used to refer to a copy of an exception object. It is Default Constructible, Copy Constructible, Assignable and Equality Comparable; <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt>'s operations do not throw.</p>
<p>Two instances of <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> are equivalent and compare equal if and only if they refer to the same exception.</p> <p>Two instances of <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> are equivalent and compare equal if and only if they refer to the same exception.</p>
<p>The default constructor of <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> produces the null value of the type. The null value is equivalent only to itself.</p> <p>The default constructor of <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> produces the null value of the type. The null value is equivalent only to itself.</p>
<h4>Note:</h4>
<p><tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> objects are returned by <tt><span class="RenoLink"><a href="current_exception.html">current_exception</a></span>()</tt> and <tt><span class="RenoLink"><a href="copy_exception.html">copy_exception</a></span>()</tt>.</p>
</div><h3>See also:</h3> </div><h3>See also:</h3>
<div class="RenoPageList"><a href="boost-exception.html">Boost Exception<br/> <div class="RenoPageList"><a href="boost-exception.html">Boost Exception<br/>
</a><a href="clone_exception.html">clone_exception<br/> </a><a href="copy_exception.html">copy_exception<br/>
</a><a href="enable_exception_cloning.html">enable_exception_cloning<br/> </a><a href="current_exception.html">current_exception<br/>
</a><a href="enable_current_exception.html">enable_current_exception<br/>
</a><a href="rethrow_exception.html">rethrow_exception<br/> </a><a href="rethrow_exception.html">rethrow_exception<br/>
</a><a href="unknown_exception.html">unknown_exception<br/>
</a></div> </a></div>
<div id="footer"> <div id="footer">
<p>&nbsp;</p> <p>&nbsp;</p>

62
doc/grouping_data.html Normal file
View File

@ -0,0 +1,62 @@
<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN'
'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>
<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'>
<head>
<meta http-equiv='Content-Type' content='text/html; charset=utf-8'/>
<title>Tutorial: Adding Grouped Data to Exceptions</title>
<link href='reno.css' type='text/css' rel='stylesheet'/>
</head>
<body>
<div class="body-0">
<div class="body-1">
<div class="body-2">
<div>
<div id="boost_logo">
<a href="http://www.boost.org"><img style="border:0" src="http://www.boost.org/boost.png" alt="Boost" width="277" height="86"/></a>
</div>
<h1>Boost Exception</h1>
</div>
<div class="RenoIncludeDIV"><h3>Adding Grouped Data to Exceptions</h3>
<p>The code snippet below demonstrates how <tt>boost::<span class="RenoLink"><a href="http://www.boost.org/libs/tuple/doc/tuple_users_guide.html">tuple</a></span></tt> can be used to bundle the name of the function that failed, together with the reported <tt>errno</tt> so that they can be added to exception objects more conveniently together:</p>
<pre>#include &lt;<span class="RenoLink"><a href="exception_error_info_group_hpp.html">boost/exception/info_tuple.hpp</a></span>&gt;
#include &lt;boost/shared_ptr.hpp&gt;
#include &lt;stdio.h&gt;
#include &lt;string&gt;
#include &lt;errno.h&gt;
typedef boost::<span class="RenoLink"><a href="error_info.html">error_info</a></span>&lt;struct tag_file_name,std::string&gt; file_name_info;
typedef boost::<span class="RenoLink"><a href="error_info.html">error_info</a></span>&lt;struct tag_function,char const *&gt; function_info;
typedef boost::<span class="RenoLink"><a href="error_info.html">error_info</a></span>&lt;struct tag_errno,int&gt; errno_info;
typedef boost::tuple&lt;function_info,errno_info&gt; clib_failure;
class file_open_error: public boost::<span class="RenoLink"><a href="exception.html">exception</a></span> { };
boost::shared_ptr&lt;FILE&gt;
file_open( char const * name, char const * mode )
{
if( FILE * f=fopen(name,mode) )
return boost::shared_ptr&lt;FILE&gt;(f,fclose);
else
throw file_open_error() &lt;&lt;
file_name_info(name) &lt;&lt;
clib_failure("fopen",errno);
}</pre>
<p>Note that the members of a <tt>boost::<span class="RenoLink"><a href="http://www.boost.org/libs/tuple/doc/tuple_users_guide.html">tuple</a></span></tt> are stored separately in exception objects; they can only be retrieved individually, using <tt><span class="RenoLink"><a href="get_error_info.html">get_error_info</a></span>()</tt>.</p>
</div><h3>See also:</h3>
<div class="RenoPageList"><a href="transporting_data.html">Tutorial: Transporting of Arbitrary Data to the Catch Site<br/>
</a></div>
<div id="footer">
<p>&nbsp;</p>
<hr/>
<p>
<a class="logo" href="http://jigsaw.w3.org/css-validator/validator?uri=http://revergestudios.com/boost-exception/reno.css"><img class="logo_pic" src="valid-css.png" alt="Valid CSS" height="31" width="88"/></a>
<a class="logo" href="http://validator.w3.org/check?uri=referer"><img class="logo_pic" src="valid-xhtml.png" alt="Valid XHTML 1.0" height="31" width="88"/></a>
<small>Copyright (c) 2006-2008 by Emil Dotchevski and Reverge Studios, Inc.<br/>
Distributed under the <a href="http://www.boost.org/LICENSE_1_0.txt">Boost Software License, Version 1.0</a>.</small>
</p>
</div>
</div>
</div>
</div>
</body>
</html>

9
doc/name_idx.html
View File

@ -21,19 +21,20 @@
<p><a href="BOOST_ERROR_INFO.html">BOOST_ERROR_INFO</a></p> <p><a href="BOOST_ERROR_INFO.html">BOOST_ERROR_INFO</a></p>
<h3>b</h3> <h3>b</h3>
<p><a href="exception_hpp.html">boost/exception.hpp</a></p> <p><a href="exception_hpp.html">boost/exception.hpp</a></p>
<p><a href="exception_cloning_hpp.html">boost/exception/cloning.hpp</a></p> <p><a href="exception_enable_exception_cloning_hpp.html">boost/exception/enable_current_exception.hpp</a></p>
<p><a href="exception_enable_error_info_hpp.html">boost/exception/enable_error_info.hpp</a></p> <p><a href="exception_enable_error_info_hpp.html">boost/exception/enable_error_info.hpp</a></p>
<p><a href="exception_enable_exception_cloning_hpp.html">boost/exception/enable_exception_cloning.hpp</a></p>
<p><a href="exception_error_info_value_hpp.html">boost/exception/error_info.hpp</a></p> <p><a href="exception_error_info_value_hpp.html">boost/exception/error_info.hpp</a></p>
<p><a href="exception_exception_hpp.html">boost/exception/exception.hpp</a></p> <p><a href="exception_exception_hpp.html">boost/exception/exception.hpp</a></p>
<p><a href="exception_error_info_hpp.html">boost/exception/info.hpp</a></p> <p><a href="exception_error_info_hpp.html">boost/exception/info.hpp</a></p>
<p><a href="exception_error_info_group_hpp.html">boost/exception/info_tuple.hpp</a></p> <p><a href="exception_error_info_group_hpp.html">boost/exception/info_tuple.hpp</a></p>
<p><a href="exception_cloning_hpp.html">boost/exception_ptr.hpp</a></p>
<p><a href="throw_exception_hpp.html">boost/throw_exception.hpp</a></p> <p><a href="throw_exception_hpp.html">boost/throw_exception.hpp</a></p>
<h3>c</h3> <h3>c</h3>
<p><a href="clone_exception.html">clone_exception</a></p> <p><a href="copy_exception.html">copy_exception</a></p>
<p><a href="current_exception.html">current_exception</a></p>
<h3>e</h3> <h3>e</h3>
<p><a href="enable_current_exception.html">enable_current_exception</a></p>
<p><a href="enable_error_info.html">enable_error_info</a></p> <p><a href="enable_error_info.html">enable_error_info</a></p>
<p><a href="enable_exception_cloning.html">enable_exception_cloning</a></p>
<p><a href="error_info.html">error_info</a></p> <p><a href="error_info.html">error_info</a></p>
<p><a href="exception.html">exception</a></p> <p><a href="exception.html">exception</a></p>
<p><a href="exception_constructors.html">exception::exception</a></p> <p><a href="exception_constructors.html">exception::exception</a></p>

2
doc/rethrow_exception.html
View File

@ -17,7 +17,7 @@
<h1>Boost Exception</h1> <h1>Boost Exception</h1>
</div> </div>
<div class="RenoIncludeDIV"><h3>rethrow_exception()</h3> <div class="RenoIncludeDIV"><h3>rethrow_exception()</h3>
<div class="RenoIncludeDIV"><p><tt>#include &lt;<span class="RenoLink"><a href="exception_cloning_hpp.html">boost/exception/cloning.hpp</a></span>&gt;</tt></p> <div class="RenoIncludeDIV"><p><tt>#include &lt;<span class="RenoLink"><a href="exception_cloning_hpp.html">boost/exception_ptr.hpp</a></span>&gt;</tt></p>
<pre>namespace <pre>namespace
boost boost
{ {

5377
doc/boost-exception.reno → doc/source/boost-exception.reno
View File

File diff suppressed because it is too large Load Diff

18
doc/source/html_prefix.txt Normal file
View File

@ -0,0 +1,18 @@
<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN'
'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>
<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'>
<head>
<meta http-equiv='Content-Type' content='text/html; charset=utf-8'/>
<title>%s</title>
<link href='reno.css' type='text/css' rel='stylesheet'/>
</head>
<body>
<div class="body-0">
<div class="body-1">
<div class="body-2">
<div>
<div id="boost_logo">
<a href="http://www.boost.org"><img style="border:0" src="http://www.boost.org/boost.png" alt="Boost" width="277" height="86"/></a>
</div>
<h1>Boost Exception</h1>
</div>

15
doc/source/html_suffix.txt Normal file
View File

@ -0,0 +1,15 @@
<div id="footer">
<p>&nbsp;</p>
<hr/>
<p>
<a class="logo" href="http://jigsaw.w3.org/css-validator/validator?uri=http://revergestudios.com/boost-exception/reno.css"><img class="logo_pic" src="valid-css.png" alt="Valid CSS" height="31" width="88"/></a>
<a class="logo" href="http://validator.w3.org/check?uri=referer"><img class="logo_pic" src="valid-xhtml.png" alt="Valid XHTML 1.0" height="31" width="88"/></a>
<small>Copyright (c) 2006-2008 by Emil Dotchevski and Reverge Studios, Inc.<br/>
Distributed under the <a href="http://www.boost.org/LICENSE_1_0.txt">Boost Software License, Version 1.0</a>.</small>
</p>
</div>
</div>
</div>
</div>
</body>
</html>

4
doc/throw_exception.html
View File

@ -29,12 +29,12 @@ boost
#endif</span> #endif</span>
}</pre> }</pre>
</div><h4>Effects:</h4> </div><h4>Effects:</h4>
<div><ul><li> If <tt>BOOST_NO_EXCEPTIONS</tt> is not defined, <tt>boost::<span class="RenoLink"><a href="throw_exception.html">throw_exception</a></span>(e)</tt> is equivalent to <tt>throw boost::<span class="RenoLink"><a href="enable_exception_cloning.html">enable_exception_cloning</a></span>(boost::<span class="RenoLink"><a href="enable_error_info.html">enable_error_info</a></span>(e))</tt>, unless <tt>BOOST_EXCEPTION_DISABLE</tt> is defined, in which case <tt>boost::<span class="RenoLink"><a href="throw_exception.html">throw_exception</a></span>(e)</tt> is equivalent to <tt>throw e;</tt></li> <div><ul><li> If <tt>BOOST_NO_EXCEPTIONS</tt> is not defined, <tt>boost::<span class="RenoLink"><a href="throw_exception.html">throw_exception</a></span>(e)</tt> is equivalent to <tt>throw boost::<span class="RenoLink"><a href="enable_current_exception.html">enable_current_exception</a></span>(boost::<span class="RenoLink"><a href="enable_error_info.html">enable_error_info</a></span>(e))</tt>, unless <tt>BOOST_EXCEPTION_DISABLE</tt> is defined, in which case <tt>boost::<span class="RenoLink"><a href="throw_exception.html">throw_exception</a></span>(e)</tt> is equivalent to <tt>throw e;</tt></li>
<li> If <tt>BOOST_NO_EXCEPTIONS</tt> is defined, the function is left undefined, and the user is expected to supply an appropriate definition. Callers of <tt>throw_exception</tt> are allowed to assume that the function never returns; therefore, if the user-defined <tt>throw_exception</tt> returns, the behavior is undefined.</li> <li> If <tt>BOOST_NO_EXCEPTIONS</tt> is defined, the function is left undefined, and the user is expected to supply an appropriate definition. Callers of <tt>throw_exception</tt> are allowed to assume that the function never returns; therefore, if the user-defined <tt>throw_exception</tt> returns, the behavior is undefined.</li>
</ul></div> </ul></div>
</div><h3>See also:</h3> </div><h3>See also:</h3>
<div class="RenoPageList"><a href="boost-exception.html">Boost Exception<br/> <div class="RenoPageList"><a href="boost-exception.html">Boost Exception<br/>
</a><a href="enable_exception_cloning.html">enable_exception_cloning<br/> </a><a href="enable_current_exception.html">enable_current_exception<br/>
</a><a href="cloning.html">Tutorial: Transporting of Exceptions between Threads<br/> </a><a href="cloning.html">Tutorial: Transporting of Exceptions between Threads<br/>
</a></div> </a></div>
<div id="footer"> <div id="footer">

2
doc/transporting_data.html
View File

@ -141,7 +141,7 @@ parse_file( char const * file_name )
#include &lt;boost/shared_ptr.hpp&gt; #include &lt;boost/shared_ptr.hpp&gt;
#include &lt;stdio.h&gt; #include &lt;stdio.h&gt;
#include &lt;string&gt; #include &lt;string&gt;
#include &lt;errno&gt; #include &lt;errno.h&gt;
typedef boost::<span class="RenoLink"><a href="error_info.html">error_info</a></span>&lt;struct tag_file_name,std::string&gt; file_name_info; typedef boost::<span class="RenoLink"><a href="error_info.html">error_info</a></span>&lt;struct tag_file_name,std::string&gt; file_name_info;
typedef boost::<span class="RenoLink"><a href="error_info.html">error_info</a></span>&lt;struct tag_function,char const *&gt; function_info; typedef boost::<span class="RenoLink"><a href="error_info.html">error_info</a></span>&lt;struct tag_function,char const *&gt; function_info;

9
doc/unknown_exception.html
View File

@ -17,7 +17,7 @@
<h1>Boost Exception</h1> <h1>Boost Exception</h1>
</div> </div>
<div class="RenoIncludeDIV"><h3>unknown_exception</h3> <div class="RenoIncludeDIV"><h3>unknown_exception</h3>
<div class="RenoIncludeDIV"><p><tt>#include &lt;<span class="RenoLink"><a href="exception_cloning_hpp.html">boost/exception/cloning.hpp</a></span>&gt;</tt></p> <div class="RenoIncludeDIV"><p><tt>#include &lt;<span class="RenoLink"><a href="exception_cloning_hpp.html">boost/exception_ptr.hpp</a></span>&gt;</tt></p>
<pre>namespace <pre>namespace
boost boost
{ {
@ -29,12 +29,11 @@ boost
---unspecified--- ---unspecified---
};</span> };</span>
}</pre> }</pre>
</div><p>This type is used by the <span class="RenoLink"><a href="cloning.html">cloning</a></span> support in Boost Exception.</p> </div><p>This type is used by the <span class="RenoLink"><a href="cloning.html">cloning</a></span> support in Boost Exception. Please see <tt><span class="RenoLink"><a href="current_exception.html">current_exception</a></span>()</tt>.</p>
<p>To allow an exception to be cloned, <tt><span class="RenoLink"><a href="enable_exception_cloning.html">enable_exception_cloning</a></span>()</tt> must be used at the time the exception object is passed to <tt>throw</tt>. Otherwise, calling <tt><span class="RenoLink"><a href="clone_exception.html">clone_exception</a></span>()</tt> returns an <tt><span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span></tt> which refers to an instance of <tt><span class="RenoLink"><a href="unknown_exception.html">unknown_exception</a></span></tt>.</p>
</div><h3>See also:</h3> </div><h3>See also:</h3>
<div class="RenoPageList"><a href="boost-exception.html">Boost Exception<br/> <div class="RenoPageList"><a href="boost-exception.html">Boost Exception<br/>
</a><a href="clone_exception.html">clone_exception<br/> </a><a href="current_exception.html">current_exception<br/>
</a><a href="enable_exception_cloning.html">enable_exception_cloning<br/> </a><a href="enable_current_exception.html">enable_current_exception<br/>
</a></div> </a></div>
<div id="footer"> <div id="footer">
<p>&nbsp;</p> <p>&nbsp;</p>

54
doc/using_enable_cloning.html Normal file
View File

@ -0,0 +1,54 @@
<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN'
'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>
<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'>
<head>
<meta http-equiv='Content-Type' content='text/html; charset=utf-8'/>
<title>Tutorial: Using enable_current_exception() at the Time of the Throw</title>
<link href='reno.css' type='text/css' rel='stylesheet'/>
</head>
<body>
<div class="body-0">
<div class="body-1">
<div class="body-2">
<div>
<div id="boost_logo">
<a href="http://www.boost.org"><img style="border:0" src="http://www.boost.org/boost.png" alt="Boost" width="277" height="86"/></a>
</div>
<h1>Boost Exception</h1>
</div>
<div class="RenoIncludeDIV"><h3>Using enable_current_exception() at the Time of the Throw</h3>
<p>Here is how cloning can be enabled in a throw-expression (15.1):</p>
<pre>#include &lt;<span class="RenoLink"><a href="exception_enable_exception_cloning_hpp.html">boost/exception/enable_current_exception.hpp</a></span>&gt;
#include &lt;<span class="RenoLink"><a href="exception_error_info_hpp.html">boost/exception/info.hpp</a></span>&gt;
#include &lt;stdio.h&gt;
#include &lt;errno.h&gt;
typedef boost::error_info&lt;struct tag_errno,int&gt; errno_info;
class file_read_error: public boost::<span class="RenoLink"><a href="exception.html">exception</a></span> { };
void
file_read( FILE * f, void * buffer, size_t size )
{
if( size!=fread(buffer,1,size,f) )
throw boost::<span class="RenoLink"><a href="enable_current_exception.html">enable_current_exception</a></span>(file_read_error()) &lt;&lt;
errno_info(errno);
}</pre>
</div><h3>See also:</h3>
<div class="RenoPageList"><a href="cloning.html">Tutorial: Transporting of Exceptions between Threads<br/>
</a></div>
<div id="footer">
<p>&nbsp;</p>
<hr/>
<p>
<a class="logo" href="http://jigsaw.w3.org/css-validator/validator?uri=http://revergestudios.com/boost-exception/reno.css"><img class="logo_pic" src="valid-css.png" alt="Valid CSS" height="31" width="88"/></a>
<a class="logo" href="http://validator.w3.org/check?uri=referer"><img class="logo_pic" src="valid-xhtml.png" alt="Valid XHTML 1.0" height="31" width="88"/></a>
<small>Copyright (c) 2006-2008 by Emil Dotchevski and Reverge Studios, Inc.<br/>
Distributed under the <a href="http://www.boost.org/LICENSE_1_0.txt">Boost Software License, Version 1.0</a>.</small>
</p>
</div>
</div>
</div>
</div>
</body>
</html>