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

   1 <section xmlns="http://docbook.org/ns/docbook" version="5.0"
   2          xml:id="manual.intro.using.exceptions" xreflabel="Using Exceptions">
   3 <?dbhtml filename="using_exceptions.html"?>
   4
   5 <info><title>Exceptions</title>
   6   <keywordset>
   7     <keyword>C++</keyword>
   8     <keyword>exception</keyword>
   9     <keyword>error</keyword>
  10     <keyword>exception neutrality</keyword>
  11     <keyword>exception safety</keyword>
  12     <keyword>exception propagation</keyword>
  13     <keyword>-fno-exceptions</keyword>
  14   </keywordset>
  15 </info>
  16
  17 <para>
  18 The C++ language provides language support for stack unwinding
  19 with <literal>try</literal> and <literal>catch</literal> blocks and
  20 the <literal>throw</literal> keyword.
  21 </para>
  22
  23 <para>
  24 These are very powerful constructs, and require some thought when
  25 applied to the standard library in order to yield components that work
  26 efficiently while cleaning up resources when unexpectedly killed via
  27 exceptional circumstances.
  28 </para>
  29
  30 <para>
  31 Two general topics of discussion follow:
  32 exception neutrality and exception safety.
  33 </para>
  34
  35
  36 <section xml:id="intro.using.exception.safety" xreflabel="Exception Safety"><info><title>Exception Safety</title></info>
  37
  38
  39   <para>
  40     What is exception-safe code?
  41   </para>
  42
  43   <para>
  44     Will define this as reasonable and well-defined behavior by classes
  45     and functions from the standard library when used by user-defined
  46     classes and functions that are themselves exception safe.
  47   </para>
  48
  49   <para>
  50     Please note that using exceptions in combination with templates
  51     imposes an additional requirement for exception
  52     safety. Instantiating types are required to have destructors that
  53     do no throw.
  54   </para>
  55
  56   <para>
  57     Using the layered approach from Abrahams, can classify library
  58     components as providing set levels of safety. These will be called
  59     exception guarantees, and can be divided into three categories.
  60   </para>
  61
  62 <itemizedlist>
  63
  64   <listitem>
  65   <para>
  66     One. Don't throw.
  67   </para>
  68   <para>
  69     As specified in 23.2.1 general container requirements. Applicable
  70     to container and string classes.
  71   </para>
  72   <para>
  73     Member
  74     functions <function>erase</function>, <function>pop_back</function>, <function>pop_front</function>, <function>swap</function>, <function>clear</function>. And <type>iterator</type>
  75     copy constructor and assignment operator.
  76   </para>
  77   </listitem>
  78
  79   <listitem>
  80   <para>
  81     Two. Don't leak resources when exceptions are thrown. This is
  82     also referred to as the <quote>basic</quote> exception safety guarantee.
  83   </para>
  84
  85   <para>
  86     This applicable throughout the standard library.
  87   </para>
  88   </listitem>
  89
  90   <listitem>
  91   <para>
  92     Three. Commit-or-rollback semantics.  This is
  93     referred to as <quote>strong</quote> exception safety guarantee.
  94   </para>
  95
  96   <para>
  97     As specified in 23.2.1 general container requirements. Applicable
  98     to container and string classes.
  99   </para>
 100   <para>
 101     Member functions <function>insert</function> of a single
 102     element, <function>push_back</function>, <function>push_front</function>,
 103     and <function>rehash</function>.
 104   </para>
 105
 106   </listitem>
 107 </itemizedlist>
 108
 109 </section>
 110
 111
 112 <section xml:id="intro.using.exception.propagating" xreflabel="Exceptions Neutrality"><info><title>Exception Neutrality</title></info>
 113
 114   <para>
 115     Simply put, once thrown an exception object should continue in
 116     flight unless handled explicitly. In practice, this means
 117     propagating exceptions should not be swallowed in
 118     gratuitous <literal>catch(...)</literal> blocks. Instead,
 119     matching <literal>try</literal> and <literal>catch</literal>
 120     blocks should have specific catch handlers and allow un-handed
 121     exception objects to propagate. If a
 122     terminating <literal>catch(...)</literal> blocks exist then it
 123     should end with a <literal>throw</literal> to re-throw the current
 124     exception.
 125   </para>
 126
 127   <para>
 128     Why do this?
 129   </para>
 130
 131   <para>
 132     By allowing exception objects to propagate, a more flexible
 133     approach to error handling is made possible (although not
 134     required.) Instead of dealing with an error immediately, one can
 135     allow the exception to propagate up until sufficient context is
 136     available and the choice of exiting or retrying can be made in an
 137     informed manner.
 138   </para>
 139
 140   <para>
 141     Unfortunately, this tends to be more of a guideline than a strict
 142     rule as applied to the standard library. As such, the following is
 143     a list of known problem areas where exceptions are not propagated.
 144   </para>
 145
 146 <itemizedlist>
 147   <listitem>
 148     <para>
 149       Input/Output
 150     </para>
 151   <para>
 152     The destructor <function>ios_base::Init::~Init()</function>
 153     swallows all exceptions from <function>flush</function> called on
 154     all open streams at termination.
 155   </para>
 156
 157   <para>
 158     All formatted input in <classname>basic_istream</classname> or
 159     formatted output in <classname>basic_ostream</classname> can be
 160     configured to swallow exceptions
 161     when <function>exceptions</function> is set to
 162     ignore <type>ios_base::badbit</type>.
 163   </para>
 164
 165   <para>
 166     Functions that have been registered
 167     with <function>ios_base::register_callback</function> swallow all
 168     exceptions when called as part of a callback event.
 169   </para>
 170
 171   <para>
 172     When closing the underlying
 173     file, <function>basic_filebuf::close</function> will swallow
 174     (non-cancellation) exceptions thrown and return <literal>NULL</literal>.
 175   </para>
 176   </listitem>
 177   <listitem>
 178     <para>
 179       Thread
 180     </para>
 181     <para>
 182       The constructors of <classname>thread</classname> that take a
 183       callable function argument swallow all exceptions resulting from
 184       executing the function argument.
 185     </para>
 186   </listitem>
 187 </itemizedlist>
 188
 189 </section>
 190
 191 <section xml:id="intro.using.exception.no" xreflabel="-fno-exceptions"><info><title>Doing without</title></info>
 192
 193   <para>
 194     C++ is a language that strives to be as efficient as is possible
 195     in delivering features. As such, considerable care is used by both
 196     language implementer and designers to make sure unused features
 197     not impose hidden or unexpected costs. The GNU system tries to be
 198     as flexible and as configurable as possible. So, it should come as
 199     no surprise that GNU C++ provides an optional language extension,
 200     spelled <literal>-fno-exceptions</literal>, as a way to excise the
 201     implicitly generated magic necessary to
 202     support <literal>try</literal> and <literal>catch</literal> blocks
 203     and thrown objects. (Language support
 204     for <literal>-fno-exceptions</literal> is documented in the GNU
 205     GCC <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#Code-Gen-Options">manual</link>.)
 206   </para>
 207
 208   <para>Before detailing the library support
 209     for <literal>-fno-exceptions</literal>, first a passing note on
 210     the things lost when this flag is used: it will break exceptions
 211     trying to pass through code compiled
 212     with <literal>-fno-exceptions</literal> whether or not that code
 213     has any <literal>try</literal> or <literal>catch</literal>
 214     constructs. If you might have some code that throws, you shouldn't
 215     use <literal>-fno-exceptions</literal>. If you have some code that
 216     uses <literal>try</literal> or <literal>catch</literal>, you
 217     shouldn't use <literal>-fno-exceptions</literal>.
 218   </para>
 219
 220   <para>
 221     And what it to be gained, tinkering in the back alleys with a
 222     language like this? Exception handling overhead can be measured
 223     in the size of the executable binary, and varies with the
 224     capabilities of the underlying operating system and specific
 225     configuration of the C++ compiler. On recent hardware with GNU
 226     system software of the same age, the combined code and data size
 227     overhead for enabling exception handling is around 7%. Of course,
 228     if code size is of singular concern than using the appropriate
 229     optimizer setting with exception handling enabled
 230     (ie, <literal>-Os -fexceptions</literal>) may save up to twice
 231     that, and preserve error checking.
 232   </para>
 233
 234   <para>
 235     So. Hell bent, we race down the slippery track, knowing the brakes
 236     are a little soft and that the right front wheel has a tendency to
 237     wobble at speed. Go on: detail the standard library support
 238     for <literal>-fno-exceptions</literal>.
 239   </para>
 240
 241   <para>
 242     In sum, valid C++ code with exception handling is transformed into
 243     a dialect without exception handling. In detailed steps: all use
 244     of the C++
 245     keywords <literal>try</literal>, <literal>catch</literal>,
 246     and <literal>throw</literal> in the standard library have been
 247     permanently replaced with the pre-processor controlled equivalents
 248     spelled <literal>__try</literal>, <literal>__catch</literal>,
 249     and <literal>__throw_exception_again</literal>. They are defined
 250     as follows.
 251   </para>
 252
 253 <programlisting>
 254 #if __cpp_exceptions
 255 # define __try      try
 256 # define __catch(X) catch(X)
 257 # define __throw_exception_again throw
 258 #else
 259 # define __try      if (true)
 260 # define __catch(X) if (false)
 261 # define __throw_exception_again
 262 #endif
 263 </programlisting>
 264
 265 <para>
 266   In addition, for every object derived from
 267   class <classname>exception</classname>, there exists a corresponding
 268   function with C language linkage. An example:
 269 </para>
 270
 271 <programlisting>
 272 #if __cpp_exceptions
 273   void __throw_bad_exception(void)
 274   { throw bad_exception(); }
 275 #else
 276   void __throw_bad_exception(void)
 277   { abort(); }
 278 #endif
 279 </programlisting>
 280
 281 <para>
 282   The last language feature needing to be transformed
 283   by <literal>-fno-exceptions</literal> is treatment of exception
 284   specifications on member functions. Fortunately, the compiler deals
 285   with this by ignoring exception specifications and so no alternate
 286   source markup is needed.
 287 </para>
 288
 289 <para>
 290   By using this combination of language re-specification by the
 291   compiler, and the pre-processor tricks and the functional
 292   indirection layer for thrown exception objects by the library,
 293   libstdc++ files can be compiled
 294   with <literal>-fno-exceptions</literal>.
 295 </para>
 296
 297 <para>
 298  User code that uses C++ keywords
 299  like <literal>throw</literal>, <literal>try</literal>,
 300  and <literal>catch</literal> will produce errors even if the user
 301  code has included libstdc++ headers and is using constructs
 302  like <classname>basic_iostream</classname>. Even though the standard
 303  library has been transformed, user code may need modification. User
 304   code that attempts or expects to do error checking on standard
 305   library components compiled with exception handling disabled should
 306   be evaluated and potentially made conditional.
 307 </para>
 308
 309 <para>
 310   Some issues remain with this approach (see bugzilla entry
 311   25191). Code paths are not equivalent, in
 312   particular <literal>catch</literal> blocks are not evaluated. Also
 313   problematic are <literal>throw</literal> expressions expecting a
 314   user-defined throw handler. Known problem areas in the standard
 315   library include using an instance
 316   of <classname>basic_istream</classname>
 317   with <function>exceptions</function> set to specific
 318   <type>ios_base::iostate</type> conditions, or
 319   cascading <literal>catch</literal> blocks that dispatch error
 320   handling or recovery efforts based on the type of exception object
 321   thrown.
 322 </para>
 323
 324 <para>
 325   Oh, and by the way: none of this hackery is at all
 326   special. (Although perhaps well-deserving of a raised eyebrow.)
 327   Support continues to evolve and may change in the future. Similar
 328   and even additional techniques are used in other C++ libraries and
 329   compilers.
 330 </para>
 331
 332 <para>
 333  C++ hackers with a bent for language and control-flow purity have
 334   been successfully consoled by grizzled C veterans lamenting the
 335   substitution of the C language keyword
 336   <literal>const</literal> with the uglified
 337   doppelganger <literal>__const</literal>.
 338 </para>
 339
 340
 341 </section>
 342
 343 <section xml:id="intro.using.exception.compat"><info><title>Compatibility</title></info>
 344
 345
 346 <section xml:id="using.exception.compat.c"><info><title>With <literal>C</literal></title></info>
 347
 348 <para>
 349   C language code that is expecting to interoperate with C++ should be
 350   compiled with <literal>-fexceptions</literal>. This will make
 351   debugging a C language function called as part of C++-induced stack
 352   unwinding possible.
 353 </para>
 354
 355 <para>
 356   In particular, unwinding into a frame with no exception handling
 357 data will cause a runtime abort. If the unwinder runs out of unwind
 358 info before it finds a handler, <function>std::terminate()</function>
 359 is called.
 360 </para>
 361
 362 <para>
 363   Please note that most development environments should take care of
 364   getting these details right. For GNU systems, all appropriate parts
 365   of the GNU C library are already compiled
 366   with <literal>-fexceptions</literal>.
 367 </para>
 368
 369 </section>
 370
 371 <section xml:id="using.exception.compat.posix"><info><title>With <literal>POSIX</literal> thread cancellation</title></info>
 372
 373
 374 <para>
 375   GNU systems re-use some of the exception handling mechanisms to
 376   track control flow for <literal>POSIX</literal> thread cancellation.
 377 </para>
 378
 379 <para>
 380   Cancellation points are functions defined by POSIX as worthy of
 381   special treatment. The standard library may use some of these
 382   functions to implement parts of the ISO C++ standard or depend on
 383   them for extensions.
 384 </para>
 385
 386 <para>
 387   Of note:
 388 </para>
 389
 390 <para>
 391   <function>nanosleep</function>,
 392   <function>read</function>, <function>write</function>, <function>open</function>, <function>close</function>,
 393   and <function>wait</function>.
 394 </para>
 395
 396 <para>
 397   The parts of libstdc++ that use C library functions marked as
 398   cancellation points should take pains to be exception neutral.
 399   Failing this, <literal>catch</literal> blocks have been augmented to
 400   show that the POSIX cancellation object is in flight.
 401 </para>
 402
 403 <para>
 404   This augmentation adds a <literal>catch</literal> block
 405   for <classname>__cxxabiv1::__forced_unwind</classname>, which is the
 406   object representing the POSIX cancellation object. Like so:
 407 </para>
 408
 409 <programlisting>
 410   catch(const __cxxabiv1::__forced_unwind&amp;)
 411   {
 412     this-&gt;_M_setstate(ios_base::badbit);
 413     throw;
 414   }
 415   catch(...)
 416   { this-&gt;_M_setstate(ios_base::badbit); }
 417 </programlisting>
 418
 419
 420 </section>
 421 </section>
 422
 423 <bibliography xml:id="using.exceptions.biblio"><info><title>Bibliography</title></info>
 424
 425
 426   <biblioentry>
 427       <title>
 428         <link xmlns:xlink="http://www.w3.org/1999/xlink"
 429               xlink:href="http://www.opengroup.org/austin/">
 430         System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008)
 431         </link>
 432       </title>
 433
 434
 435     <pagenums>
 436       2.9.5 Thread Cancellation
 437     </pagenums>
 438     <copyright>
 439       <year>2008</year>
 440       <holder>
 441         The Open Group/The Institute of Electrical and Electronics
 442         Engineers, Inc.
 443       </holder>
 444     </copyright>
 445   </biblioentry>
 446
 447   <biblioentry>
 448       <title>
 449         <link xmlns:xlink="http://www.w3.org/1999/xlink"
 450               xlink:href="http://www.boost.org/community/error_handling.html">
 451         Error and Exception Handling
 452         </link>
 453       </title>
 454
 455     <author><personname><firstname>David</firstname><surname>Abrahams </surname></personname></author>
 456     <publisher>
 457       <publishername>
 458         Boost
 459       </publishername>
 460     </publisher>
 461   </biblioentry>
 462
 463
 464   <biblioentry>
 465       <title>
 466         <link xmlns:xlink="http://www.w3.org/1999/xlink"
 467               xlink:href="http://www.boost.org/community/exception_safety.html">
 468         Exception-Safety in Generic Components
 469         </link>
 470       </title>
 471
 472     <author><personname><firstname>David</firstname><surname>Abrahams</surname></personname></author>
 473     <publisher>
 474       <publishername>
 475         Boost
 476       </publishername>
 477     </publisher>
 478   </biblioentry>
 479
 480   <biblioentry>
 481       <title>
 482         <link xmlns:xlink="http://www.w3.org/1999/xlink"
 483               xlink:href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/1997/N1077.pdf">
 484         Standard Library Exception Policy
 485         </link>
 486       </title>
 487
 488     <author><personname><firstname>Matt</firstname><surname>Austern</surname></personname></author>
 489     <publisher>
 490       <publishername>
 491         WG21 N1077
 492       </publishername>
 493     </publisher>
 494   </biblioentry>
 495
 496   <biblioentry>
 497       <title>
 498         <link xmlns:xlink="http://www.w3.org/1999/xlink"
 499               xlink:href="http://gcc.gnu.org/ml/gcc-patches/2001-03/msg00661.html">
 500         ia64 c++ abi exception handling
 501         </link>
 502       </title>
 503
 504     <author><personname><firstname>Richard</firstname><surname>Henderson</surname></personname></author>
 505     <publisher>
 506       <publishername>
 507         GNU
 508       </publishername>
 509     </publisher>
 510   </biblioentry>
 511
 512   <biblioentry>
 513       <title>
 514         <link xmlns:xlink="http://www.w3.org/1999/xlink"
 515               xlink:href="http://www.research.att.com/~bs/3rd_safe.pdf">
 516         Appendix E: Standard-Library Exception Safety
 517         </link>
 518       </title>
 519     <author><personname><firstname>Bjarne</firstname><surname>Stroustrup</surname></personname></author>
 520   </biblioentry>
 521
 522   <biblioentry>
 523     <citetitle>
 524       Exceptional C++
 525     </citetitle>
 526     <pagenums>
 527       Exception-Safety Issues and Techniques
 528     </pagenums>
 529     <author><personname><firstname>Herb</firstname><surname>Sutter</surname></personname></author>
 530   </biblioentry>
 531
 532   <biblioentry>
 533       <title>
 534         <link xmlns:xlink="http://www.w3.org/1999/xlink"
 535               xlink:href="http://gcc.gnu.org/PR25191">
 536       GCC Bug 25191: exception_defines.h #defines try/catch
 537         </link>
 538       </title>
 539   </biblioentry>
 540
 541 </bibliography>
 542
 543 </section>