2009-10-14 Benjamin Kosnik * doc/xml/authors.xml: Update. * doc/xml/manual/intro.xml: Move test section... * doc/xml/manual/appendix_porting.xml: ...here. * doc/xml/manual/diagnostics.xml: Edit. * doc/xml/manual/using.xml: Break out exception section. * doc/xml/manual/using_exceptions.xml: New. * doc/html: Regenerate. Index: doc/xml/authors.xml =================================================================== --- doc/xml/authors.xml (revision 152794) +++ doc/xml/authors.xml (working copy) @@ -74,7 +74,7 @@ Allocators, ABI, API evolution and deprecation history, Backwards Compatibility, Thread, Debug Support, Locales, Facets, Parallel Mode, Headers, Namespaces, Construction and - Structure, DocBook conversion and layout. + Structure, Using Exceptions, DocBook conversion and layout. @@ -148,6 +148,17 @@ + Silvius + Rus + + + + Profile mode + + + + + Johannes Singler Index: doc/xml/manual/intro.xml =================================================================== --- doc/xml/manual/intro.xml (revision 152794) +++ doc/xml/manual/intro.xml (working copy) @@ -870,13 +870,8 @@ - - - - Index: doc/xml/manual/appendix_porting.xml =================================================================== --- doc/xml/manual/appendix_porting.xml (revision 152794) +++ doc/xml/manual/appendix_porting.xml (working copy) @@ -35,6 +35,11 @@ parse="xml" href="internals.xml"> + + + + Index: doc/xml/manual/using.xml =================================================================== --- doc/xml/manual/using.xml (revision 152794) +++ doc/xml/manual/using.xml (working copy) @@ -1290,33 +1290,13 @@ - + - - - Exceptions + + + - - - Propagating Exceptions aka Exception Neutrality - - - - - - Exception Safety - - - - - - Support for <literal>-fno-exceptions</literal> - - - - - - Index: doc/xml/manual/using_exceptions.xml =================================================================== --- doc/xml/manual/using_exceptions.xml (revision 0) +++ doc/xml/manual/using_exceptions.xml (revision 0) @@ -0,0 +1,579 @@ + + + + + + + C++ + + + exception + + + error + + + exception neutrality + + + exception safety + + + exception propagation + + + -fno-exceptions + + + + +Exceptions + + +The C++ language provides language support for stack unwinding +with try and catch blocks and +the throw keyword. + + + +These are very powerful constructs, and require some thought when +applied to the standard library in order to yield components that work +efficiently while cleaning up resources when unexpectedly killed via +exceptional circumstances. + + + +Two general topics of discussion follow: +exception neutrality and exception safety. + + + + +Exception Safety + + + What is exception-safe code? + + + + Will define this as reasonable and well-defined behavior by classes + and functions from the standard library when used by user-defined + classes and functions that are themselves exception safe. + + + + Please note that using exceptions in combination with templates + imposes an additional requirement for exception + safety. Instantiating types are required to have destructors that + do no throw. + + + + Using the layered approach from Abrahams, can classify library + components as providing set levels of safety. These will be called + exception guarantees, and can be divided into three categories. + + + + + + + One. Don't throw. + + + As specified in 23.2.1 general container requirements. Applicable + to container and string classes. + + + Member + functions erase, pop_back, pop_front, swap, clear. And iterator + copy constructor and assignment operator. + + + + + + Two. Don't leak resources when exceptions are thrown. This is + also referred to as the basic exception safety guarantee. + + + + This applicable throughout the standard library. + + + + + + Three. Commit-or-rollback semantics. This is + referred to as strong exception safety guarantee. + + + + As specified in 23.2.1 general container requirements. Applicable + to container and string classes. + + + Member functions insert of a single + element, push_back, push_front, + and rehash. + + + + + + + + + +Exception Neutrality + + Simply put, once thrown an exception object should continue in + flight unless handled explicitly. In practice, this means + propagating exceptions should not be swallowed in + gratuitous catch(...) blocks. Instead, + matching try and catch + blocks should have specific catch handlers and allow un-handed + exception objects to propagate. If a + terminating catch(...) blocks exist then it + should end with a throw to re-throw the current + exception. + + + + Why do this? + + + + By allowing exception objects to propagate, a more flexible + approach to error handling is made possible (although not + required.) Instead of dealing with an error immediately, one can + allow the exception to propagate up until sufficient context is + available and the choice of exiting or retrying can be made in an + informed manner. + + + + Unfortunately, this tends to be more of a guideline than a strict + rule as applied to the standard library. As such, the following is + a list of known problem areas where exceptions are not propagated. + + + + + + Input/Output + + + The destructor ios_base::Init::~Init() + swallows all exceptions from flush called on + all open streams at termination. + + + + All formatted input in basic_istream or + formatted output in basic_ostream can be + configured to swallow exceptions + when exceptions is set to + ignore ios_base::badbit. + + + + Functions that have been registered + with ios_base::register_callback swallow all + exceptions when called as part of a callback event. + + + + When closing the underlying + file, basic_filebuf::close will swallow + (non-cancellation) exceptions thrown and return NULL. + + + + + Thread + + + The constructors of thread that take a + callable function argument swallow all exceptions resulting from + executing the function argument. + + + + + + + +Doing without + + C++ is a language that strives to be as efficient as is possible + in delivering features. As such, considerable care is used by both + language implementer and designers to make sure unused features + not impose hidden or unexpected costs. The GNU system tries to be + as flexible and as configurable as possible. So, it should come as + no surprise that GNU C++ provides an optional language extension, + spelled -fno-exceptions, as a way to excise the + implicitly generated magic necessary to + support try and catch blocks + and thrown objects. (Language support + for -fno-exceptions is documented in the GNU + GCC manual.) + + + Before detailing the library support + for -fno-exceptions, first a passing note on + the things lost when this flag is used: it will break exceptions + trying to pass through code compiled + with -fno-exceptions whether or not that code + has any try or catch + constructs. If you might have some code that throws, you shouldn't + use -fno-exceptions. If you have some code that + uses try or catch, you + shouldn't use -fno-exceptions. + + + + And what it to be gained, tinkering in the back alleys with a + language like this? Exception handling overhead can be measured + in the size of the executable binary, and varies with the + capabilities of the underlying operating system and specific + configuration of the C++ compiler. On recent hardware with GNU + system software of the same age, the combined code and data size + overhead for enabling exception handling is around 7%. Of course, + if code size is of singular concern than using the appropriate + optimizer setting with exception handling enabled + (ie, -Os -fexceptions) may save up to twice + that, and preserve error checking. + + + + So. Hell bent, we race down the slippery track, knowing the brakes + are a little soft and that the right front wheel has a tendency to + wobble at speed. Go on: detail the standard library support + for -fno-exceptions. + + + + In sum, valid C++ code with exception handling is transformed into + a dialect without exception handling. In detailed steps: all use + of the C++ + keywords try, catch, + and throw in the standard library have been + permanently replaced with the pre-processor controlled equivalents + spelled __try, __catch, + and __throw_exception_again. They are defined + as follows. + + + +#ifdef __EXCEPTIONS +# define __try try +# define __catch(X) catch(X) +# define __throw_exception_again throw +#else +# define __try if (true) +# define __catch(X) if (false) +# define __throw_exception_again +#endif + + + + In addition, for every object derived from + class exception, there exists a corresponding + function with C language linkage. An example: + + + +#ifdef __EXCEPTIONS + void __throw_bad_exception(void) + { throw bad_exception(); } +#else + void __throw_bad_exception(void) + { abort(); } +#endif + + + + The last language feature needing to be transformed + by -fno-exceptions is treatment of exception + specifications on member functions. Fortunately, the compiler deals + with this by ignoring exception specifications and so no alternate + source markup is needed. + + + + By using this combination of language re-specification by the + compiler, and the pre-processor tricks and the functional + indirection layer for thrown exception objects by the library, + libstdc++ files can be compiled + with -fno-exceptions. + + + + User code that uses C++ keywords + like throw, try, + and catch will produce errors even if the user + code has included libstdc++ headers and is using constructs + like basic_iostream. Even though the standard + library has been transformed, user code may need modification. User + code that attempts or expects to do error checking on standard + library components compiled with exception handling disabled should + be evaluated and potentially made conditional. + + + + Some issues remain with this approach (see bugzilla entry + 25191). Code paths are not equivalent, in + particular catch blocks are not evaluated. Also + problematic are throw expressions expecting a + user-defined throw handler. Known problem areas in the standard + library include using an instance + of basic_istream + with exceptions set to specific + ios_base::iostate conditions, or + cascading catch blocks that dispatch error + handling or recovery efforts based on the type of exception object + thrown. + + + + Oh, and by the way: none of this hackery is at all + special. (Although perhaps well-deserving of a raised eyebrow.) + Support continues to evolve and may change in the future. Similar + and even additional techniques are used in other C++ libraries and + compilers. + + + + C++ hackers with a bent for language and control-flow purity have + been successfully consoled by grizzled C veterans lamenting the + substitution of the C language keyword + const with the uglified + doppelganger __const. + + + + + + +Compatibility + + +With <literal>C</literal> + + C language code that is expecting to interoperate with C++ should be + compiled with -fexceptions. This will make + debugging a C language function called as part of C++-induced stack + unwinding possible. + + + + In particular, unwinding into a frame with no exception handling +data will cause a runtime abort. If the unwinder runs out of unwind +info before it finds a handler, std::terminate() +is called. + + + + Please note that most development environments should take care of + getting these details right. For GNU systems, all appropriate parts + of the GNU C library are already compiled + with -fexceptions. + + + + + +With <literal>POSIX</literal> thread cancellation + + + GNU systems re-use some of the exception handling mechanisms to + track control flow for POSIX thread cancellation. + + + + Cancellation points are functions defined by POSIX as worthy of + special treatment. The standard library may use some of these + functions to implement parts of the ISO C++ standard or depend on + them for extensions. + + + + Of note: + + + + nanosleep, + read, write, open, close, + and wait. + + + + The parts of libstdc++ that use C library functions marked as + cancellation points should take pains to be exception neutral. + Failing this, catch blocks have been augmented to + show that the POSIX cancellation object is in flight. + + + + This augmentation adds a catch block + for __cxxabiv1::__forced_unwind, which is the + object representing the POSIX cancellation object. Like so: + + + + catch(const __cxxabiv1::__forced_unwind&) + { + this->_M_setstate(ios_base::badbit); + throw; + } + catch(...) + { this->_M_setstate(ios_base::badbit); } + + + + + + + +Bibliography + + + + System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008) + + + 2.9.5 Thread Cancellation + + + + 2008 + + The Open Group/The Institute of Electrical and Electronics Engineers, Inc. + + + + + + + + + + + + Error and Exception Handling + + + David + Abrahams + + + + Boost + + + + + + + + + + + + Exception-Safety in Generic Components + + + David + Abrahams + + + + Boost + + + + + + + + + + + Standard Library Exception Policy + + + Matt + Austern + + + + WG21 N1077 + + + + + + + + + + + ia64 c++ abi exception handling + + + Richard + Henderson + + + + GNU + + + + + + + + + + + Appendix E: Standard-Library Exception Safety + + + Bjarne + Stroustrup + + + + + + + + + + Exceptional C++ + + + Exception-Safety Issues and Techniques + + + Herb + Sutter + + + + + + exception_defines.h #defines try/catch + + + GCC Bug 25191 + + + + + + + + Index: doc/xml/manual/diagnostics.xml =================================================================== --- doc/xml/manual/diagnostics.xml (revision 152794) +++ doc/xml/manual/diagnostics.xml (working copy) @@ -71,11 +71,6 @@ - - Cancellation - - -