libstdc++-v3/doc/html/manual/using_exceptions.html

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