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 <jwak...@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 <thread>, <future>,
- <mutex>, or <condition_variable>.</entry>
+ <entry>For ISO C++11
+ <filename class="headerfile"><thread></filename>,
+ <filename class="headerfile"><future></filename>,
+ <filename class="headerfile"><mutex></filename>,
+ or <filename class="headerfile"><condition_variable></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"><atomic></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 <ios>. Most of these macros
- should not be used by consumers of libstdc++, and are reserved
+ the public libstdc++ API, like
+ <filename class="headerfile"><ios></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>
