1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<head> 4<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 5<title>Boost.Container and C++ exceptions</title> 6<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> 7<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 8<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> 9<link rel="up" href="../container.html" title="Chapter 9. Boost.Container"> 10<link rel="prev" href="main_features.html" title="Main features"> 11<link rel="next" href="non_standard_containers.html" title="Non-standard containers"> 12</head> 13<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 14<table cellpadding="2" width="100%"><tr> 15<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td> 16<td align="center"><a href="../../../index.html">Home</a></td> 17<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> 18<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 19<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 20<td align="center"><a href="../../../more/index.htm">More</a></td> 21</tr></table> 22<hr> 23<div class="spirit-nav"> 24<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> 25</div> 26<div class="section"> 27<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 28<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> 29</h2></div></div></div> 30<p> 31 In some environments, such as game development or embedded systems, C++ exceptions 32 are disabled or a customized error handling is needed. According to document 33 <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2271.html" target="_top">N2271 34 EASTL -- Electronic Arts Standard Template Library</a> exceptions can be 35 disabled for several reasons: 36 </p> 37<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 38<li class="listitem"> 39 <span class="quote">“<span class="quote"><span class="emphasis"><em>Exception handling incurs some kind of cost in all compiler 40 implementations, including those that avoid the cost during normal execution. 41 However, in some cases this cost may arguably offset the cost of the code 42 that it is replacing.</em></span></span>”</span> 43 </li> 44<li class="listitem"> 45 <span class="quote">“<span class="quote"><span class="emphasis"><em>Exception handling is often agreed to be a superior solution 46 for handling a large range of function return values. However, avoiding 47 the creation of functions that need large ranges of return values is superior 48 to using exception handling to handle such values.</em></span></span>”</span> 49 </li> 50<li class="listitem"> 51 <span class="quote">“<span class="quote"><span class="emphasis"><em>Using exception handling correctly can be difficult in 52 the case of complex software.</em></span></span>”</span> 53 </li> 54<li class="listitem"> 55 <span class="quote">“<span class="quote"><span class="emphasis"><em>The execution of throw and catch can be significantly 56 expensive with some implementations.</em></span></span>”</span> 57 </li> 58<li class="listitem"> 59 <span class="quote">“<span class="quote"><span class="emphasis"><em>Exception handling violates the don't-pay-for-what-you-don't-use 60 design of C++, as it incurs overhead in any non-leaf function that has 61 destructible stack objects regardless of whether they use exception handling.</em></span></span>”</span> 62 </li> 63<li class="listitem"> 64 <span class="quote">“<span class="quote"><span class="emphasis"><em>The approach that game software usually takes is to avoid 65 the need for exception handling where possible; avoid the possibility of 66 circumstances that may lead to exceptions. For example, verify up front 67 that there is enough memory for a subsystem to do its job instead of trying 68 to deal with the problem via exception handling or any other means after 69 it occurs.</em></span></span>”</span> 70 </li> 71<li class="listitem"> 72 <span class="quote">“<span class="quote"><span class="emphasis"><em>However, some game libraries may nevertheless benefit 73 from the use of exception handling. It's best, however, if such libraries 74 keep the exception handling internal lest they force their usage of exception 75 handling on the rest of the application.</em></span></span>”</span> 76 </li> 77</ul></div> 78<p> 79 In order to support environments without C++ exception support or environments 80 with special error handling needs, <span class="bold"><strong>Boost.Container</strong></span> 81 changes error signalling behaviour when <code class="computeroutput"><span class="identifier">BOOST_CONTAINER_USER_DEFINED_THROW_CALLBACKS</span></code> 82 or <code class="computeroutput"><span class="identifier">BOOST_NO_EXCEPTIONS</span></code> is defined. 83 The former shall be defined by the user and the latter can be either defined 84 by the user or implicitly defined by <span class="bold"><strong>Boost.Confg</strong></span> 85 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). 86 </p> 87<p> 88 When dealing with user-defined classes, (e.g. when constructing user-defined 89 classes): 90 </p> 91<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 92<li class="listitem"> 93 If <code class="computeroutput"><span class="identifier">BOOST_NO_EXCEPTIONS</span></code> 94 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> 95 statements. The class writer must handle and propagate error situations 96 internally as no error will be propagated through <span class="bold"><strong>Boost.Container</strong></span>. 97 </li> 98<li class="listitem"> 99 If <code class="computeroutput"><span class="identifier">BOOST_NO_EXCEPTIONS</span></code> 100 is <span class="bold"><strong>not</strong></span> defined, the library propagates 101 exceptions offering the exception guarantees detailed in the documentation. 102 </li> 103</ul></div> 104<p> 105 When the library needs to throw an exception (such as <code class="computeroutput"><span class="identifier">out_of_range</span></code> 106 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 107 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 <boost/container/throw_exception.hpp>">boost/container/throw_exception.hpp</a></code>: 108 </p> 109<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 110<li class="listitem"> 111 If <code class="computeroutput"><span class="identifier">BOOST_CONTAINER_USER_DEFINED_THROW_CALLBACKS</span></code> 112 is defined, then the programmer must provide its own definition for all 113 <code class="computeroutput"><span class="identifier">throw_xxx</span></code> functions. Those 114 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>. 115 </li> 116<li class="listitem"> 117 Else if <code class="computeroutput"><span class="identifier">BOOST_NO_EXCEPTIONS</span></code> 118 is defined, a <code class="computeroutput"><span class="identifier">BOOST_ASSERT_MSG</span></code> 119 assertion is triggered (see <a href="http://www.boost.org/libs/utility/assert.html" target="_top">Boost.Assert</a> 120 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> 121 is called. 122 </li> 123<li class="listitem"> 124 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>). 125 </li> 126</ul></div> 127</div> 128<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 129<td align="left"></td> 130<td align="right"><div class="copyright-footer">Copyright © 2009-2018 Ion Gaztanaga<p> 131 Distributed under the Boost Software License, Version 1.0. (See accompanying 132 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>) 133 </p> 134</div></td> 135</tr></table> 136<hr> 137<div class="spirit-nav"> 138<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> 139</div> 140</body> 141</html> 142
