feedc0de/boost_exception
1
0
Fork 0
forked from boostorg/exception
Code Pull Requests 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

24
doc/cloning.html
View File

@ -17,12 +17,12 @@
<h1>Boost Exception</h1>
</div>
<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>
<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>
<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;stdio.h&gt;
#include &lt;errno.h&gt;
@ -35,12 +35,12 @@ 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_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);
}</pre>
</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>
<pre>#include &lt;<span class="RenoLink"><a href="exception_cloning_hpp.html">boost/exception/cloning.hpp</a></span>&gt;
<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;
@ -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>();
}
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>
<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
void
@ -72,11 +72,11 @@ work()
if( error )
boost::<span class="RenoLink"><a href="rethrow_exception.html">rethrow_exception</a></span>(error);
}</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>
<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>
<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 class="RenoPageList"><a href="boost-exception.html">Boost Exception<br/>
</a><a href="unknown_exception.html">unknown_exception<br/>