1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Exceptions</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><meta name="keywords" content="C++, exception, error, exception neutrality, exception safety, exception propagation, -fno-exceptions" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="using.html" title="Chapter 3. Using" /><link rel="prev" href="using_concurrency.html" title="Concurrency" /><link rel="next" href="debug.html" title="Debugging Support" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Exceptions</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="using_concurrency.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td width="20%" align="right"> <a accesskey="n" href="debug.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.using.exceptions"></a>Exceptions</h2></div></div></div><p> 3The C++ language provides language support for stack unwinding 4with <code class="literal">try</code> and <code class="literal">catch</code> blocks and 5the <code class="literal">throw</code> keyword. 6</p><p> 7These are very powerful constructs, and require some thought when 8applied to the standard library in order to yield components that work 9efficiently while cleaning up resources when unexpectedly killed via 10exceptional circumstances. 11</p><p> 12Two general topics of discussion follow: 13exception neutrality and exception safety. 14</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="intro.using.exception.safety"></a>Exception Safety</h3></div></div></div><p> 15 What is exception-safe code? 16 </p><p> 17 Will define this as reasonable and well-defined behavior by classes 18 and functions from the standard library when used by user-defined 19 classes and functions that are themselves exception safe. 20 </p><p> 21 Please note that using exceptions in combination with templates 22 imposes an additional requirement for exception 23 safety. Instantiating types are required to have destructors that 24 do no throw. 25 </p><p> 26 Using the layered approach from Abrahams, can classify library 27 components as providing set levels of safety. These will be called 28 exception guarantees, and can be divided into three categories. 29 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> 30 One. Don't throw. 31 </p><p> 32 As specified in 23.2.1 general container requirements. Applicable 33 to container and string classes. 34 </p><p> 35 Member 36 functions <code class="function">erase</code>, <code class="function">pop_back</code>, <code class="function">pop_front</code>, <code class="function">swap</code>, <code class="function">clear</code>. And <span class="type">iterator</span> 37 copy constructor and assignment operator. 38 </p></li><li class="listitem"><p> 39 Two. Don't leak resources when exceptions are thrown. This is 40 also referred to as the <span class="quote">“<span class="quote">basic</span>”</span> exception safety guarantee. 41 </p><p> 42 This applicable throughout the standard library. 43 </p></li><li class="listitem"><p> 44 Three. Commit-or-rollback semantics. This is 45 referred to as <span class="quote">“<span class="quote">strong</span>”</span> exception safety guarantee. 46 </p><p> 47 As specified in 23.2.1 general container requirements. Applicable 48 to container and string classes. 49 </p><p> 50 Member functions <code class="function">insert</code> of a single 51 element, <code class="function">push_back</code>, <code class="function">push_front</code>, 52 and <code class="function">rehash</code>. 53 </p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="intro.using.exception.propagating"></a>Exception Neutrality</h3></div></div></div><p> 54 Simply put, once thrown an exception object should continue in 55 flight unless handled explicitly. In practice, this means 56 propagating exceptions should not be swallowed in 57 gratuitous <code class="literal">catch(...)</code> blocks. Instead, 58 matching <code class="literal">try</code> and <code class="literal">catch</code> 59 blocks should have specific catch handlers and allow un-handed 60 exception objects to propagate. If a 61 terminating <code class="literal">catch(...)</code> blocks exist then it 62 should end with a <code class="literal">throw</code> to re-throw the current 63 exception. 64 </p><p> 65 Why do this? 66 </p><p> 67 By allowing exception objects to propagate, a more flexible 68 approach to error handling is made possible (although not 69 required.) Instead of dealing with an error immediately, one can 70 allow the exception to propagate up until sufficient context is 71 available and the choice of exiting or retrying can be made in an 72 informed manner. 73 </p><p> 74 Unfortunately, this tends to be more of a guideline than a strict 75 rule as applied to the standard library. As such, the following is 76 a list of known problem areas where exceptions are not propagated. 77 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> 78 Input/Output 79 </p><p> 80 The destructor <code class="function">ios_base::Init::~Init()</code> 81 swallows all exceptions from <code class="function">flush</code> called on 82 all open streams at termination. 83 </p><p> 84 All formatted input in <code class="classname">basic_istream</code> or 85 formatted output in <code class="classname">basic_ostream</code> can be 86 configured to swallow exceptions 87 when <code class="function">exceptions</code> is set to 88 ignore <span class="type">ios_base::badbit</span>. 89 </p><p> 90 Functions that have been registered 91 with <code class="function">ios_base::register_callback</code> swallow all 92 exceptions when called as part of a callback event. 93 </p><p> 94 When closing the underlying 95 file, <code class="function">basic_filebuf::close</code> will swallow 96 (non-cancellation) exceptions thrown and return <code class="literal">NULL</code>. 97 </p></li><li class="listitem"><p> 98 Thread 99 </p><p> 100 The constructors of <code class="classname">thread</code> that take a 101 callable function argument swallow all exceptions resulting from 102 executing the function argument. 103 </p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="intro.using.exception.no"></a>Doing without</h3></div></div></div><p> 104 C++ is a language that strives to be as efficient as is possible 105 in delivering features. As such, considerable care is used by both 106 language implementer and designers to make sure unused features 107 not impose hidden or unexpected costs. The GNU system tries to be 108 as flexible and as configurable as possible. So, it should come as 109 no surprise that GNU C++ provides an optional language extension, 110 spelled <code class="literal">-fno-exceptions</code>, as a way to excise the 111 implicitly generated magic necessary to 112 support <code class="literal">try</code> and <code class="literal">catch</code> blocks 113 and thrown objects. (Language support 114 for <code class="literal">-fno-exceptions</code> is documented in the GNU 115 GCC <a class="link" href="http://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#Code-Gen-Options" target="_top">manual</a>.) 116 </p><p>Before detailing the library support 117 for <code class="literal">-fno-exceptions</code>, first a passing note on 118 the things lost when this flag is used: it will break exceptions 119 trying to pass through code compiled 120 with <code class="literal">-fno-exceptions</code> whether or not that code 121 has any <code class="literal">try</code> or <code class="literal">catch</code> 122 constructs. If you might have some code that throws, you shouldn't 123 use <code class="literal">-fno-exceptions</code>. If you have some code that 124 uses <code class="literal">try</code> or <code class="literal">catch</code>, you 125 shouldn't use <code class="literal">-fno-exceptions</code>. 126 </p><p> 127 And what it to be gained, tinkering in the back alleys with a 128 language like this? Exception handling overhead can be measured 129 in the size of the executable binary, and varies with the 130 capabilities of the underlying operating system and specific 131 configuration of the C++ compiler. On recent hardware with GNU 132 system software of the same age, the combined code and data size 133 overhead for enabling exception handling is around 7%. Of course, 134 if code size is of singular concern than using the appropriate 135 optimizer setting with exception handling enabled 136 (ie, <code class="literal">-Os -fexceptions</code>) may save up to twice 137 that, and preserve error checking. 138 </p><p> 139 So. Hell bent, we race down the slippery track, knowing the brakes 140 are a little soft and that the right front wheel has a tendency to 141 wobble at speed. Go on: detail the standard library support 142 for <code class="literal">-fno-exceptions</code>. 143 </p><p> 144 In sum, valid C++ code with exception handling is transformed into 145 a dialect without exception handling. In detailed steps: all use 146 of the C++ 147 keywords <code class="literal">try</code>, <code class="literal">catch</code>, 148 and <code class="literal">throw</code> in the standard library have been 149 permanently replaced with the pre-processor controlled equivalents 150 spelled <code class="literal">__try</code>, <code class="literal">__catch</code>, 151 and <code class="literal">__throw_exception_again</code>. They are defined 152 as follows. 153 </p><pre class="programlisting"> 154#if __cpp_exceptions 155# define __try try 156# define __catch(X) catch(X) 157# define __throw_exception_again throw 158#else 159# define __try if (true) 160# define __catch(X) if (false) 161# define __throw_exception_again 162#endif 163</pre><p> 164 In addition, for every object derived from 165 class <code class="classname">exception</code>, there exists a corresponding 166 function with C language linkage. An example: 167</p><pre class="programlisting"> 168#if __cpp_exceptions 169 void __throw_bad_exception(void) 170 { throw bad_exception(); } 171#else 172 void __throw_bad_exception(void) 173 { abort(); } 174#endif 175</pre><p> 176 The last language feature needing to be transformed 177 by <code class="literal">-fno-exceptions</code> is treatment of exception 178 specifications on member functions. Fortunately, the compiler deals 179 with this by ignoring exception specifications and so no alternate 180 source markup is needed. 181</p><p> 182 By using this combination of language re-specification by the 183 compiler, and the pre-processor tricks and the functional 184 indirection layer for thrown exception objects by the library, 185 libstdc++ files can be compiled 186 with <code class="literal">-fno-exceptions</code>. 187</p><p> 188 User code that uses C++ keywords 189 like <code class="literal">throw</code>, <code class="literal">try</code>, 190 and <code class="literal">catch</code> will produce errors even if the user 191 code has included libstdc++ headers and is using constructs 192 like <code class="classname">basic_iostream</code>. Even though the standard 193 library has been transformed, user code may need modification. User 194 code that attempts or expects to do error checking on standard 195 library components compiled with exception handling disabled should 196 be evaluated and potentially made conditional. 197</p><p> 198 Some issues remain with this approach (see bugzilla entry 199 25191). Code paths are not equivalent, in 200 particular <code class="literal">catch</code> blocks are not evaluated. Also 201 problematic are <code class="literal">throw</code> expressions expecting a 202 user-defined throw handler. Known problem areas in the standard 203 library include using an instance 204 of <code class="classname">basic_istream</code> 205 with <code class="function">exceptions</code> set to specific 206 <span class="type">ios_base::iostate</span> conditions, or 207 cascading <code class="literal">catch</code> blocks that dispatch error 208 handling or recovery efforts based on the type of exception object 209 thrown. 210</p><p> 211 Oh, and by the way: none of this hackery is at all 212 special. (Although perhaps well-deserving of a raised eyebrow.) 213 Support continues to evolve and may change in the future. Similar 214 and even additional techniques are used in other C++ libraries and 215 compilers. 216</p><p> 217 C++ hackers with a bent for language and control-flow purity have 218 been successfully consoled by grizzled C veterans lamenting the 219 substitution of the C language keyword 220 <code class="literal">const</code> with the uglified 221 doppelganger <code class="literal">__const</code>. 222</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="intro.using.exception.compat"></a>Compatibility</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="using.exception.compat.c"></a>With <code class="literal">C</code></h4></div></div></div><p> 223 C language code that is expecting to interoperate with C++ should be 224 compiled with <code class="literal">-fexceptions</code>. This will make 225 debugging a C language function called as part of C++-induced stack 226 unwinding possible. 227</p><p> 228 In particular, unwinding into a frame with no exception handling 229data will cause a runtime abort. If the unwinder runs out of unwind 230info before it finds a handler, <code class="function">std::terminate()</code> 231is called. 232</p><p> 233 Please note that most development environments should take care of 234 getting these details right. For GNU systems, all appropriate parts 235 of the GNU C library are already compiled 236 with <code class="literal">-fexceptions</code>. 237</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="using.exception.compat.posix"></a>With <code class="literal">POSIX</code> thread cancellation</h4></div></div></div><p> 238 GNU systems re-use some of the exception handling mechanisms to 239 track control flow for <code class="literal">POSIX</code> thread cancellation. 240</p><p> 241 Cancellation points are functions defined by POSIX as worthy of 242 special treatment. The standard library may use some of these 243 functions to implement parts of the ISO C++ standard or depend on 244 them for extensions. 245</p><p> 246 Of note: 247</p><p> 248 <code class="function">nanosleep</code>, 249 <code class="function">read</code>, <code class="function">write</code>, <code class="function">open</code>, <code class="function">close</code>, 250 and <code class="function">wait</code>. 251</p><p> 252 The parts of libstdc++ that use C library functions marked as 253 cancellation points should take pains to be exception neutral. 254 Failing this, <code class="literal">catch</code> blocks have been augmented to 255 show that the POSIX cancellation object is in flight. 256</p><p> 257 This augmentation adds a <code class="literal">catch</code> block 258 for <code class="classname">__cxxabiv1::__forced_unwind</code>, which is the 259 object representing the POSIX cancellation object. Like so: 260</p><pre class="programlisting"> 261 catch(const __cxxabiv1::__forced_unwind&) 262 { 263 this->_M_setstate(ios_base::badbit); 264 throw; 265 } 266 catch(...) 267 { this->_M_setstate(ios_base::badbit); } 268</pre></div></div><div class="bibliography"><div class="titlepage"><div><div><h3 class="title"><a id="using.exceptions.biblio"></a>Bibliography</h3></div></div></div><div class="biblioentry"><a id="id-1.3.3.4.9.9.2"></a><p><span class="title"><em> 269 <a class="link" href="http://www.opengroup.org/austin/" target="_top"> 270 System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008) 271 </a> 272 </em>. </span><span class="pagenums"> 273 2.9.5 Thread Cancellation 274 . </span><span class="copyright">Copyright © 2008 275 The Open Group/The Institute of Electrical and Electronics 276 Engineers, Inc. 277 . </span></p></div><div class="biblioentry"><a id="id-1.3.3.4.9.9.3"></a><p><span class="title"><em> 278 <a class="link" href="https://www.boost.org/community/error_handling.html" target="_top"> 279 Error and Exception Handling 280 </a> 281 </em>. </span><span class="author"><span class="firstname">David</span> <span class="surname">Abrahams </span>. </span><span class="publisher"><span class="publishername"> 282 Boost 283 . </span></span></p></div><div class="biblioentry"><a id="id-1.3.3.4.9.9.4"></a><p><span class="title"><em> 284 <a class="link" href="https://www.boost.org/community/exception_safety.html" target="_top"> 285 Exception-Safety in Generic Components 286 </a> 287 </em>. </span><span class="author"><span class="firstname">David</span> <span class="surname">Abrahams</span>. </span><span class="publisher"><span class="publishername"> 288 Boost 289 . </span></span></p></div><div class="biblioentry"><a id="id-1.3.3.4.9.9.5"></a><p><span class="title"><em> 290 <a class="link" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/1997/N1077.pdf" target="_top"> 291 Standard Library Exception Policy 292 </a> 293 </em>. </span><span class="author"><span class="firstname">Matt</span> <span class="surname">Austern</span>. </span><span class="publisher"><span class="publishername"> 294 WG21 N1077 295 . </span></span></p></div><div class="biblioentry"><a id="id-1.3.3.4.9.9.6"></a><p><span class="title"><em> 296 <a class="link" href="http://gcc.gnu.org/ml/gcc-patches/2001-03/msg00661.html" target="_top"> 297 ia64 c++ abi exception handling 298 </a> 299 </em>. </span><span class="author"><span class="firstname">Richard</span> <span class="surname">Henderson</span>. </span><span class="publisher"><span class="publishername"> 300 GNU 301 . </span></span></p></div><div class="biblioentry"><a id="id-1.3.3.4.9.9.7"></a><p><span class="title"><em> 302 <a class="link" href="https://www.stroustrup.com/3rd_safe.pdf" target="_top"> 303 Appendix E: Standard-Library Exception Safety 304 </a> 305 </em>. </span><span class="author"><span class="firstname">Bjarne</span> <span class="surname">Stroustrup</span>. </span></p></div><div class="biblioentry"><a id="id-1.3.3.4.9.9.8"></a><p><span class="citetitle"><em class="citetitle"> 306 Exceptional C++ 307 </em>. </span><span class="pagenums"> 308 Exception-Safety Issues and Techniques 309 . </span><span class="author"><span class="firstname">Herb</span> <span class="surname">Sutter</span>. </span></p></div><div class="biblioentry"><a id="id-1.3.3.4.9.9.9"></a><p><span class="title"><em> 310 <a class="link" href="http://gcc.gnu.org/PR25191" target="_top"> 311 GCC Bug 25191: exception_defines.h #defines try/catch 312 </a> 313 </em>. </span></p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="using_concurrency.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="using.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="debug.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Concurrency </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Debugging Support</td></tr></table></div></body></html>