Merged r152721 through r154039 into branch.

git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/branches/ifunc@154040 138bc75d-0d04-0410-961f-82ee72b054a4

5 files changed, 592 insertions, 39 deletions

diff --git a/libstdc++-v3/doc/xml/manual/appendix_porting.xml b/libstdc++-v3/doc/xml/manual/appendix_porting.xml
index f565c0e03d4..c44a9adeb86 100644
--- a/libstdc++-v3/doc/xml/manual/appendix_porting.xml
+++ b/libstdc++-v3/doc/xml/manual/appendix_porting.xml
@@ -35,6 +35,11 @@
 	      parse="xml" href="internals.xml">
   </xi:include>
 
+  <!-- Test -->
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
+	      parse="xml" href="test.xml">
+  </xi:include>
+
   <!-- ABI Policy and Guidelines -->
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
 	      parse="xml" href="abi.xml">
diff --git a/libstdc++-v3/doc/xml/manual/diagnostics.xml b/libstdc++-v3/doc/xml/manual/diagnostics.xml
index d76f6e8e419..097d8917695 100644
--- a/libstdc++-v3/doc/xml/manual/diagnostics.xml
+++ b/libstdc++-v3/doc/xml/manual/diagnostics.xml
@@ -71,11 +71,6 @@
    </programlisting>
 
   </sect1>  
-  <sect1 id="manual.diagnostics.exceptions.cancellation" xreflabel="Cancellation">
-    <title>Cancellation</title>
-    <para>
-    </para>
-  </sect1>  
 </chapter>
 
 <chapter id="manual.diagnostics.concept_checking" xreflabel="Concept Checking">
diff --git a/libstdc++-v3/doc/xml/manual/intro.xml b/libstdc++-v3/doc/xml/manual/intro.xml
index d4e1d12d896..33bacae60b0 100644
--- a/libstdc++-v3/doc/xml/manual/intro.xml
+++ b/libstdc++-v3/doc/xml/manual/intro.xml
@@ -195,10 +195,9 @@ requirements of the license of GCC.
       <title>Implementation Bugs</title>
     <para>
       Information on known bugs, details on efforts to fix them, and
-      fixed bugs are all available as part of the GCC bug tracking
-      system, <ulink
-      url="http://gcc.gnu.org/bugzilla">bugzilla</ulink>, with the
-      category set to <literal>libstdc++</literal>.
+      fixed bugs are all available as part of the <ulink
+      url="http://gcc.gnu.org/bugs/">GCC bug tracking system</ulink>,
+      with the category set to <literal>libstdc++</literal>.
     </para>
     </sect2>
 
@@ -870,13 +869,8 @@ started to build.
 
 </sect1>
 
-  <!-- Section 04 : Test -->
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
-	      parse="xml" href="test.xml">
-  </xi:include>
 </chapter>
 
-
 <!-- Chapter 03 : Using -->
 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 	    parse="xml" href="using.xml">
diff --git a/libstdc++-v3/doc/xml/manual/using.xml b/libstdc++-v3/doc/xml/manual/using.xml
index bf25bb766ac..d9ff8cadef4 100644
--- a/libstdc++-v3/doc/xml/manual/using.xml
+++ b/libstdc++-v3/doc/xml/manual/using.xml
@@ -1290,32 +1290,12 @@ gcc version 4.1.2 20070925 (Red Hat 4.1.2-33)
    </para> 
 
     </sect2>
-  </sect1>
-
-  <sect1 id="manual.intro.using.exception" xreflabel="Exceptions">
-    <?dbhtml filename="using_exceptions.html"?>
-    <title>Exceptions</title>
-
-  <sect2 id="intro.using.exception.propagating" xreflabel="Propagating Exceptions">
-
-    <title>Propagating Exceptions aka Exception Neutrality</title>
-  <para> 
-  </para>
-  </sect2>
-
-  <sect2 id="intro.using.exception.safety" xreflabel="Exception Safety">
-    <title>Exception Safety</title>
-  <para> 
-  </para>
-  </sect2>
-
-  <sect2 id="intro.using.exception.no" xreflabel="-fno-exceptions">
-    <title>Support for <literal>-fno-exceptions</literal></title>
-  <para> 
-  </para>
-  </sect2>
+</sect1>
 
-  </sect1>  
+<!-- Section 0x : Exception policies, expectations, topics -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
+	    parse="xml" href="using_exceptions.xml">
+</xi:include>
 
 <!-- Section 0x : Debug -->
 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
diff --git a/libstdc++-v3/doc/xml/manual/using_exceptions.xml b/libstdc++-v3/doc/xml/manual/using_exceptions.xml
new file mode 100644
index 00000000000..09c21d41ccc
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/using_exceptions.xml
@@ -0,0 +1,579 @@
+<sect1 id="manual.intro.using.exceptions" xreflabel="Using Exceptions">
+<?dbhtml filename="using_exceptions.html"?>
+
+<sect1info>
+  <keywordset>
+    <keyword>
+      C++
+    </keyword>
+    <keyword>
+      exception
+    </keyword>
+    <keyword>
+      error
+    </keyword>
+    <keyword>
+      exception neutrality
+    </keyword>
+    <keyword>
+      exception safety
+    </keyword>
+    <keyword>
+      exception propagation
+    </keyword>
+    <keyword>
+      -fno-exceptions
+    </keyword>
+  </keywordset>
+</sect1info>
+
+<title>Exceptions</title>
+
+<para>
+The C++ language provides language support for stack unwinding
+with <literal>try</literal> and <literal>catch</literal> blocks and
+the <literal>throw</literal> keyword.
+</para>
+
+<para>
+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. 
+</para>
+
+<para>
+Two general topics of discussion follow:
+exception neutrality and exception safety.
+</para>
+
+
+<sect2 id="intro.using.exception.safety" xreflabel="Exception Safety">
+<title>Exception Safety</title>
+
+  <para> 
+    What is exception-safe code? 
+  </para>
+
+  <para>
+    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.
+  </para>
+
+  <para>
+    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.
+  </para>
+
+  <para>
+    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.
+  </para>
+
+<itemizedlist>
+
+  <listitem>
+  <para>
+    One. Don't throw.
+  </para>
+  <para>
+    As specified in 23.2.1 general container requirements. Applicable
+    to container and string classes.
+  </para>
+  <para>
+    Member
+    functions <function>erase</function>, <function>pop_back</function>, <function>pop_front</function>, <function>swap</function>, <function>clear</function>. And <type>iterator</type>
+    copy constructor and assignment operator.
+  </para>
+  </listitem>
+
+  <listitem>
+  <para>
+    Two. Don't leak resources when exceptions are thrown. This is
+    also referred to as the <quote>basic</quote> exception safety guarantee.
+  </para>
+
+  <para>
+    This applicable throughout the standard library.
+  </para>
+  </listitem>
+
+  <listitem>
+  <para>
+    Three. Commit-or-rollback semantics.  This is
+    referred to as <quote>strong</quote> exception safety guarantee.
+  </para>
+
+  <para>
+    As specified in 23.2.1 general container requirements. Applicable
+    to container and string classes.
+  </para>
+  <para>
+    Member functions <function>insert</function> of a single
+    element, <function>push_back</function>, <function>push_front</function>,
+    and <function>rehash</function>.
+  </para>
+
+  </listitem>
+</itemizedlist>
+
+</sect2>
+
+
+<sect2 id="intro.using.exception.propagating" xreflabel="Exceptions Neutrality">
+<title>Exception Neutrality</title>
+  <para>
+    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 <literal>catch(...)</literal> blocks. Instead,
+    matching <literal>try</literal> and <literal>catch</literal>
+    blocks should have specific catch handlers and allow un-handed
+    exception objects to propagate. If a
+    terminating <literal>catch(...)</literal> blocks exist then it
+    should end with a <literal>throw</literal> to re-throw the current
+    exception.
+  </para>
+
+  <para>
+    Why do this?
+  </para>
+
+  <para>
+    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.
+  </para>
+
+  <para>
+    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.
+  </para>
+
+<itemizedlist>
+  <listitem>
+    <para>
+      Input/Output
+    </para>
+  <para>
+    The destructor <function>ios_base::Init::~Init()</function>
+    swallows all exceptions from <function>flush</function> called on
+    all open streams at termination.
+  </para>
+
+  <para>
+    All formatted input in <classname>basic_istream</classname> or
+    formatted output in <classname>basic_ostream</classname> can be
+    configured to swallow exceptions
+    when <function>exceptions</function> is set to
+    ignore <type>ios_base::badbit</type>.
+  </para>
+
+  <para>
+    Functions that have been registered
+    with <function>ios_base::register_callback</function> swallow all
+    exceptions when called as part of a callback event.
+  </para>
+
+  <para>
+    When closing the underlying
+    file, <function>basic_filebuf::close</function> will swallow
+    (non-cancellation) exceptions thrown and return <literal>NULL</literal>.
+  </para>
+  </listitem>
+  <listitem>
+    <para>
+      Thread
+    </para>
+    <para>
+      The constructors of <classname>thread</classname> that take a
+      callable function argument swallow all exceptions resulting from
+      executing the function argument.
+    </para>
+  </listitem>
+</itemizedlist>
+
+</sect2>
+
+<sect2 id="intro.using.exception.no" xreflabel="-fno-exceptions">
+<title>Doing without</title>
+  <para>
+    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 <literal>-fno-exceptions</literal>, as a way to excise the
+    implicitly generated magic necessary to
+    support <literal>try</literal> and <literal>catch</literal> blocks
+    and thrown objects. (Language support
+    for <literal>-fno-exceptions</literal> is documented in the GNU
+    GCC <ulink url="http://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#Code-Gen-Options">manual</ulink>.)
+  </para>
+
+  <para>Before detailing the library support
+    for <literal>-fno-exceptions</literal>, first a passing note on
+    the things lost when this flag is used: it will break exceptions
+    trying to pass through code compiled
+    with <literal>-fno-exceptions</literal> whether or not that code
+    has any <literal>try</literal> or <literal>catch</literal>
+    constructs. If you might have some code that throws, you shouldn't
+    use <literal>-fno-exceptions</literal>. If you have some code that
+    uses <literal>try</literal> or <literal>catch</literal>, you
+    shouldn't use <literal>-fno-exceptions</literal>.
+  </para> 
+
+  <para> 
+    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, <literal>-Os -fexceptions</literal>) may save up to twice
+    that, and preserve error checking.
+  </para>
+
+  <para>
+    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 <literal>-fno-exceptions</literal>.
+  </para>
+
+  <para>
+    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 <literal>try</literal>, <literal>catch</literal>,
+    and <literal>throw</literal> in the standard library have been
+    permanently replaced with the pre-processor controlled equivalents
+    spelled <literal>__try</literal>, <literal>__catch</literal>,
+    and <literal>__throw_exception_again</literal>. They are defined
+    as follows.
+  </para>
+
+<programlisting>
+#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
+</programlisting>
+
+<para>
+  In addition, for every object derived from
+  class <classname>exception</classname>, there exists a corresponding
+  function with C language linkage. An example:
+</para>
+
+<programlisting>
+#ifdef __EXCEPTIONS
+  void __throw_bad_exception(void)
+  { throw bad_exception(); }
+#else
+  void __throw_bad_exception(void)
+  { abort(); }
+#endif
+</programlisting>
+
+<para>
+  The last language feature needing to be transformed
+  by <literal>-fno-exceptions</literal> 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.
+</para>
+
+<para>
+  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 <literal>-fno-exceptions</literal>.
+</para>
+
+<para>
+ User code that uses C++ keywords
+ like <literal>throw</literal>, <literal>try</literal>,
+ and <literal>catch</literal> will produce errors even if the user
+ code has included libstdc++ headers and is using constructs
+ like <classname>basic_iostream</classname>. 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. 
+</para>
+
+<para>
+  Some issues remain with this approach (see bugzilla entry
+  25191). Code paths are not equivalent, in
+  particular <literal>catch</literal> blocks are not evaluated. Also
+  problematic are <literal>throw</literal> expressions expecting a
+  user-defined throw handler. Known problem areas in the standard
+  library include using an instance
+  of <classname>basic_istream</classname>
+  with <function>exceptions</function> set to specific
+  <type>ios_base::iostate</type> conditions, or
+  cascading <literal>catch</literal> blocks that dispatch error
+  handling or recovery efforts based on the type of exception object
+  thrown.
+</para>
+
+<para>
+  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.
+</para>
+
+<para>
+ 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
+  <literal>const</literal> with the uglified
+  doppelganger <literal>__const</literal>.
+</para>
+
+
+</sect2>
+
+<sect2 id="intro.using.exception.compat">
+<title>Compatibility</title>
+
+<sect3 id="using.exception.compat.c">
+<title>With <literal>C</literal></title>
+<para> 
+  C language code that is expecting to interoperate with C++ should be
+  compiled with <literal>-fexceptions</literal>. This will make
+  debugging a C language function called as part of C++-induced stack
+  unwinding possible.
+</para>
+
+<para>
+  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, <function>std::terminate()</function>
+is called.
+</para>
+
+<para>
+  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 <literal>-fexceptions</literal>.
+</para>
+
+</sect3>
+
+<sect3 id="using.exception.compat.posix">
+<title>With <literal>POSIX</literal> thread cancellation</title>
+
+<para> 
+  GNU systems re-use some of the exception handling mechanisms to
+  track control flow for <literal>POSIX</literal> thread cancellation.
+</para>
+
+<para>
+  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.
+</para>
+
+<para>
+  Of note:
+</para>
+
+<para>
+  <function>nanosleep</function>,
+  <function>read</function>, <function>write</function>, <function>open</function>, <function>close</function>,
+  and <function>wait</function>.
+</para>
+
+<para>
+  The parts of libstdc++ that use C library functions marked as
+  cancellation points should take pains to be exception neutral.
+  Failing this, <literal>catch</literal> blocks have been augmented to
+  show that the POSIX cancellation object is in flight.
+</para>
+
+<para>
+  This augmentation adds a <literal>catch</literal> block
+  for <classname>__cxxabiv1::__forced_unwind</classname>, which is the
+  object representing the POSIX cancellation object. Like so:
+</para>
+
+<programlisting>
+  catch(const __cxxabiv1::__forced_unwind&amp;)
+  {
+    this->_M_setstate(ios_base::badbit);
+    throw;
+  }
+  catch(...)
+  { this->_M_setstate(ios_base::badbit); }
+</programlisting>
+
+
+</sect3>
+</sect2>
+
+<bibliography id="using.exceptions.biblio">
+<title>Bibliography</title>
+
+  <biblioentry>
+    <title>
+      System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008)
+    </title>
+    <pagenums>
+      2.9.5 Thread Cancellation
+    </pagenums>
+
+    <copyright>
+      <year>2008</year>
+      <holder>
+      The Open Group/The Institute of Electrical and Electronics Engineers, Inc.</holder>
+    </copyright>
+
+    <biblioid>
+      <ulink url="http://www.opengroup.org/austin/">
+      </ulink>
+    </biblioid>
+
+  </biblioentry> 
+
+  <biblioentry>
+    <title>
+      Error and Exception Handling
+    </title>
+    <author>
+      <firstname>David</firstname>
+      <surname>Abrahams </surname>
+    </author>
+    <publisher>
+      <publishername>
+	Boost
+      </publishername>
+    </publisher>
+    <biblioid>
+      <ulink url="http://www.boost.org/community/error_handling.html">
+      </ulink>
+    </biblioid>
+  </biblioentry> 
+
+
+  <biblioentry>
+    <title>
+      Exception-Safety in Generic Components
+    </title>
+    <author>
+      <firstname>David</firstname>
+      <surname>Abrahams</surname>
+    </author>
+    <publisher>
+      <publishername>
+	Boost
+      </publishername>
+    </publisher>
+    <biblioid>
+      <ulink url="http://www.boost.org/community/exception_safety.html">
+      </ulink>
+    </biblioid>
+  </biblioentry> 
+
+  <biblioentry>
+    <title>
+      Standard Library Exception Policy
+    </title>
+    <author>
+      <firstname>Matt</firstname>
+      <surname>Austern</surname>
+    </author>
+    <publisher>
+      <publishername>
+	WG21 N1077
+      </publishername>
+    </publisher>
+    <biblioid>
+      <ulink url="www.open-std.org/jtc1/sc22/wg21/docs/papers/1997/N1077.pdf">
+      </ulink>
+    </biblioid>
+  </biblioentry> 
+
+  <biblioentry>
+    <title>
+      ia64 c++ abi exception handling
+    </title>
+    <author>
+      <firstname>Richard</firstname>
+      <surname>Henderson</surname>
+    </author>
+    <publisher>
+      <publishername>
+	GNU
+      </publishername>
+    </publisher>
+    <biblioid>
+      <ulink url="http://gcc.gnu.org/ml/gcc-patches/2001-03/msg00661.html">
+      </ulink>
+    </biblioid>
+  </biblioentry> 
+
+  <biblioentry>
+    <title>
+      Appendix E: Standard-Library Exception Safety
+    </title>
+    <author>
+      <firstname>Bjarne</firstname>
+      <surname>Stroustrup</surname>
+    </author>
+    <biblioid>
+      <ulink url="http://www.research.att.com/~bs/3rd_safe.pdf">
+      </ulink>
+    </biblioid>
+  </biblioentry> 
+
+  <biblioentry>
+    <title>
+      Exceptional C++
+    </title>
+    <pagenums>
+      Exception-Safety Issues and Techniques
+    </pagenums>
+    <author>
+      <firstname>Herb</firstname>
+      <surname>Sutter</surname>
+    </author>
+  </biblioentry> 
+
+  <biblioentry>
+    <title>
+      exception_defines.h #defines try/catch
+    </title>
+    <subtitle>
+      GCC Bug <ulink url="http://gcc.gnu.org/PR25191">25191</ulink>
+    </subtitle>
+    <biblioid>
+    </biblioid>
+  </biblioentry> 
+
+</bibliography>
+
+</sect1>