forked from boostorg/exception
Documentation update
[SVN r52121]
This commit is contained in:
@ -36,6 +36,7 @@
|
|||||||
</div></div><p>This macro takes an exception object, records BOOST_CURRENT_FUNCTION, __FILE__ and __LINE__ in it, and forwards it to <span class="RenoLink"><a href="throw_exception.html">throw_exception</a></span>. To recover this information at the catch site, use <span class="RenoLink"><a href="get_error_info.html">get_error_info</a></span>; the information is also included in the message returned by <span class="RenoLink"><a href="diagnostic_information.html">diagnostic_information</a></span>.</p>
|
</div></div><p>This macro takes an exception object, records BOOST_CURRENT_FUNCTION, __FILE__ and __LINE__ in it, and forwards it to <span class="RenoLink"><a href="throw_exception.html">throw_exception</a></span>. To recover this information at the catch site, use <span class="RenoLink"><a href="get_error_info.html">get_error_info</a></span>; the information is also included in the message returned by <span class="RenoLink"><a href="diagnostic_information.html">diagnostic_information</a></span>.</p>
|
||||||
</div><div class="RenoPageList"><a href="boost-exception.html">Boost Exception<br/>
|
</div><div class="RenoPageList"><a href="boost-exception.html">Boost Exception<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><a href="frequently_asked_questions.html">Frequently Asked Questions<br/>
|
||||||
</a></div>
|
</a></div>
|
||||||
<!-- Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. -->
|
<!-- Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. -->
|
||||||
<!-- Distributed under the Boost Software License, Version 1.0. (See accompanying -->
|
<!-- Distributed under the Boost Software License, Version 1.0. (See accompanying -->
|
||||||
|
@ -68,6 +68,7 @@
|
|||||||
</li>
|
</li>
|
||||||
</ol></div>
|
</ol></div>
|
||||||
</li>
|
</li>
|
||||||
|
<li><span class="RenoLink"><a href="frequently_asked_questions.html">Frequently Asked Questions</a></span></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>
|
||||||
</ol></div>
|
</ol></div>
|
||||||
<h2>Synopsis</h2>
|
<h2>Synopsis</h2>
|
||||||
@ -205,12 +206,24 @@ boost
|
|||||||
<p>T must have accessible copy constructor and must not be a reference (there is no requirement that T's copy constructor does not throw.)</p>
|
<p>T must have accessible copy constructor and must not be a reference (there is no requirement that T's copy constructor does not throw.)</p>
|
||||||
<h4>Description:</h4>
|
<h4>Description:</h4>
|
||||||
<p>This class template is used to associate a Tag type with a value type T. Objects of type <span class="RenoLink"><a href="error_info.html">error_info</a></span><Tag,T> can be passed to <span class="RenoLink"><a href="exception_operator_shl.html">operator<<</a></span> to be stored in objects of type boost::<span class="RenoLink"><a href="exception.html">exception</a></span>.</p>
|
<p>This class template is used to associate a Tag type with a value type T. Objects of type <span class="RenoLink"><a href="error_info.html">error_info</a></span><Tag,T> can be passed to <span class="RenoLink"><a href="exception_operator_shl.html">operator<<</a></span> to be stored in objects of type boost::<span class="RenoLink"><a href="exception.html">exception</a></span>.</p>
|
||||||
<h4>Note:</h4>
|
<h4>Usage:</h4>
|
||||||
<p>The header <<span class="RenoLink"><a href="exception_error_info_value_hpp.html">boost/exception/error_info.hpp</a></span>> provides a declaration of the <span class="RenoLink"><a href="error_info.html">error_info</a></span> template, which is sufficient for the purpose of typedefing an instance for specific Tag and T, like this:</p>
|
<p>The header <<span class="RenoLink"><a href="exception_error_info_value_hpp.html">boost/exception/error_info.hpp</a></span>> provides a declaration of the <span class="RenoLink"><a href="error_info.html">error_info</a></span> template, which is sufficient for the purpose of typedefing an instance for specific Tag and T, for example:</p>
|
||||||
|
<pre>#include <<span class="RenoLink"><a href="exception_error_info_value_hpp.html">boost/exception/error_info.hpp</a></span>>
|
||||||
|
|
||||||
|
struct tag_errno;
|
||||||
|
typedef boost::<span class="RenoLink"><a href="error_info.html">error_info</a></span><tag_errno,int> errno_info;</pre>
|
||||||
|
<p>Or, the shorter equivalent:</p>
|
||||||
<pre>#include <<span class="RenoLink"><a href="exception_error_info_value_hpp.html">boost/exception/error_info.hpp</a></span>>
|
<pre>#include <<span class="RenoLink"><a href="exception_error_info_value_hpp.html">boost/exception/error_info.hpp</a></span>>
|
||||||
|
|
||||||
typedef boost::<span class="RenoLink"><a href="error_info.html">error_info</a></span><struct tag_errno,int> errno_info;</pre>
|
typedef boost::<span class="RenoLink"><a href="error_info.html">error_info</a></span><struct tag_errno,int> errno_info;</pre>
|
||||||
<p>Of course, to actually add an <span class="RenoLink"><a href="error_info.html">error_info</a></span> object to <span class="RenoLink"><a href="exception.html">exceptions</a></span> using <span class="RenoLink"><a href="exception_operator_shl.html">operator<<</a></span>, or to retrieve it using <span class="RenoLink"><a href="get_error_info.html">get_error_info</a></span>, you must first #include <<span class="RenoLink"><a href="exception_error_info_hpp.html">boost/exception/info.hpp</a></span>>.</p>
|
<p>This errno_info typedef can be passed to <span class="RenoLink"><a href="exception_operator_shl.html">operator<<</a></span> (#include <<span class="RenoLink"><a href="exception_error_info_hpp.html">boost/exception/info.hpp</a></span>> first) to store an int named tag_errno in exceptions of types that derive from boost::<span class="RenoLink"><a href="exception.html">exception</a></span>:</p>
|
||||||
|
<pre>throw file_read_error() <span class="RenoLink"><a href="exception_operator_shl.html"><<</a></span> errno_info(errno);</pre>
|
||||||
|
<p>It can also be passed to <span class="RenoLink"><a href="get_error_info.html">get_error_info</a></span> (#include <<span class="RenoLink"><a href="exception_get_error_info_hpp.html">boost/exception/get_error_info.hpp</a></span>> first) to retrieve the tag_errno int from a boost::<span class="RenoLink"><a href="exception.html">exception</a></span>:</p>
|
||||||
|
<pre>catch( boost::<span class="RenoLink"><a href="exception.html">exception</a></span> & x )
|
||||||
|
{
|
||||||
|
if( boost::shared_ptr<int const> e=boost::<span class="RenoLink"><a href="get_error_info.html">get_error_info</a></span><errno_info>(x) )
|
||||||
|
....
|
||||||
|
}</pre>
|
||||||
</div><div class="RenoIncludeDIV"><div class="RenoAutoDIV"><h3>exception/operator<<</h3>
|
</div><div class="RenoIncludeDIV"><div class="RenoAutoDIV"><h3>exception/operator<<</h3>
|
||||||
</div>
|
</div>
|
||||||
<div class="RenoIncludeDIV"><p><span class="RenoEscape">#<!--<wiki>`#</wiki>--></span>include <<span class="RenoLink"><a href="exception_error_info_hpp.html">boost/exception/info.hpp</a></span>><span class="RenoBR"> </span><br/></p>
|
<div class="RenoIncludeDIV"><p><span class="RenoEscape">#<!--<wiki>`#</wiki>--></span>include <<span class="RenoLink"><a href="exception_error_info_hpp.html">boost/exception/info.hpp</a></span>><span class="RenoBR"> </span><br/></p>
|
||||||
|
@ -56,6 +56,8 @@ std::exception::what: example_io error
|
|||||||
</a><a href="boost-exception.html">Boost Exception<br/>
|
</a><a href="boost-exception.html">Boost Exception<br/>
|
||||||
</a><a href="exception_diagnostic_information_hpp.html">boost/exception/diagnostic_information.hpp<br/>
|
</a><a href="exception_diagnostic_information_hpp.html">boost/exception/diagnostic_information.hpp<br/>
|
||||||
</a><a href="tutorial_diagnostic_information.html">Diagnostic Information<br/>
|
</a><a href="tutorial_diagnostic_information.html">Diagnostic Information<br/>
|
||||||
|
</a><a href="frequently_asked_questions.html">Frequently Asked Questions<br/>
|
||||||
|
</a><a href="motivation.html">Motivation<br/>
|
||||||
</a></div>
|
</a></div>
|
||||||
</div>
|
</div>
|
||||||
<!-- Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. -->
|
<!-- Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. -->
|
||||||
|
@ -52,6 +52,7 @@ throw boost::<span class="RenoLink"><a href="enable_current_exception.html">enab
|
|||||||
</a><a href="configuration_macros.html">Configuration Macros<br/>
|
</a><a href="configuration_macros.html">Configuration Macros<br/>
|
||||||
</a><a href="copy_exception.html">copy_exception<br/>
|
</a><a href="copy_exception.html">copy_exception<br/>
|
||||||
</a><a href="current_exception.html">current_exception<br/>
|
</a><a href="current_exception.html">current_exception<br/>
|
||||||
|
</a><a href="frequently_asked_questions.html">Frequently Asked Questions<br/>
|
||||||
</a><a href="tutorial_exception_ptr.html">Transporting of Exceptions Between Threads<br/>
|
</a><a href="tutorial_exception_ptr.html">Transporting of Exceptions Between Threads<br/>
|
||||||
</a><a href="throw_exception.html">throw_exception<br/>
|
</a><a href="throw_exception.html">throw_exception<br/>
|
||||||
</a></div>
|
</a></div>
|
||||||
|
@ -41,12 +41,24 @@ boost
|
|||||||
<p>T must have accessible copy constructor and must not be a reference (there is no requirement that T's copy constructor does not throw.)</p>
|
<p>T must have accessible copy constructor and must not be a reference (there is no requirement that T's copy constructor does not throw.)</p>
|
||||||
<h4>Description:</h4>
|
<h4>Description:</h4>
|
||||||
<p>This class template is used to associate a Tag type with a value type T. Objects of type <span class="RenoLink"><a href="error_info.html">error_info</a></span><Tag,T> can be passed to <span class="RenoLink"><a href="exception_operator_shl.html">operator<<</a></span> to be stored in objects of type boost::<span class="RenoLink"><a href="exception.html">exception</a></span>.</p>
|
<p>This class template is used to associate a Tag type with a value type T. Objects of type <span class="RenoLink"><a href="error_info.html">error_info</a></span><Tag,T> can be passed to <span class="RenoLink"><a href="exception_operator_shl.html">operator<<</a></span> to be stored in objects of type boost::<span class="RenoLink"><a href="exception.html">exception</a></span>.</p>
|
||||||
<h4>Note:</h4>
|
<h4>Usage:</h4>
|
||||||
<p>The header <<span class="RenoLink"><a href="exception_error_info_value_hpp.html">boost/exception/error_info.hpp</a></span>> provides a declaration of the <span class="RenoLink"><a href="error_info.html">error_info</a></span> template, which is sufficient for the purpose of typedefing an instance for specific Tag and T, like this:</p>
|
<p>The header <<span class="RenoLink"><a href="exception_error_info_value_hpp.html">boost/exception/error_info.hpp</a></span>> provides a declaration of the <span class="RenoLink"><a href="error_info.html">error_info</a></span> template, which is sufficient for the purpose of typedefing an instance for specific Tag and T, for example:</p>
|
||||||
|
<pre>#include <<span class="RenoLink"><a href="exception_error_info_value_hpp.html">boost/exception/error_info.hpp</a></span>>
|
||||||
|
|
||||||
|
struct tag_errno;
|
||||||
|
typedef boost::<span class="RenoLink"><a href="error_info.html">error_info</a></span><tag_errno,int> errno_info;</pre>
|
||||||
|
<p>Or, the shorter equivalent:</p>
|
||||||
<pre>#include <<span class="RenoLink"><a href="exception_error_info_value_hpp.html">boost/exception/error_info.hpp</a></span>>
|
<pre>#include <<span class="RenoLink"><a href="exception_error_info_value_hpp.html">boost/exception/error_info.hpp</a></span>>
|
||||||
|
|
||||||
typedef boost::<span class="RenoLink"><a href="error_info.html">error_info</a></span><struct tag_errno,int> errno_info;</pre>
|
typedef boost::<span class="RenoLink"><a href="error_info.html">error_info</a></span><struct tag_errno,int> errno_info;</pre>
|
||||||
<p>Of course, to actually add an <span class="RenoLink"><a href="error_info.html">error_info</a></span> object to <span class="RenoLink"><a href="exception.html">exceptions</a></span> using <span class="RenoLink"><a href="exception_operator_shl.html">operator<<</a></span>, or to retrieve it using <span class="RenoLink"><a href="get_error_info.html">get_error_info</a></span>, you must first #include <<span class="RenoLink"><a href="exception_error_info_hpp.html">boost/exception/info.hpp</a></span>>.</p>
|
<p>This errno_info typedef can be passed to <span class="RenoLink"><a href="exception_operator_shl.html">operator<<</a></span> (#include <<span class="RenoLink"><a href="exception_error_info_hpp.html">boost/exception/info.hpp</a></span>> first) to store an int named tag_errno in exceptions of types that derive from boost::<span class="RenoLink"><a href="exception.html">exception</a></span>:</p>
|
||||||
|
<pre>throw file_read_error() <span class="RenoLink"><a href="exception_operator_shl.html"><<</a></span> errno_info(errno);</pre>
|
||||||
|
<p>It can also be passed to <span class="RenoLink"><a href="get_error_info.html">get_error_info</a></span> (#include <<span class="RenoLink"><a href="exception_get_error_info_hpp.html">boost/exception/get_error_info.hpp</a></span>> first) to retrieve the tag_errno int from a boost::<span class="RenoLink"><a href="exception.html">exception</a></span>:</p>
|
||||||
|
<pre>catch( boost::<span class="RenoLink"><a href="exception.html">exception</a></span> & x )
|
||||||
|
{
|
||||||
|
if( boost::shared_ptr<int const> e=boost::<span class="RenoLink"><a href="get_error_info.html">get_error_info</a></span><errno_info>(x) )
|
||||||
|
....
|
||||||
|
}</pre>
|
||||||
</div><div class="RenoAutoDIV"><div class="RenoHR"><hr/></div>
|
</div><div class="RenoAutoDIV"><div class="RenoHR"><hr/></div>
|
||||||
<h3>See Also:</h3>
|
<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/>
|
||||||
@ -59,6 +71,7 @@ typedef boost::<span class="RenoLink"><a href="error_info.html">error_info</a></
|
|||||||
</a><a href="error_info_value_type.html">error_info::value_type<br/>
|
</a><a href="error_info_value_type.html">error_info::value_type<br/>
|
||||||
</a><a href="exception.html">exception<br/>
|
</a><a href="exception.html">exception<br/>
|
||||||
</a><a href="exception_operator_shl.html">exception/operator<<<br/>
|
</a><a href="exception_operator_shl.html">exception/operator<<<br/>
|
||||||
|
</a><a href="frequently_asked_questions.html">Frequently Asked Questions<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="tutorial_enable_error_info.html">Integrating Boost Exception in Existing Exception Class Hierarchies<br/>
|
</a><a href="tutorial_enable_error_info.html">Integrating Boost Exception in Existing Exception Class Hierarchies<br/>
|
||||||
</a><a href="motivation.html">Motivation<br/>
|
</a><a href="motivation.html">Motivation<br/>
|
||||||
|
@ -54,6 +54,7 @@ boost
|
|||||||
</a><a href="exception_operator_shl.html">exception/operator<<<br/>
|
</a><a href="exception_operator_shl.html">exception/operator<<<br/>
|
||||||
</a><a href="exception_constructors.html">exception::exception<br/>
|
</a><a href="exception_constructors.html">exception::exception<br/>
|
||||||
</a><a href="exception_destructor.html">exception::~exception<br/>
|
</a><a href="exception_destructor.html">exception::~exception<br/>
|
||||||
|
</a><a href="frequently_asked_questions.html">Frequently Asked Questions<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="tutorial_enable_error_info.html">Integrating Boost Exception in Existing Exception Class Hierarchies<br/>
|
</a><a href="tutorial_enable_error_info.html">Integrating Boost Exception in Existing Exception Class Hierarchies<br/>
|
||||||
</a><a href="motivation.html">Motivation<br/>
|
</a><a href="motivation.html">Motivation<br/>
|
||||||
|
@ -34,6 +34,7 @@ boost
|
|||||||
<h3>See Also:</h3>
|
<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="exception_hpp.html">boost/exception.hpp<br/>
|
</a><a href="exception_hpp.html">boost/exception.hpp<br/>
|
||||||
|
</a><a href="error_info.html">error_info<br/>
|
||||||
</a><a href="get_error_info.html">get_error_info<br/>
|
</a><a href="get_error_info.html">get_error_info<br/>
|
||||||
</a></div>
|
</a></div>
|
||||||
</div>
|
</div>
|
||||||
|
@ -45,6 +45,7 @@ boost
|
|||||||
</a><a href="error_info.html">error_info<br/>
|
</a><a href="error_info.html">error_info<br/>
|
||||||
</a><a href="exception.html">exception<br/>
|
</a><a href="exception.html">exception<br/>
|
||||||
</a><a href="exception_constructors.html">exception::exception<br/>
|
</a><a href="exception_constructors.html">exception::exception<br/>
|
||||||
|
</a><a href="frequently_asked_questions.html">Frequently Asked Questions<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="tutorial_enable_error_info.html">Integrating Boost Exception in Existing Exception Class Hierarchies<br/>
|
</a><a href="tutorial_enable_error_info.html">Integrating Boost Exception in Existing Exception Class Hierarchies<br/>
|
||||||
</a><a href="motivation.html">Motivation<br/>
|
</a><a href="motivation.html">Motivation<br/>
|
||||||
|
@ -42,6 +42,7 @@ boost
|
|||||||
</a><a href="copy_exception.html">copy_exception<br/>
|
</a><a href="copy_exception.html">copy_exception<br/>
|
||||||
</a><a href="current_exception.html">current_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_current_exception.html">enable_current_exception<br/>
|
||||||
|
</a><a href="frequently_asked_questions.html">Frequently Asked Questions<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/>
|
||||||
</a></div>
|
</a></div>
|
||||||
|
101
doc/frequently_asked_questions.html
Normal file
101
doc/frequently_asked_questions.html
Normal file
@ -0,0 +1,101 @@
|
|||||||
|
<!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>frequently asked questions</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>
|
||||||
|
<!-- Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. -->
|
||||||
|
<!-- Distributed under the Boost Software License, Version 1.0. (See accompanying -->
|
||||||
|
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
|
||||||
|
<div class="RenoIncludeDIV"><div class="RenoAutoDIV"><h3>Frequently Asked Questions</h3>
|
||||||
|
</div>
|
||||||
|
<h3>Why use operator<< overload for adding info to exceptions?</h3>
|
||||||
|
<p>Before throwing an object of type that derives from boost::<span class="RenoLink"><a href="exception.html">exception</a></span>, it is often desirable to add one or more <span class="RenoLink"><a href="error_info.html">error_info</a></span> objects in it. The syntactic sugar provided by <span class="RenoLink"><a href="exception_operator_shl.html">exception/operator<<</a></span> allows this to be done directly in a throw expression:</p>
|
||||||
|
<pre>throw error() <span class="RenoLink"><a href="exception_operator_shl.html"><<</a></span> foo_info(foo) <span class="RenoLink"><a href="exception_operator_shl.html"><<</a></span> bar_info(bar);</pre>
|
||||||
|
<p>which saves typing compared to this possible alternative:</p>
|
||||||
|
<pre>error e;
|
||||||
|
e.add(foo_info(foo));
|
||||||
|
e.add(bar_info(bar));
|
||||||
|
throw e;</pre>
|
||||||
|
<p>and looks better than something like:</p>
|
||||||
|
<pre>throw error().add(foo_info(foo)).add(bar_info(bar));</pre>
|
||||||
|
<h3>Why is boost::exception abstract?</h3>
|
||||||
|
<p>To prevent exception-neutral contexts from erroneusly erasing the type of the original exception when adding <span class="RenoLink"><a href="error_info.html">error_info</a></span> to an active exception object:</p>
|
||||||
|
<pre>catch( boost::<span class="RenoLink"><a href="exception.html">exception</a></span> & e )
|
||||||
|
{
|
||||||
|
e <span class="RenoLink"><a href="exception_operator_shl.html"><<</a></span> foo_info(foo);
|
||||||
|
throw e; //Compile error: boost::<span class="RenoLink"><a href="exception.html">exception</a></span> is abstract
|
||||||
|
}</pre>
|
||||||
|
<p>The correct code is:</p>
|
||||||
|
<pre>catch( boost::<span class="RenoLink"><a href="exception.html">exception</a></span> & e )
|
||||||
|
{
|
||||||
|
e <span class="RenoLink"><a href="exception_operator_shl.html"><<</a></span> foo_info(foo);
|
||||||
|
throw; //Okay, re-throwing the original exception object.
|
||||||
|
}</pre>
|
||||||
|
<h3>What is the space overhead of the boost::exception base class?</h3>
|
||||||
|
<p>The space overhead for the boost::exception data members is negligible in the context of exception handling. Throwing objects that derive from boost::<span class="RenoLink"><a href="exception.html">exception</a></span> does not by itself cause dynamic memory allocations.</p>
|
||||||
|
<p>Deriving from boost::<span class="RenoLink"><a href="exception.html">exception</a></span> enables any data to be added to exceptions, which usually does allocate memory. However, this memory is reclaimed when the exception has been handled, and since typically user code does not allocate memory during the unrolling of the stack, adding error info to exceptions should not cause memory fragmentation.</p>
|
||||||
|
<h3>Why is boost::exception integrated in boost::throw_exception?</h3>
|
||||||
|
<p>The boost::<span class="RenoLink"><a href="throw_exception.html">throw_exception</a></span> function predates the Boost Exception library and there has been some concern about its current behavior of injecting boost::<span class="RenoLink"><a href="exception.html">exception</a></span> as a base of any exception passed to boost::<span class="RenoLink"><a href="throw_exception.html">throw_exception</a></span>. Such concerns are dictated by the typical strict interpretation of a common principle in C and C++, that users only pay for features they actually use.</p>
|
||||||
|
<p>The problem is that users of Boost Exception can't by themselves cause a library to throw types that derive from boost::<span class="RenoLink"><a href="exception.html">exception</a></span>, and without this they can't use any of the Boost Exception facilities.</p>
|
||||||
|
<p>For example, if a user wants to use Boost Serialization in a separate thread, it is desirable to be able to transport exceptions emitted by that library into the main thread where they can be analyzed to generate a user-friendly message. This can be easily achieved using boost::<span class="RenoLink"><a href="exception_ptr.html">exception_ptr</a></span>, but this requires that Boost Serialization throws exceptions using boost::<span class="RenoLink"><a href="enable_current_exception.html">enable_current_exception</a></span>. If Boost Serialization calls boost::<span class="RenoLink"><a href="throw_exception.html">throw_exception</a></span> to throw, this behavior happens automatically and transparently.</p>
|
||||||
|
<p>The cost of this integration is:</p>
|
||||||
|
<div><ul><li> In terms of space: a pointer and 3 ints are added to the static size of exception objects.</li>
|
||||||
|
<li> In terms of speed: the pointer is initialized to null at the point of the throw.</li>
|
||||||
|
<li> In terms of coupling: about 400 self-contained lines of C++ with no external includes.</li>
|
||||||
|
</ul></div>
|
||||||
|
<h3>Should I call boost::throw_exception or BOOST_THROW_EXCEPTION?</h3>
|
||||||
|
<p>It is preferable to throw exceptions using the <span class="RenoLink"><a href="BOOST_THROW_EXCEPTION.html">BOOST_THROW_EXCEPTION</a></span> macro. This has the benefit of recording in the exception object the __FILE__ and __LINE__ of the throw, as well as the pretty name of the function that throws. This has virtually no overhead, yet enables boost::<span class="RenoLink"><a href="diagnostic_information.html">diagnostic_information</a></span> to compose a more useful, if not user-friendly message.</p>
|
||||||
|
<p>Typical use of boost::<span class="RenoLink"><a href="diagnostic_information.html">diagnostic_information</a></span> is:</p>
|
||||||
|
<pre>catch( boost::exception & e )
|
||||||
|
{
|
||||||
|
std::cerr << "OMG!" << boost::diagnostic_information(e);
|
||||||
|
}
|
||||||
|
catch( ... )
|
||||||
|
{
|
||||||
|
std::cerr << "OMG!!!";
|
||||||
|
}</pre>
|
||||||
|
<p>This is a possible message it may display, the first line is only possible if <span class="RenoLink"><a href="BOOST_THROW_EXCEPTION.html">BOOST_THROW_EXCEPTION</a></span> is used:</p>
|
||||||
|
<pre>example_io.cpp(83): Throw in function void parse_file(const char *)
|
||||||
|
Dynamic exception type: class file_open_error
|
||||||
|
std::exception::what: example_io error
|
||||||
|
[struct tag_errno_code *] = 2, OS says "No such file or directory"
|
||||||
|
[struct tag_file_name *] = tmp1.xml
|
||||||
|
[struct tag_function *] = fopen
|
||||||
|
[struct tag_open_mode *] = rb</pre>
|
||||||
|
</div><div class="RenoAutoDIV"><div class="RenoHR"><hr/></div>
|
||||||
|
<h3>See Also:</h3>
|
||||||
|
<div class="RenoPageList"><a href="boost-exception.html">Boost Exception<br/>
|
||||||
|
</a><a href="motivation.html">Motivation<br/>
|
||||||
|
</a></div>
|
||||||
|
</div>
|
||||||
|
<!-- Copyright (c) 2006-2008 Emil Dotchevski and Reverge Studios, Inc. -->
|
||||||
|
<!-- Distributed under the Boost Software License, Version 1.0. (See accompanying -->
|
||||||
|
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
|
||||||
|
<div id="footer">
|
||||||
|
<p> </p>
|
||||||
|
<hr/>
|
||||||
|
<p>
|
||||||
|
<a class="logo" href="http://jigsaw.w3.org/css-validator/check/referer"><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>
|
@ -119,10 +119,12 @@ catch( boost::<span class="RenoLink"><a href="exception.html">exception</a></spa
|
|||||||
if( shared_ptr<int const> c=<span class="RenoLink"><a href="get_error_info.html">get_error_info</a></span><errno_code>(e) )
|
if( shared_ptr<int const> c=<span class="RenoLink"><a href="get_error_info.html">get_error_info</a></span><errno_code>(e) )
|
||||||
std::cerr << “OS says: “ << strerror(*c) << “\n”;
|
std::cerr << “OS says: “ << strerror(*c) << “\n”;
|
||||||
}</pre>
|
}</pre>
|
||||||
|
<p>In addition, boost::<span class="RenoLink"><a href="diagnostic_information.html">diagnostic_information</a></span> can be used to compose an automatic (if not user-friendly) message that contains all of the <span class="RenoLink"><a href="error_info.html">error_info</a></span> objects added to a boost::<span class="RenoLink"><a href="exception.html">exception</a></span>. This is useful for inclusion in logs and other diagnostic objects.</p>
|
||||||
</div><div class="RenoAutoDIV"><div class="RenoHR"><hr/></div>
|
</div><div class="RenoAutoDIV"><div class="RenoHR"><hr/></div>
|
||||||
<h3>See Also:</h3>
|
<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="exception_types_as_simple_semantic_tags.html">Exception Types As Simple Semantic Tags<br/>
|
</a><a href="exception_types_as_simple_semantic_tags.html">Exception Types As Simple Semantic Tags<br/>
|
||||||
|
</a><a href="frequently_asked_questions.html">Frequently Asked Questions<br/>
|
||||||
</a><a href="tutorial_enable_error_info.html">Integrating Boost Exception in Existing Exception Class Hierarchies<br/>
|
</a><a href="tutorial_enable_error_info.html">Integrating Boost Exception in Existing Exception Class Hierarchies<br/>
|
||||||
</a></div>
|
</a></div>
|
||||||
</div>
|
</div>
|
||||||
|
@ -58,6 +58,8 @@
|
|||||||
<p><a href="exception_constructors.html">exception::exception</a></p>
|
<p><a href="exception_constructors.html">exception::exception</a></p>
|
||||||
<p><a href="exception_destructor.html">exception::~exception</a></p>
|
<p><a href="exception_destructor.html">exception::~exception</a></p>
|
||||||
<p><a href="exception_ptr.html">exception_ptr</a></p>
|
<p><a href="exception_ptr.html">exception_ptr</a></p>
|
||||||
|
<h3>F</h3>
|
||||||
|
<p><a href="frequently_asked_questions.html">Frequently Asked Questions</a></p>
|
||||||
<h3>g</h3>
|
<h3>g</h3>
|
||||||
<p><a href="get_error_info.html">get_error_info</a></p>
|
<p><a href="get_error_info.html">get_error_info</a></p>
|
||||||
<h3>I</h3>
|
<h3>I</h3>
|
||||||
|
File diff suppressed because it is too large
Load Diff
@ -45,6 +45,7 @@ boost
|
|||||||
</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><a href="configuration_macros.html">Configuration Macros<br/>
|
</a><a href="configuration_macros.html">Configuration Macros<br/>
|
||||||
</a><a href="enable_current_exception.html">enable_current_exception<br/>
|
</a><a href="enable_current_exception.html">enable_current_exception<br/>
|
||||||
|
</a><a href="frequently_asked_questions.html">Frequently Asked Questions<br/>
|
||||||
</a><a href="tutorial_exception_ptr.html">Transporting of Exceptions Between Threads<br/>
|
</a><a href="tutorial_exception_ptr.html">Transporting of Exceptions Between Threads<br/>
|
||||||
</a></div>
|
</a></div>
|
||||||
</div>
|
</div>
|
||||||
|
Reference in New Issue
Block a user