From 9adc2d48acdadae96a52dc2ffc58c881fc4af6dc Mon Sep 17 00:00:00 2001 From: Jonathan Wakely Date: Mon, 20 Apr 2015 12:07:50 +0100 Subject: [PATCH] concurrency_extensions.xml: Update documentation on atomics. * doc/xml/manual/concurrency_extensions.xml: Update documentation on atomics. * doc/xml/manual/using.xml: Likewise. Improve markup. * doc/html/*: Regenerate. From-SVN: r222230 --- libstdc++-v3/ChangeLog | 7 ++ libstdc++-v3/doc/html/index.html | 2 +- .../doc/html/manual/ext_concurrency.html | 2 +- .../doc/html/manual/ext_concurrency_impl.html | 14 ++- libstdc++-v3/doc/html/manual/extensions.html | 2 +- libstdc++-v3/doc/html/manual/index.html | 2 +- libstdc++-v3/doc/html/manual/using.html | 14 ++- .../doc/html/manual/using_concurrency.html | 26 +++--- .../doc/html/manual/using_macros.html | 39 +++++---- .../doc/xml/manual/concurrency_extensions.xml | 18 +++- libstdc++-v3/doc/xml/manual/using.xml | 86 ++++++++++++------- 11 files changed, 138 insertions(+), 74 deletions(-) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 22113d597da..a82dd923a76 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,10 @@ +2015-04-20 Jonathan Wakely + + * doc/xml/manual/concurrency_extensions.xml: Update documentation + on atomics. + * doc/xml/manual/using.xml: Likewise. Improve markup. + * doc/html/*: Regenerate. + 2015-04-15 Rainer Orth * scripts/extract_symvers.pl: Ignore elfdump error output. diff --git a/libstdc++-v3/doc/html/index.html b/libstdc++-v3/doc/html/index.html index 536d931ba98..feaa28c0e42 100644 --- a/libstdc++-v3/doc/html/index.html +++ b/libstdc++-v3/doc/html/index.html @@ -127,7 +127,7 @@ Text modify Up
Text modify Down -
Observations
Associative
Priority_Queue
Acknowledgments
Bibliography
23. HP/SGI Extensions
Backwards Compatibility
Deprecated
24. Utilities
25. Algorithms
26. Numerics
27. Iterators
28. Input and Output
Derived filebufs
29. Demangling
30. Concurrency
Design
Interface to Locks and Mutexes
Interface to Atomic Functions
Implementation
Using Builtin Atomic Functions
Thread Abstraction
Use
IV. +
Observations
Associative
Priority_Queue
Acknowledgments
Bibliography
23. HP/SGI Extensions
Backwards Compatibility
Deprecated
24. Utilities
25. Algorithms
26. Numerics
27. Iterators
28. Input and Output
Derived filebufs
29. Demangling
30. Concurrency
Design
Interface to Locks and Mutexes
Interface to Atomic Functions
Implementation
Using Built-in Atomic Functions
Thread Abstraction
Use
IV. Appendices
A. Contributing diff --git a/libstdc++-v3/doc/html/manual/ext_concurrency.html b/libstdc++-v3/doc/html/manual/ext_concurrency.html index ad3eac44233..688bdd06a97 100644 --- a/libstdc++-v3/doc/html/manual/ext_concurrency.html +++ b/libstdc++-v3/doc/html/manual/ext_concurrency.html @@ -2,7 +2,7 @@ Chapter 30. Concurrency
Chapter 30. Concurrency
Prev Part III.  Extensions - Next

Chapter 30. Concurrency

Table of Contents

Design
Interface to Locks and Mutexes
Interface to Atomic Functions
Implementation
Using Builtin Atomic Functions
Thread Abstraction
Use

Design

Interface to Locks and Mutexes

The file <ext/concurrence.h> + Next

Chapter 30. Concurrency

Table of Contents

Design
Interface to Locks and Mutexes
Interface to Atomic Functions
Implementation
Using Built-in Atomic Functions
Thread Abstraction
Use

Design

Interface to Locks and Mutexes

The file <ext/concurrence.h> contains all the higher-level constructs for playing with threads. In contrast to the atomics layer, the concurrence layer consists largely of types. All types are defined within namespace __gnu_cxx. diff --git a/libstdc++-v3/doc/html/manual/ext_concurrency_impl.html b/libstdc++-v3/doc/html/manual/ext_concurrency_impl.html index 84db3da9709..bb5d144e056 100644 --- a/libstdc++-v3/doc/html/manual/ext_concurrency_impl.html +++ b/libstdc++-v3/doc/html/manual/ext_concurrency_impl.html @@ -1,12 +1,20 @@ -Implementation

Implementation
Prev Chapter 30. Concurrency Next

Implementation

Using Builtin Atomic Functions

The functions for atomic operations described above are either +Implementation

Implementation
Prev Chapter 30. Concurrency Next

Implementation

Using Built-in Atomic Functions

The functions for atomic operations described above are either implemented via compiler intrinsics (if the underlying host is capable) or by library fallbacks.

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. +

Prior to GCC 4.7 the older __sync intrinsics were used. +An example of an undefined symbol from the use of __sync_fetch_and_add on an unsupported host is a -missing reference to __sync_fetch_and_add_4.) +missing reference to __sync_fetch_and_add_4. +

Current releases use the newer __atomic intrinsics, +which are implemented by library calls if the hardware doesn't support them. +Undefined references to functions like +__atomic_is_lock_free should be resolved by linking to +libatomic, which is usually +installed alongside libstdc++.

In addition, on some hosts the compiler intrinsics are enabled conditionally, via the -march command line flag. This makes usage vary depending on the target hardware and the flags used during diff --git a/libstdc++-v3/doc/html/manual/extensions.html b/libstdc++-v3/doc/html/manual/extensions.html index 435e0b383a8..ac3e1a96101 100644 --- a/libstdc++-v3/doc/html/manual/extensions.html +++ b/libstdc++-v3/doc/html/manual/extensions.html @@ -68,4 +68,4 @@ Text modify Up

Text modify Down -
Observations
Associative
Priority_Queue
Acknowledgments
Bibliography
23. HP/SGI Extensions
Backwards Compatibility
Deprecated
24. Utilities
25. Algorithms
26. Numerics
27. Iterators
28. Input and Output
Derived filebufs
29. Demangling
30. Concurrency
Design
Interface to Locks and Mutexes
Interface to Atomic Functions
Implementation
Using Builtin Atomic Functions
Thread Abstraction
Use
Prev Up Next
Interacting with C Home 
\ No newline at end of file +
Observations
Associative
Priority_Queue
Acknowledgments
Bibliography
23. HP/SGI Extensions
Backwards Compatibility
Deprecated
24. Utilities
25. Algorithms
26. Numerics
27. Iterators
28. Input and Output
Derived filebufs
29. Demangling
30. Concurrency
Design
Interface to Locks and Mutexes
Interface to Atomic Functions
Implementation
Using Built-in Atomic Functions
Thread Abstraction
Use
Prev Up Next
Interacting with C Home 
\ No newline at end of file diff --git a/libstdc++-v3/doc/html/manual/index.html b/libstdc++-v3/doc/html/manual/index.html index 7141dc5e88a..26f6233ff05 100644 --- a/libstdc++-v3/doc/html/manual/index.html +++ b/libstdc++-v3/doc/html/manual/index.html @@ -108,7 +108,7 @@ Text modify Up
Text modify Down -
Observations
Associative
Priority_Queue
Acknowledgments
Bibliography
23. HP/SGI Extensions
Backwards Compatibility
Deprecated
24. Utilities
25. Algorithms
26. Numerics
27. Iterators
28. Input and Output
Derived filebufs
29. Demangling
30. Concurrency
Design
Interface to Locks and Mutexes
Interface to Atomic Functions
Implementation
Using Builtin Atomic Functions
Thread Abstraction
Use
IV. +
Observations
Associative
Priority_Queue
Acknowledgments
Bibliography
23. HP/SGI Extensions
Backwards Compatibility
Deprecated
24. Utilities
25. Algorithms
26. Numerics
27. Iterators
28. Input and Output
Derived filebufs
29. Demangling
30. Concurrency
Design
Interface to Locks and Mutexes
Interface to Atomic Functions
Implementation
Using Built-in Atomic Functions
Thread Abstraction
Use
IV. Appendices
A. Contributing diff --git a/libstdc++-v3/doc/html/manual/using.html b/libstdc++-v3/doc/html/manual/using.html index 9c721ed3dfb..dff5192f5f2 100644 --- a/libstdc++-v3/doc/html/manual/using.html +++ b/libstdc++-v3/doc/html/manual/using.html @@ -3,12 +3,18 @@ Introduction  Next

Chapter 3. Using

Table of Contents

Command Options
Headers
Header Files
Mixing Headers
The C Headers and namespace std
Precompiled Headers
Macros
Namespaces
Available Namespaces
namespace std
Using Namespace Composition
Linking
Almost Nothing
Finding Dynamic or Shared Libraries
Concurrency
Prerequisites
Thread Safety
Atomics
IO
Structure
Defaults
Future
Alternatives
Containers
Exceptions
Exception Safety
Exception Neutrality
Doing without
Compatibility
With C
With POSIX thread cancellation
Debugging Support
Using g++
Debug Versions of Library Binary Files
Memory Leak Hunting
Data Race Hunting
Using gdb
Tracking uncaught exceptions
Debug Mode
Compile Time Checking
Profile-based Performance Analysis

Command Options

- 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 GCC Command Options. Options that impact libstdc++ are enumerated and detailed in the table below.

By default, g++ is equivalent to g++ -std=gnu++98. The standard library also defaults to this dialect. -

Table 3.1. C++ Command Options

Option FlagsDescription
-std=c++98Use the 1998 ISO C++ standard plus amendments.
-std=gnu++98As directly above, with GNU extensions.
-std=c++11Use the 2011 ISO C++ standard.
-std=gnu++11As directly above, with GNU extensions.
-fexceptionsSee exception-free dialect
-frttiAs above, but RTTI-free dialect.
-pthread or -pthreadsFor ISO C++11 <thread>, <future>, - <mutex>, or <condition_variable>.
-fopenmpFor parallel mode.

Prev Up Next
Make Home Headers
\ No newline at end of file +

Table 3.1. C++ Command Options

Option FlagsDescription
-std=c++98Use the 1998 ISO C++ standard plus amendments.
-std=gnu++98As directly above, with GNU extensions.
-std=c++11Use the 2011 ISO C++ standard.
-std=gnu++11As directly above, with GNU extensions.
-fexceptionsSee exception-free dialect
-frttiAs above, but RTTI-free dialect.
-pthread or -pthreadsFor ISO C++11 + <thread>, + <future>, + <mutex>, + or <condition_variable>. +
-latomicLinking to libatomic + is required for some uses of ISO C++11 + <atomic>. +
-fopenmpFor parallel mode.

Prev Up Next
Make Home Headers
\ No newline at end of file diff --git a/libstdc++-v3/doc/html/manual/using_concurrency.html b/libstdc++-v3/doc/html/manual/using_concurrency.html index 5370fc39d9e..ee3d8f563aa 100644 --- a/libstdc++-v3/doc/html/manual/using_concurrency.html +++ b/libstdc++-v3/doc/html/manual/using_concurrency.html @@ -24,13 +24,14 @@ 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). +

+ Some uses of std::atomic also require linking + to libatomic.

Thread Safety

In the terms of the 2011 C++ standard a thread-safe program is one which does not perform any conflicting non-atomic operations on memory locations @@ -59,11 +60,16 @@ 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 -pthread and -march=native, although specifics vary - depending on the host environment. See Machine + depending on the host environment. See + Command Options and + Machine Dependent Options.

  • - An implementation of atomicity.h functions - exists for the architecture in question. See the internals documentation for more details. + An implementation of the + atomicity.h functions + exists for the architecture in question. See the + internals + documentation for more details.

    • The user code must guard against concurrent function calls which access any particular library object's state when one or more of those accesses modifies the state. An object will be modified by diff --git a/libstdc++-v3/doc/html/manual/using_macros.html b/libstdc++-v3/doc/html/manual/using_macros.html index 44acbb7a0f3..bac3f363080 100644 --- a/libstdc++-v3/doc/html/manual/using_macros.html +++ b/libstdc++-v3/doc/html/manual/using_macros.html @@ -7,8 +7,9 @@ file c++config.h, 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 + <ios>. Most of these + macros should not be used by consumers of libstdc++, and are reserved for internal implementation use. These macros cannot be redefined.

    @@ -18,21 +19,22 @@ general public.

    Below is the macro which users may check for library version information.

    __GLIBCXX__

    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 - document. + particular release, please consult the + ABI Policy and Guidelines appendix.

    Below are the macros which users may change with #define/#undef or with -D/-U compiler flags. The default state of the symbol is listed.

    “Configurable” (or “Not configurable”) means that the symbol is initially chosen (or not) based on --enable/--disable options at library build and configure time - (documented here), with the - various --enable/--disable choices being translated to + (documented in + Configure), + with the various --enable/--disable choices being translated to #define/#undef).

    ABI means that changing from the default value may - mean changing the ABI of compiled code. In other words, these - choices control code which has already been compiled (i.e., in a + mean changing the ABI 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 headers may see different code paths, but the libraries which you link against will not. @@ -53,19 +55,20 @@ --enable-concept-checks. 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 here. + is described in more detail in + Compile Time Checks.

    _GLIBCXX_DEBUG

    Undefined by default. When defined, compiles user code using - the debug mode. + the debug mode.

    _GLIBCXX_DEBUG_PEDANTIC

    Undefined by default. When defined while compiling with - the debug mode, makes - the debug mode extremely picky by making the use of libstdc++ - extensions and libstdc++-specific behavior into errors. + the debug mode, makes + the debug mode extremely picky by making the use of libstdc++ + extensions and libstdc++-specific behavior into errors.

    _GLIBCXX_PARALLEL

    Undefined by default. When defined, compiles user code - using the parallel - mode. + using the parallel + mode.

    _GLIBCXX_PROFILE

    Undefined by default. When defined, compiles user code - using the profile - mode. + using the profile + mode.

    Prev Up Next
    Headers Home Namespaces
    \ No newline at end of file diff --git a/libstdc++-v3/doc/xml/manual/concurrency_extensions.xml b/libstdc++-v3/doc/xml/manual/concurrency_extensions.xml index b9bab53a424..cb79c205e68 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.
    Implementation -
    Using Builtin Atomic Functions +
    Using Built-in Atomic Functions The functions for atomic operations described above are either @@ -197,9 +197,21 @@ capable) or by library fallbacks. 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. + + +Prior to GCC 4.7 the older __sync intrinsics were used. +An example of an undefined symbol from the use of __sync_fetch_and_add on an unsupported host is a -missing reference to __sync_fetch_and_add_4.) +missing reference to __sync_fetch_and_add_4. + + +Current releases use the newer __atomic intrinsics, +which are implemented by library calls if the hardware doesn't support them. +Undefined references to functions like +__atomic_is_lock_free should be resolved by linking to +libatomic, which is usually +installed alongside libstdc++. 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 3256c585a43..f6f615e1743 100644 --- a/libstdc++-v3/doc/xml/manual/using.xml +++ b/libstdc++-v3/doc/xml/manual/using.xml @@ -6,8 +6,7 @@
    Command Options - 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 GCC Command Options. Options that impact libstdc++ are enumerated and detailed in the table below. @@ -64,8 +63,20 @@ -pthread or -pthreads - For ISO C++11 <thread>, <future>, - <mutex>, or <condition_variable>. + For ISO C++11 + <thread>, + <future>, + <mutex>, + or <condition_variable>. + + + + + -latomic + Linking to libatomic + is required for some uses of ISO C++11 + <atomic>. + @@ -779,8 +790,9 @@ g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe file c++config.h, 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 + <ios>. Most of these + macros should not be used by consumers of libstdc++, and are reserved for internal implementation use. These macros cannot be redefined. @@ -800,10 +812,10 @@ g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe __GLIBCXX__ 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 - document. + particular release, please consult the + ABI Policy and Guidelines appendix. @@ -816,14 +828,15 @@ g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe Configurable (or Not configurable) means that the symbol is initially chosen (or not) based on --enable/--disable options at library build and configure time - (documented here), with the - various --enable/--disable choices being translated to + (documented in + Configure), + with the various --enable/--disable choices being translated to #define/#undef). ABI means that changing from the default value may - mean changing the ABI of compiled code. In other words, these - choices control code which has already been compiled (i.e., in a + mean changing the ABI 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 headers may see different code paths, but the libraries 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 --enable-concept-checks. 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 here. + is described in more detail in + Compile Time Checks. @@ -862,31 +876,31 @@ g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe Undefined by default. When defined, compiles user code using - the debug mode. + the debug mode. _GLIBCXX_DEBUG_PEDANTIC Undefined by default. When defined while compiling with - the debug mode, makes - the debug mode extremely picky by making the use of libstdc++ - extensions and libstdc++-specific behavior into errors. + the debug mode, makes + the debug mode extremely picky by making the use of libstdc++ + extensions and libstdc++-specific behavior into errors. _GLIBCXX_PARALLEL Undefined by default. When defined, compiles user code - using the parallel - mode. + using the parallel + mode. _GLIBCXX_PROFILE Undefined by default. When defined, compiles user code - using the profile - mode. + using the profile + mode. @@ -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). + + + + Some uses of std::atomic also require linking + to libatomic.
    @@ -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 -pthread and -march=native, although specifics vary - depending on the host environment. See Machine + depending on the host environment. See + Command Options and + Machine Dependent Options.     - An implementation of atomicity.h functions - exists for the architecture in question. See the internals documentation for more details. + An implementation of the + atomicity.h functions + exists for the architecture in question. See the + internals + documentation for more details.