136ac495dSmrg<?xml version="1.0" encoding="UTF-8" standalone="no"?> 236ac495dSmrg<!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> 336ac495dSmrgThe C++ language provides language support for stack unwinding 436ac495dSmrgwith <code class="literal">try</code> and <code class="literal">catch</code> blocks and 536ac495dSmrgthe <code class="literal">throw</code> keyword. 636ac495dSmrg</p><p> 736ac495dSmrgThese are very powerful constructs, and require some thought when 836ac495dSmrgapplied to the standard library in order to yield components that work 936ac495dSmrgefficiently while cleaning up resources when unexpectedly killed via 1036ac495dSmrgexceptional circumstances. 1136ac495dSmrg</p><p> 1236ac495dSmrgTwo general topics of discussion follow: 1336ac495dSmrgexception neutrality and exception safety. 1436ac495dSmrg</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> 1536ac495dSmrg What is exception-safe code? 1636ac495dSmrg </p><p> 1736ac495dSmrg Will define this as reasonable and well-defined behavior by classes 1836ac495dSmrg and functions from the standard library when used by user-defined 1936ac495dSmrg classes and functions that are themselves exception safe. 2036ac495dSmrg </p><p> 2136ac495dSmrg Please note that using exceptions in combination with templates 2236ac495dSmrg imposes an additional requirement for exception 2336ac495dSmrg safety. Instantiating types are required to have destructors that 2436ac495dSmrg do no throw. 2536ac495dSmrg </p><p> 2636ac495dSmrg Using the layered approach from Abrahams, can classify library 2736ac495dSmrg components as providing set levels of safety. These will be called 2836ac495dSmrg exception guarantees, and can be divided into three categories. 2936ac495dSmrg </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> 3036ac495dSmrg One. Don't throw. 3136ac495dSmrg </p><p> 3236ac495dSmrg As specified in 23.2.1 general container requirements. Applicable 3336ac495dSmrg to container and string classes. 3436ac495dSmrg </p><p> 3536ac495dSmrg Member 3636ac495dSmrg 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> 3736ac495dSmrg copy constructor and assignment operator. 3836ac495dSmrg </p></li><li class="listitem"><p> 3936ac495dSmrg Two. Don't leak resources when exceptions are thrown. This is 4036ac495dSmrg also referred to as the <span class="quote">“<span class="quote">basic</span>”</span> exception safety guarantee. 4136ac495dSmrg </p><p> 4236ac495dSmrg This applicable throughout the standard library. 4336ac495dSmrg </p></li><li class="listitem"><p> 4436ac495dSmrg Three. Commit-or-rollback semantics. This is 4536ac495dSmrg referred to as <span class="quote">“<span class="quote">strong</span>”</span> exception safety guarantee. 4636ac495dSmrg </p><p> 4736ac495dSmrg As specified in 23.2.1 general container requirements. Applicable 4836ac495dSmrg to container and string classes. 4936ac495dSmrg </p><p> 5036ac495dSmrg Member functions <code class="function">insert</code> of a single 5136ac495dSmrg element, <code class="function">push_back</code>, <code class="function">push_front</code>, 5236ac495dSmrg and <code class="function">rehash</code>. 5336ac495dSmrg </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> 5436ac495dSmrg Simply put, once thrown an exception object should continue in 5536ac495dSmrg flight unless handled explicitly. In practice, this means 5636ac495dSmrg propagating exceptions should not be swallowed in 5736ac495dSmrg gratuitous <code class="literal">catch(...)</code> blocks. Instead, 5836ac495dSmrg matching <code class="literal">try</code> and <code class="literal">catch</code> 5936ac495dSmrg blocks should have specific catch handlers and allow un-handed 6036ac495dSmrg exception objects to propagate. If a 6136ac495dSmrg terminating <code class="literal">catch(...)</code> blocks exist then it 6236ac495dSmrg should end with a <code class="literal">throw</code> to re-throw the current 6336ac495dSmrg exception. 6436ac495dSmrg </p><p> 6536ac495dSmrg Why do this? 6636ac495dSmrg </p><p> 6736ac495dSmrg By allowing exception objects to propagate, a more flexible 6836ac495dSmrg approach to error handling is made possible (although not 6936ac495dSmrg required.) Instead of dealing with an error immediately, one can 7036ac495dSmrg allow the exception to propagate up until sufficient context is 7136ac495dSmrg available and the choice of exiting or retrying can be made in an 7236ac495dSmrg informed manner. 7336ac495dSmrg </p><p> 7436ac495dSmrg Unfortunately, this tends to be more of a guideline than a strict 7536ac495dSmrg rule as applied to the standard library. As such, the following is 7636ac495dSmrg a list of known problem areas where exceptions are not propagated. 7736ac495dSmrg </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> 7836ac495dSmrg Input/Output 7936ac495dSmrg </p><p> 8036ac495dSmrg The destructor <code class="function">ios_base::Init::~Init()</code> 8136ac495dSmrg swallows all exceptions from <code class="function">flush</code> called on 8236ac495dSmrg all open streams at termination. 8336ac495dSmrg </p><p> 8436ac495dSmrg All formatted input in <code class="classname">basic_istream</code> or 8536ac495dSmrg formatted output in <code class="classname">basic_ostream</code> can be 8636ac495dSmrg configured to swallow exceptions 8736ac495dSmrg when <code class="function">exceptions</code> is set to 8836ac495dSmrg ignore <span class="type">ios_base::badbit</span>. 8936ac495dSmrg </p><p> 9036ac495dSmrg Functions that have been registered 9136ac495dSmrg with <code class="function">ios_base::register_callback</code> swallow all 9236ac495dSmrg exceptions when called as part of a callback event. 9336ac495dSmrg </p><p> 9436ac495dSmrg When closing the underlying 9536ac495dSmrg file, <code class="function">basic_filebuf::close</code> will swallow 9636ac495dSmrg (non-cancellation) exceptions thrown and return <code class="literal">NULL</code>. 9736ac495dSmrg </p></li><li class="listitem"><p> 9836ac495dSmrg Thread 9936ac495dSmrg </p><p> 10036ac495dSmrg The constructors of <code class="classname">thread</code> that take a 10136ac495dSmrg callable function argument swallow all exceptions resulting from 10236ac495dSmrg executing the function argument. 10336ac495dSmrg </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> 10436ac495dSmrg C++ is a language that strives to be as efficient as is possible 10536ac495dSmrg in delivering features. As such, considerable care is used by both 10636ac495dSmrg language implementer and designers to make sure unused features 10736ac495dSmrg not impose hidden or unexpected costs. The GNU system tries to be 10836ac495dSmrg as flexible and as configurable as possible. So, it should come as 10936ac495dSmrg no surprise that GNU C++ provides an optional language extension, 11036ac495dSmrg spelled <code class="literal">-fno-exceptions</code>, as a way to excise the 11136ac495dSmrg implicitly generated magic necessary to 11236ac495dSmrg support <code class="literal">try</code> and <code class="literal">catch</code> blocks 11336ac495dSmrg and thrown objects. (Language support 11436ac495dSmrg for <code class="literal">-fno-exceptions</code> is documented in the GNU 11536ac495dSmrg GCC <a class="link" href="http://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#Code-Gen-Options" target="_top">manual</a>.) 11636ac495dSmrg </p><p>Before detailing the library support 11736ac495dSmrg for <code class="literal">-fno-exceptions</code>, first a passing note on 11836ac495dSmrg the things lost when this flag is used: it will break exceptions 11936ac495dSmrg trying to pass through code compiled 12036ac495dSmrg with <code class="literal">-fno-exceptions</code> whether or not that code 12136ac495dSmrg has any <code class="literal">try</code> or <code class="literal">catch</code> 12236ac495dSmrg constructs. If you might have some code that throws, you shouldn't 12336ac495dSmrg use <code class="literal">-fno-exceptions</code>. If you have some code that 12436ac495dSmrg uses <code class="literal">try</code> or <code class="literal">catch</code>, you 12536ac495dSmrg shouldn't use <code class="literal">-fno-exceptions</code>. 12636ac495dSmrg </p><p> 12736ac495dSmrg And what it to be gained, tinkering in the back alleys with a 12836ac495dSmrg language like this? Exception handling overhead can be measured 12936ac495dSmrg in the size of the executable binary, and varies with the 13036ac495dSmrg capabilities of the underlying operating system and specific 13136ac495dSmrg configuration of the C++ compiler. On recent hardware with GNU 13236ac495dSmrg system software of the same age, the combined code and data size 13336ac495dSmrg overhead for enabling exception handling is around 7%. Of course, 13436ac495dSmrg if code size is of singular concern than using the appropriate 13536ac495dSmrg optimizer setting with exception handling enabled 13636ac495dSmrg (ie, <code class="literal">-Os -fexceptions</code>) may save up to twice 13736ac495dSmrg that, and preserve error checking. 13836ac495dSmrg </p><p> 13936ac495dSmrg So. Hell bent, we race down the slippery track, knowing the brakes 14036ac495dSmrg are a little soft and that the right front wheel has a tendency to 14136ac495dSmrg wobble at speed. Go on: detail the standard library support 14236ac495dSmrg for <code class="literal">-fno-exceptions</code>. 14336ac495dSmrg </p><p> 14436ac495dSmrg In sum, valid C++ code with exception handling is transformed into 14536ac495dSmrg a dialect without exception handling. In detailed steps: all use 14636ac495dSmrg of the C++ 14736ac495dSmrg keywords <code class="literal">try</code>, <code class="literal">catch</code>, 14836ac495dSmrg and <code class="literal">throw</code> in the standard library have been 14936ac495dSmrg permanently replaced with the pre-processor controlled equivalents 15036ac495dSmrg spelled <code class="literal">__try</code>, <code class="literal">__catch</code>, 15136ac495dSmrg and <code class="literal">__throw_exception_again</code>. They are defined 15236ac495dSmrg as follows. 15336ac495dSmrg </p><pre class="programlisting"> 15436ac495dSmrg#if __cpp_exceptions 15536ac495dSmrg# define __try try 15636ac495dSmrg# define __catch(X) catch(X) 15736ac495dSmrg# define __throw_exception_again throw 15836ac495dSmrg#else 15936ac495dSmrg# define __try if (true) 16036ac495dSmrg# define __catch(X) if (false) 16136ac495dSmrg# define __throw_exception_again 16236ac495dSmrg#endif 16336ac495dSmrg</pre><p> 16436ac495dSmrg In addition, for every object derived from 16536ac495dSmrg class <code class="classname">exception</code>, there exists a corresponding 16636ac495dSmrg function with C language linkage. An example: 16736ac495dSmrg</p><pre class="programlisting"> 16836ac495dSmrg#if __cpp_exceptions 16936ac495dSmrg void __throw_bad_exception(void) 17036ac495dSmrg { throw bad_exception(); } 17136ac495dSmrg#else 17236ac495dSmrg void __throw_bad_exception(void) 17336ac495dSmrg { abort(); } 17436ac495dSmrg#endif 17536ac495dSmrg</pre><p> 17636ac495dSmrg The last language feature needing to be transformed 17736ac495dSmrg by <code class="literal">-fno-exceptions</code> is treatment of exception 17836ac495dSmrg specifications on member functions. Fortunately, the compiler deals 17936ac495dSmrg with this by ignoring exception specifications and so no alternate 18036ac495dSmrg source markup is needed. 18136ac495dSmrg</p><p> 18236ac495dSmrg By using this combination of language re-specification by the 18336ac495dSmrg compiler, and the pre-processor tricks and the functional 18436ac495dSmrg indirection layer for thrown exception objects by the library, 18536ac495dSmrg libstdc++ files can be compiled 18636ac495dSmrg with <code class="literal">-fno-exceptions</code>. 18736ac495dSmrg</p><p> 18836ac495dSmrg User code that uses C++ keywords 18936ac495dSmrg like <code class="literal">throw</code>, <code class="literal">try</code>, 19036ac495dSmrg and <code class="literal">catch</code> will produce errors even if the user 19136ac495dSmrg code has included libstdc++ headers and is using constructs 19236ac495dSmrg like <code class="classname">basic_iostream</code>. Even though the standard 19336ac495dSmrg library has been transformed, user code may need modification. User 19436ac495dSmrg code that attempts or expects to do error checking on standard 19536ac495dSmrg library components compiled with exception handling disabled should 19636ac495dSmrg be evaluated and potentially made conditional. 19736ac495dSmrg</p><p> 19836ac495dSmrg Some issues remain with this approach (see bugzilla entry 19936ac495dSmrg 25191). Code paths are not equivalent, in 20036ac495dSmrg particular <code class="literal">catch</code> blocks are not evaluated. Also 20136ac495dSmrg problematic are <code class="literal">throw</code> expressions expecting a 20236ac495dSmrg user-defined throw handler. Known problem areas in the standard 20336ac495dSmrg library include using an instance 20436ac495dSmrg of <code class="classname">basic_istream</code> 20536ac495dSmrg with <code class="function">exceptions</code> set to specific 20636ac495dSmrg <span class="type">ios_base::iostate</span> conditions, or 20736ac495dSmrg cascading <code class="literal">catch</code> blocks that dispatch error 20836ac495dSmrg handling or recovery efforts based on the type of exception object 20936ac495dSmrg thrown. 21036ac495dSmrg</p><p> 21136ac495dSmrg Oh, and by the way: none of this hackery is at all 21236ac495dSmrg special. (Although perhaps well-deserving of a raised eyebrow.) 21336ac495dSmrg Support continues to evolve and may change in the future. Similar 21436ac495dSmrg and even additional techniques are used in other C++ libraries and 21536ac495dSmrg compilers. 21636ac495dSmrg</p><p> 21736ac495dSmrg C++ hackers with a bent for language and control-flow purity have 21836ac495dSmrg been successfully consoled by grizzled C veterans lamenting the 21936ac495dSmrg substitution of the C language keyword 22036ac495dSmrg <code class="literal">const</code> with the uglified 22136ac495dSmrg doppelganger <code class="literal">__const</code>. 22236ac495dSmrg</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> 22336ac495dSmrg C language code that is expecting to interoperate with C++ should be 22436ac495dSmrg compiled with <code class="literal">-fexceptions</code>. This will make 22536ac495dSmrg debugging a C language function called as part of C++-induced stack 22636ac495dSmrg unwinding possible. 22736ac495dSmrg</p><p> 22836ac495dSmrg In particular, unwinding into a frame with no exception handling 22936ac495dSmrgdata will cause a runtime abort. If the unwinder runs out of unwind 23036ac495dSmrginfo before it finds a handler, <code class="function">std::terminate()</code> 23136ac495dSmrgis called. 23236ac495dSmrg</p><p> 23336ac495dSmrg Please note that most development environments should take care of 23436ac495dSmrg getting these details right. For GNU systems, all appropriate parts 23536ac495dSmrg of the GNU C library are already compiled 23636ac495dSmrg with <code class="literal">-fexceptions</code>. 23736ac495dSmrg</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> 23836ac495dSmrg GNU systems re-use some of the exception handling mechanisms to 23936ac495dSmrg track control flow for <code class="literal">POSIX</code> thread cancellation. 24036ac495dSmrg</p><p> 24136ac495dSmrg Cancellation points are functions defined by POSIX as worthy of 24236ac495dSmrg special treatment. The standard library may use some of these 24336ac495dSmrg functions to implement parts of the ISO C++ standard or depend on 24436ac495dSmrg them for extensions. 24536ac495dSmrg</p><p> 24636ac495dSmrg Of note: 24736ac495dSmrg</p><p> 24836ac495dSmrg <code class="function">nanosleep</code>, 24936ac495dSmrg <code class="function">read</code>, <code class="function">write</code>, <code class="function">open</code>, <code class="function">close</code>, 25036ac495dSmrg and <code class="function">wait</code>. 25136ac495dSmrg</p><p> 25236ac495dSmrg The parts of libstdc++ that use C library functions marked as 25336ac495dSmrg cancellation points should take pains to be exception neutral. 25436ac495dSmrg Failing this, <code class="literal">catch</code> blocks have been augmented to 25536ac495dSmrg show that the POSIX cancellation object is in flight. 25636ac495dSmrg</p><p> 25736ac495dSmrg This augmentation adds a <code class="literal">catch</code> block 25836ac495dSmrg for <code class="classname">__cxxabiv1::__forced_unwind</code>, which is the 25936ac495dSmrg object representing the POSIX cancellation object. Like so: 26036ac495dSmrg</p><pre class="programlisting"> 26136ac495dSmrg catch(const __cxxabiv1::__forced_unwind&) 26236ac495dSmrg { 26336ac495dSmrg this->_M_setstate(ios_base::badbit); 26436ac495dSmrg throw; 26536ac495dSmrg } 26636ac495dSmrg catch(...) 26736ac495dSmrg { this->_M_setstate(ios_base::badbit); } 26836ac495dSmrg</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> 26936ac495dSmrg <a class="link" href="http://www.opengroup.org/austin/" target="_top"> 27036ac495dSmrg System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008) 27136ac495dSmrg </a> 27236ac495dSmrg </em>. </span><span class="pagenums"> 27336ac495dSmrg 2.9.5 Thread Cancellation 27436ac495dSmrg . </span><span class="copyright">Copyright © 2008 27536ac495dSmrg The Open Group/The Institute of Electrical and Electronics 27636ac495dSmrg Engineers, Inc. 27736ac495dSmrg . </span></p></div><div class="biblioentry"><a id="id-1.3.3.4.9.9.3"></a><p><span class="title"><em> 278*c0a68be4Smrg <a class="link" href="https://www.boost.org/community/error_handling.html" target="_top"> 27936ac495dSmrg Error and Exception Handling 28036ac495dSmrg </a> 28136ac495dSmrg </em>. </span><span class="author"><span class="firstname">David</span> <span class="surname">Abrahams </span>. </span><span class="publisher"><span class="publishername"> 28236ac495dSmrg Boost 28336ac495dSmrg . </span></span></p></div><div class="biblioentry"><a id="id-1.3.3.4.9.9.4"></a><p><span class="title"><em> 284*c0a68be4Smrg <a class="link" href="https://www.boost.org/community/exception_safety.html" target="_top"> 28536ac495dSmrg Exception-Safety in Generic Components 28636ac495dSmrg </a> 28736ac495dSmrg </em>. </span><span class="author"><span class="firstname">David</span> <span class="surname">Abrahams</span>. </span><span class="publisher"><span class="publishername"> 28836ac495dSmrg Boost 28936ac495dSmrg . </span></span></p></div><div class="biblioentry"><a id="id-1.3.3.4.9.9.5"></a><p><span class="title"><em> 29036ac495dSmrg <a class="link" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/1997/N1077.pdf" target="_top"> 29136ac495dSmrg Standard Library Exception Policy 29236ac495dSmrg </a> 29336ac495dSmrg </em>. </span><span class="author"><span class="firstname">Matt</span> <span class="surname">Austern</span>. </span><span class="publisher"><span class="publishername"> 29436ac495dSmrg WG21 N1077 29536ac495dSmrg . </span></span></p></div><div class="biblioentry"><a id="id-1.3.3.4.9.9.6"></a><p><span class="title"><em> 29636ac495dSmrg <a class="link" href="http://gcc.gnu.org/ml/gcc-patches/2001-03/msg00661.html" target="_top"> 29736ac495dSmrg ia64 c++ abi exception handling 29836ac495dSmrg </a> 29936ac495dSmrg </em>. </span><span class="author"><span class="firstname">Richard</span> <span class="surname">Henderson</span>. </span><span class="publisher"><span class="publishername"> 30036ac495dSmrg GNU 30136ac495dSmrg . </span></span></p></div><div class="biblioentry"><a id="id-1.3.3.4.9.9.7"></a><p><span class="title"><em> 30236ac495dSmrg <a class="link" href="http://www.stroustrup.com/3rd_safe.pdf" target="_top"> 30336ac495dSmrg Appendix E: Standard-Library Exception Safety 30436ac495dSmrg </a> 30536ac495dSmrg </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"> 30636ac495dSmrg Exceptional C++ 30736ac495dSmrg </em>. </span><span class="pagenums"> 30836ac495dSmrg Exception-Safety Issues and Techniques 30936ac495dSmrg . </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> 31036ac495dSmrg <a class="link" href="http://gcc.gnu.org/PR25191" target="_top"> 31136ac495dSmrg GCC Bug 25191: exception_defines.h #defines try/catch 31236ac495dSmrg </a> 31336ac495dSmrg </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>