[patch] Improve libstdc++ documentation on using atomics.

[Jonathan Wakely <jwakely at redhat dot com>]

Currently we don't mention libatomic anywhere in the libstdc++ manual,
even though it might be needed for std::atomic.

This fixes that and makes a few other drive-by improvements.

Committed to trunk. This would be suitable for all active branches,
so I might backport it once the gcc-5-branch opens.


commit b86123208d25cf50b75b58a2fc7911972690b414
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Mon Apr 20 12:01:59 2015 +0100

    	* doc/xml/manual/concurrency_extensions.xml: Update documentation
    	on atomics.
    	* doc/xml/manual/using.xml: Likewise. Improve markup.
    	* doc/html/*: Regenerate.

diff --git a/libstdc++-v3/doc/xml/manual/concurrency_extensions.xml b/libstdc++-v3/doc/xml/manual/concurrency_extensions.xml
index b9bab53..cb79c20 100644
--- a/libstdc++-v3/doc/xml/manual/concurrency_extensions.xml
+++ b/libstdc++-v3/doc/xml/manual/concurrency_extensions.xml
@@ -187,7 +187,7 @@ host hardware and operating system.
 <section xml:id="manual.ext.concurrency.impl" xreflabel="Implementation"><info><title>Implementation</title></info>
   <?dbhtml filename="ext_concurrency_impl.html"?>
   
-  <section xml:id="manual.ext.concurrency.impl.atomic_fallbacks" xreflabel="Atomic F"><info><title>Using Builtin Atomic Functions</title></info>
+  <section xml:id="manual.ext.concurrency.impl.atomic_fallbacks" xreflabel="Atomic F"><info><title>Using Built-in Atomic Functions</title></info>
     
 
 <para>The functions for atomic operations described above are either
@@ -197,9 +197,21 @@ capable) or by library fallbacks.</para>
 <para>Compiler intrinsics (builtins) are always preferred.  However, as
 the compiler builtins for atomics are not universally implemented,
 using them directly is problematic, and can result in undefined
-function calls. (An example of an undefined symbol from the use
+function calls.
+</para>
+
+<para>Prior to GCC 4.7 the older <code>__sync</code> intrinsics were used.
+An example of an undefined symbol from the use
 of <code>__sync_fetch_and_add</code> on an unsupported host is a
-missing reference to <code>__sync_fetch_and_add_4</code>.)
+missing reference to <code>__sync_fetch_and_add_4</code>.
+</para>
+
+<para>Current releases use the newer <code>__atomic</code> intrinsics,
+which are implemented by library calls if the hardware doesn't support them.
+Undefined references to functions like
+<code>__atomic_is_lock_free</code> should be resolved by linking to
+<filename class="libraryfile">libatomic</filename>, which is usually
+installed alongside libstdc++.
 </para>
 
 <para>In addition, on some hosts the compiler intrinsics are enabled
diff --git a/libstdc++-v3/doc/xml/manual/using.xml b/libstdc++-v3/doc/xml/manual/using.xml
index 3256c58..f6f615e 100644
--- a/libstdc++-v3/doc/xml/manual/using.xml
+++ b/libstdc++-v3/doc/xml/manual/using.xml
@@ -6,8 +6,7 @@
   <section xml:id="manual.intro.using.flags" xreflabel="Flags"><info><title>Command Options</title></info>
     
     <para>
-      The set of features available in the GNU C++ library is shaped
-      by
+      The set of features available in the GNU C++ library is shaped by
       several <link xmlns:xlink="http://www.w3.org/1999/xlink"; xlink:href="http://gcc.gnu.org/onlinedocs/gcc-4.3.2/gcc/Invoking-GCC.html";>GCC
       Command Options</link>. Options that impact libstdc++ are
       enumerated and detailed in the table below.
@@ -64,8 +63,20 @@
 
     <row>
       <entry><literal>-pthread</literal> or <literal>-pthreads</literal></entry>
-      <entry>For ISO C++11 &lt;thread&gt;, &lt;future&gt;,
-      &lt;mutex&gt;, or &lt;condition_variable&gt;.</entry>
+      <entry>For ISO C++11
+        <filename class="headerfile">&lt;thread&gt;</filename>,
+        <filename class="headerfile">&lt;future&gt;</filename>,
+        <filename class="headerfile">&lt;mutex&gt;</filename>,
+        or <filename class="headerfile">&lt;condition_variable&gt;</filename>.
+      </entry>
+    </row>
+
+    <row>
+      <entry><literal>-latomic</literal></entry>
+      <entry>Linking to <filename class="libraryfile">libatomic</filename>
+        is required for some uses of ISO C++11
+        <filename class="headerfile">&lt;atomic&gt;</filename>.
+      </entry>
     </row>
 
     <row>
@@ -779,8 +790,9 @@ g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe
       file <filename class="headerfile">c++config.h</filename>, which
       is generated during the libstdc++ configuration and build
       process. This file is then included when needed by files part of
-      the public libstdc++ API, like &lt;ios&gt;. Most of these macros
-      should not be used by consumers of libstdc++, and are reserved
+      the public libstdc++ API, like
+      <filename class="headerfile">&lt;ios&gt;</filename>. Most of these
+      macros should not be used by consumers of libstdc++, and are reserved
       for internal implementation use. <emphasis>These macros cannot
       be redefined</emphasis>.
    </para>
@@ -800,10 +812,10 @@ g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe
       <term><code>__GLIBCXX__</code></term>
       <listitem>
 	<para>The current version of
-    libstdc++ in compressed ISO date format, form of an unsigned
+    libstdc++ in compressed ISO date format, as an unsigned
     long. For details on the value of this particular macro for a
-    particular release, please consult this <link linkend="appendix.porting.abi">
-    document</link>.
+    particular release, please consult the <link linkend="appendix.porting.abi">
+    ABI Policy and Guidelines</link> appendix.
     </para>
     </listitem>
     </varlistentry>
@@ -816,14 +828,15 @@ g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe
    <para><quote>Configurable</quote> (or <quote>Not configurable</quote>) means
       that the symbol is initially chosen (or not) based on
       --enable/--disable options at library build and configure time
-      (documented <link linkend="manual.intro.setup.configure">here</link>), with the
-      various --enable/--disable choices being translated to
+      (documented in
+      <link linkend="manual.intro.setup.configure">Configure</link>),
+      with the various --enable/--disable choices being translated to
       #define/#undef).
    </para>
 
    <para> <acronym>ABI</acronym> means that changing from the default value may
-  mean changing the <acronym>ABI</acronym> of compiled code. In other words, these
-  choices control code which has already been compiled (i.e., in a
+  mean changing the <acronym>ABI</acronym> of compiled code. In other words,
+  these choices control code which has already been compiled (i.e., in a
   binary such as libstdc++.a/.so).  If you explicitly #define or
   #undef these macros, the <emphasis>headers</emphasis> may see different code
   paths, but the <emphasis>libraries</emphasis> which you link against will not.
@@ -854,7 +867,8 @@ g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe
 	<code>--enable-concept-checks</code>.  When defined, performs
 	compile-time checking on certain template instantiations to
 	detect violations of the requirements of the standard.  This
-	is described in more detail <link linkend="manual.ext.compile_checks">here</link>.
+	is described in more detail in
+	<link linkend="manual.ext.compile_checks">Compile Time Checks</link>.
       </para>
     </listitem></varlistentry>
 
@@ -862,31 +876,31 @@ g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe
     <listitem>
       <para>
 	Undefined by default. When defined, compiles user code using
-    the <link linkend="manual.ext.debug_mode">debug mode</link>.
+	the <link linkend="manual.ext.debug_mode">debug mode</link>.
       </para>
     </listitem></varlistentry>
     <varlistentry><term><code>_GLIBCXX_DEBUG_PEDANTIC</code></term>
     <listitem>
       <para>
 	Undefined by default. When defined while compiling with
-    the <link linkend="manual.ext.debug_mode">debug mode</link>, makes
-    the debug mode extremely picky by making the use of libstdc++
-    extensions and libstdc++-specific behavior into errors.
+	the <link linkend="manual.ext.debug_mode">debug mode</link>, makes
+	the debug mode extremely picky by making the use of libstdc++
+	extensions and libstdc++-specific behavior into errors.
       </para>
     </listitem></varlistentry>
     <varlistentry><term><code>_GLIBCXX_PARALLEL</code></term>
     <listitem>
       <para>Undefined by default. When defined, compiles user code
-    using the <link linkend="manual.ext.parallel_mode">parallel
-    mode</link>.
+	using the <link linkend="manual.ext.parallel_mode">parallel
+	mode</link>.
       </para>
     </listitem></varlistentry>
 
     <varlistentry><term><code>_GLIBCXX_PROFILE</code></term>
     <listitem>
       <para>Undefined by default. When defined, compiles user code
-    using the <link linkend="manual.ext.profile_mode">profile
-    mode</link>.
+	using the <link linkend="manual.ext.profile_mode">profile
+	mode</link>.
       </para>
     </listitem></varlistentry>
     </variablelist>
@@ -1248,13 +1262,16 @@ A quick read of the relevant part of the GCC
       all required macros to a compilation (if any such flags are
       required then you must provide the flag for all compilations not
       just linking) and link-library additions and/or replacements at
-      link time.  The documentation is weak.  Here is a quick summary
-      to display how ad hoc this is: On Solaris, both -pthreads and
-      -threads (with subtly different meanings) are honored.  
-      On GNU/Linux x86, -pthread is honored.  On FreeBSD,
-      -pthread is honored.  Some other ports use other switches.
-      AFAIK, none of this is properly documented anywhere other than
-      in ``gcc -dumpspecs'' (look at lib and cpp entries).
+      link time.  The documentation is weak.  On several targets (including
+      GNU/Linux, Solaris and various BSDs) -pthread is honored.
+      Some other ports use other switches.
+      This is not well documented anywhere other than
+      in "gcc -dumpspecs" (look at the 'lib' and 'cpp' entries).
+   </para>
+
+   <para>
+     Some uses of <classname>std::atomic</classname> also require linking
+     to <filename class="libraryfile">libatomic</filename>.
    </para>
 
     </section>
@@ -1305,14 +1322,19 @@ gcc version 4.1.2 20070925 (Red Hat 4.1.2-33)
 	 Requisite command-line flags are used for atomic operations
 	 and threading. Examples of this include <code>-pthread</code>
 	 and <code>-march=native</code>, although specifics vary
-	 depending on the host environment. See <link xmlns:xlink="http://www.w3.org/1999/xlink"; xlink:href="http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html";>Machine
+	 depending on the host environment. See
+	 <link linkend="manual.intro.using.flags">Command Options</link> and
+	 <link xmlns:xlink="http://www.w3.org/1999/xlink"; xlink:href="http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html";>Machine
 	 Dependent Options</link>.
        </para>
        </listitem>
        <listitem>
 	 <para>
-	   An implementation of atomicity.h functions
-	   exists for the architecture in question. See the internals documentation for more <link linkend="internals.thread_safety">details</link>.
+	   An implementation of the
+	   <filename class="headerfile">atomicity.h</filename> functions
+	   exists for the architecture in question. See the
+	   <link linkend="internals.thread_safety">internals
+	   documentation</link> for more details.
        </para>
        </listitem>