The libstdc++ parallel mode

The latest version of this document is always available at http://gcc.gnu.org/onlinedocs/libstdc++/parallel_mode.html.

To the libstdc++-v3 homepage.

The libstdc++ parallel mode is an experimental parallel implementation of many algorithms the C++ Standard Library.

Several of the standard algorithms, for instance std::search, are made parallel using OpenMP annotations. These parallel mode constructs and can be invoked by explicit source declaration or by compiling existing sources with a specific compiler flag.

The libstdc++ parallel mode

The libstdc++ parallel mode performs parallization of algorithms, function objects, classes, and functions in the C++ Standard.

Using the libstdc++ parallel mode

To use the libstdc++ parallel mode, compile your application with the compiler flag -D_GLIBCXX_PARALLEL -fopenmp. This will link in libgomp, the GNU OpenMP implementation, whose presence is mandatory. In addition, hardware capable of atomic operations is de rigueur. Actually activating these atomic operations may require explicit compiler flags on some targets (like sparc and x86), such as -march=i686, -march=native or -mcpu=v9.

Note that the _GLIBCXX_PARALLEL define may change the sizes and behavior of standard class templates such as std::search, and therefore one can only link code compiled with parallel mode and code compiled without parallel mode if no instantiation of a container is passed between the two translation units. Parallel mode functionality has distinct linkage, and cannot be confused with normal mode symbols.

The following library components in the include <numeric> are included in the parallel mode:

• std::accumulate
• std::adjacent_difference
• std::inner_product
• std::partial_sum

The following library components in the include <algorithm> are included in the parallel mode:

• std::adjacent_find
• std::count
• std::count_if
• std::equal
• std::find
• std::find_if
• std::find_first_of
• std::for_each
• std::generate
• std::generate_n
• std::lexicographical_compare
• std::mismatch
• std::search
• std::search_n
• std::transform
• std::replace
• std::replace_if
• std::max_element
• std::merge
• std::min_element
• std::nth_element
• std::partial_sort
• std::partition
• std::random_shuffle
• std::set_union
• std::set_intersection
• std::set_symmetric_difference
• std::set_difference
• std::sort
• std::stable_sort
• std::unique_copy

Using the parallel algorithms without parallel mode

When it is not feasible to recompile your entire application, or only specific algorithms need to be parallel-aware, individual parallel algorithms can be made available explicitly. These parallel algorithms are functionally equivalent to the standard drop-in algorithms used in parallel mode, but they are available in a separate namespace as GNU extensions and may be used in programs compiled with either release mode or with parallel mode. The following table provides the names and headers of the parallel algorithms:

Parallel mode semantics

Something about exception safety, interaction with threads, etc. Goal is to have the usual constraints of the STL with respect to exception safety and threads, but add in support for parallel computing.

Something about compile-time settings and configuration, ie using __gnu_parallel::Settings. XXX Up in the air.

Interface basics and relevant namespaces

Two namespaces contain the parallel mode: std::__parallel and __gnu_parallel.

One namespace contain versions of code that are explicitly sequential: __gnu_serial.

Parallel implementations of the sequential standard components are defined in namespace std::__parallel. For instance, std::transform from <algorithm> has a parallel counterpart in std::__parallel::transform from <parallel/algorithm>. In addition, these parallel implementatations are injected into namespace __gnu_parallel with using declarations.

Support and infrastructure is in namespace __gnu_parallel.

More information, and an organized index of types and functions related to the parallel mode on a per-namespace basis, can be found in the generated source documentation.

Testing

Both the normal conformance and regression tests and the supplemental performance tests work.

To run the conformance and regression tests with the parallel mode active,

The log and summary files for conformance testing are in the testsuite/parallel directory.

To run the performance tests with the parallel mode active,

The result file for performance testing are in the testsuite directory, in the file libstdc++_performance.sum. In addition, the policy-based containers have their own visualizations, which have additional software dependencies than the usual bare-boned text file, and can be generated by using the make doc-performance rule in the testsuite's Makefile.

Return to the top of the page or to the libstdc++ homepage.

See license.html for copying conditions. Comments and suggestions are welcome, and may be sent to the libstdc++ mailing list.