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"?>
5 <info><title>Exceptions</title>
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>
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.
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.
31 Two general topics of discussion follow:
32 exception neutrality and exception safety.
36 <section xml:id="intro.using.exception.safety" xreflabel="Exception Safety"><info><title>Exception Safety</title></info>
40 What is exception-safe code?
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.
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
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.
69 As specified in 23.2.1 general container requirements. Applicable
70 to container and string classes.
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.
81 Two. Don't leak resources when exceptions are thrown. This is
82 also referred to as the <quote>basic</quote> exception safety guarantee.
86 This applicable throughout the standard library.
92 Three. Commit-or-rollback semantics. This is
93 referred to as <quote>strong</quote> exception safety guarantee.
97 As specified in 23.2.1 general container requirements. Applicable
98 to container and string classes.
101 Member functions <function>insert</function> of a single
102 element, <function>push_back</function>, <function>push_front</function>,
103 and <function>rehash</function>.
112 <section xml:id="intro.using.exception.propagating" xreflabel="Exceptions Neutrality"><info><title>Exception Neutrality</title></info>
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
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
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.
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.
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>.
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.
172 When closing the underlying
173 file, <function>basic_filebuf::close</function> will swallow
174 (non-cancellation) exceptions thrown and return <literal>NULL</literal>.
182 The constructors of <classname>thread</classname> that take a
183 callable function argument swallow all exceptions resulting from
184 executing the function argument.
191 <section xml:id="intro.using.exception.no" xreflabel="-fno-exceptions"><info><title>Doing without</title></info>
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>.)
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>.
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.
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>.
242 In sum, valid C++ code with exception handling is transformed into
243 a dialect without exception handling. In detailed steps: all use
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
256 # define __catch(X) catch(X)
257 # define __throw_exception_again throw
259 # define __try if (true)
260 # define __catch(X) if (false)
261 # define __throw_exception_again
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:
273 void __throw_bad_exception(void)
274 { throw bad_exception(); }
276 void __throw_bad_exception(void)
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.
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>.
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.
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
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
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>.
343 <section xml:id="intro.using.exception.compat"><info><title>Compatibility</title></info>
346 <section xml:id="using.exception.compat.c"><info><title>With <literal>C</literal></title></info>
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
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>
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>.
371 <section xml:id="using.exception.compat.posix"><info><title>With <literal>POSIX</literal> thread cancellation</title></info>
375 GNU systems re-use some of the exception handling mechanisms to
376 track control flow for <literal>POSIX</literal> thread cancellation.
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
391 <function>nanosleep</function>,
392 <function>read</function>, <function>write</function>, <function>open</function>, <function>close</function>,
393 and <function>wait</function>.
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.
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:
410 catch(const __cxxabiv1::__forced_unwind&)
412 this->_M_setstate(ios_base::badbit);
416 { this->_M_setstate(ios_base::badbit); }
423 <bibliography xml:id="using.exceptions.biblio"><info><title>Bibliography</title></info>
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)
436 2.9.5 Thread Cancellation
441 The Open Group/The Institute of Electrical and Electronics
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
455 <author><personname><firstname>David</firstname><surname>Abrahams </surname></personname></author>
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
472 <author><personname><firstname>David</firstname><surname>Abrahams</surname></personname></author>
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
488 <author><personname><firstname>Matt</firstname><surname>Austern</surname></personname></author>
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
504 <author><personname><firstname>Richard</firstname><surname>Henderson</surname></personname></author>
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
519 <author><personname><firstname>Bjarne</firstname><surname>Stroustrup</surname></personname></author>
527 Exception-Safety Issues and Techniques
529 <author><personname><firstname>Herb</firstname><surname>Sutter</surname></personname></author>
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