generic-library/boost
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
boost/doc/html/container/exception_handling.html

142 lines
10 KiB
HTML
Raw Permalink Normal View History

[DEV] add v1.76.0
2021-10-05 21:37:46 +02:00
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Boost.Container and C++ exceptions</title>
<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
<link rel="up" href="../container.html" title="Chapter 9. Boost.Container">
<link rel="prev" href="main_features.html" title="Main features">
<link rel="next" href="non_standard_containers.html" title="Non-standard containers">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
<td align="center"><a href="../../../index.html">Home</a></td>
<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="main_features.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../container.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="non_standard_containers.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="container.exception_handling"></a><a class="link" href="exception_handling.html" title="Boost.Container and C++ exceptions">Boost.Container and C++ exceptions</a>
</h2></div></div></div>
<p>
In some environments, such as game development or embedded systems, C++ exceptions
are disabled or a customized error handling is needed. According to document
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2271.html" target="_top">N2271
EASTL -- Electronic Arts Standard Template Library</a> exceptions can be
disabled for several reasons:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<span class="quote">“<span class="quote"><span class="emphasis"><em>Exception handling incurs some kind of cost in all compiler
implementations, including those that avoid the cost during normal execution.
However, in some cases this cost may arguably offset the cost of the code
that it is replacing.</em></span></span>”</span>
</li>
<li class="listitem">
<span class="quote">“<span class="quote"><span class="emphasis"><em>Exception handling is often agreed to be a superior solution
for handling a large range of function return values. However, avoiding
the creation of functions that need large ranges of return values is superior
to using exception handling to handle such values.</em></span></span>”</span>
</li>
<li class="listitem">
<span class="quote">“<span class="quote"><span class="emphasis"><em>Using exception handling correctly can be difficult in
the case of complex software.</em></span></span>”</span>
</li>
<li class="listitem">
<span class="quote">“<span class="quote"><span class="emphasis"><em>The execution of throw and catch can be significantly
expensive with some implementations.</em></span></span>”</span>
</li>
<li class="listitem">
<span class="quote">“<span class="quote"><span class="emphasis"><em>Exception handling violates the don't-pay-for-what-you-don't-use
design of C++, as it incurs overhead in any non-leaf function that has
destructible stack objects regardless of whether they use exception handling.</em></span></span>”</span>
</li>
<li class="listitem">
<span class="quote">“<span class="quote"><span class="emphasis"><em>The approach that game software usually takes is to avoid
the need for exception handling where possible; avoid the possibility of
circumstances that may lead to exceptions. For example, verify up front
that there is enough memory for a subsystem to do its job instead of trying
to deal with the problem via exception handling or any other means after
it occurs.</em></span></span>”</span>
</li>
<li class="listitem">
<span class="quote">“<span class="quote"><span class="emphasis"><em>However, some game libraries may nevertheless benefit
from the use of exception handling. It's best, however, if such libraries
keep the exception handling internal lest they force their usage of exception
handling on the rest of the application.</em></span></span>”</span>
</li>
</ul></div>
<p>
In order to support environments without C++ exception support or environments
with special error handling needs, <span class="bold"><strong>Boost.Container</strong></span>
changes error signalling behaviour when <code class="computeroutput"><span class="identifier">BOOST_CONTAINER_USER_DEFINED_THROW_CALLBACKS</span></code>
or <code class="computeroutput"><span class="identifier">BOOST_NO_EXCEPTIONS</span></code> is defined.
The former shall be defined by the user and the latter can be either defined
by the user or implicitly defined by <span class="bold"><strong>Boost.Confg</strong></span>
when the compiler has been invoked with the appropriate flag (like <code class="computeroutput"><span class="special">-</span><span class="identifier">fno</span><span class="special">-</span><span class="identifier">exceptions</span></code> in GCC).
</p>
<p>
When dealing with user-defined classes, (e.g. when constructing user-defined
classes):
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
If <code class="computeroutput"><span class="identifier">BOOST_NO_EXCEPTIONS</span></code>
is defined, the library avoids using <code class="computeroutput"><span class="keyword">try</span></code>/<code class="computeroutput"><span class="keyword">catch</span></code>/<code class="computeroutput"><span class="keyword">throw</span></code>
statements. The class writer must handle and propagate error situations
internally as no error will be propagated through <span class="bold"><strong>Boost.Container</strong></span>.
</li>
<li class="listitem">
If <code class="computeroutput"><span class="identifier">BOOST_NO_EXCEPTIONS</span></code>
is <span class="bold"><strong>not</strong></span> defined, the library propagates
exceptions offering the exception guarantees detailed in the documentation.
</li>
</ul></div>
<p>
When the library needs to throw an exception (such as <code class="computeroutput"><span class="identifier">out_of_range</span></code>
when an incorrect index is used in <code class="computeroutput"><span class="identifier">vector</span><span class="special">::</span><span class="identifier">at</span></code>), the
library calls a throw-callback declared in <code class="computeroutput"><a class="link" href="../boost_container_header_reference.html#header.boost.container.throw_exception_hpp" title="Header &lt;boost/container/throw_exception.hpp&gt;">boost/container/throw_exception.hpp</a></code>:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
If <code class="computeroutput"><span class="identifier">BOOST_CONTAINER_USER_DEFINED_THROW_CALLBACKS</span></code>
is defined, then the programmer must provide its own definition for all
<code class="computeroutput"><span class="identifier">throw_xxx</span></code> functions. Those
functions can't return, they must throw an exception or call <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">exit</span></code> or <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">abort</span></code>.
</li>
<li class="listitem">
Else if <code class="computeroutput"><span class="identifier">BOOST_NO_EXCEPTIONS</span></code>
is defined, a <code class="computeroutput"><span class="identifier">BOOST_ASSERT_MSG</span></code>
assertion is triggered (see <a href="http://www.boost.org/libs/utility/assert.html" target="_top">Boost.Assert</a>
for more information). If this assertion returns, then <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">abort</span></code>
is called.
</li>
<li class="listitem">
Else, an appropriate standard library exception is thrown (like <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">out_of_range</span></code>).
</li>
</ul></div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2009-2018 Ion Gaztanaga<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="main_features.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../container.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="non_standard_containers.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
Reference in New Issue Copy Permalink