libstdc++-v3/doc/html/manual/parallel_mode_using.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Using</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.78.1" /><meta name="keywords" content="C++, library, parallel" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="parallel_mode.html" title="Chapter 18. Parallel Mode" /><link rel="prev" href="parallel_mode_semantics.html" title="Semantics" /><link rel="next" href="parallel_mode_design.html" title="Design" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Using</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="parallel_mode_semantics.html">Prev</a> </td><th width="60%" align="center">Chapter 18. Parallel Mode</th><td width="20%" align="right"> <a accesskey="n" href="parallel_mode_design.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.parallel_mode.using"></a>Using</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="parallel_mode.using.prereq_flags"></a>Prerequisite Compiler Flags</h3></div></div></div><p>
   3   Any use of parallel functionality requires additional compiler
   4   and runtime support, in particular support for OpenMP. Adding this support is
   5   not difficult: just compile your application with the compiler
   6   flag <code class="literal">-fopenmp</code>. This will link
   7   in <code class="code">libgomp</code>, the
   8   OpenMP <a class="link" href="http://gcc.gnu.org/onlinedocs/libgomp/" target="_top">GNU implementation</a>,
   9   whose presence is mandatory.
  10 </p><p>
  11 In addition, hardware that supports atomic operations and a compiler
  12   capable of producing atomic operations is mandatory: GCC defaults to no
  13   support for atomic operations on some common hardware
  14   architectures. Activating atomic operations may require explicit
  15   compiler flags on some targets (like sparc and x86), such
  16   as <code class="literal">-march=i686</code>,
  17   <code class="literal">-march=native</code> or <code class="literal">-mcpu=v9</code>. See
  18   the GCC manual for more information.
  19 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="parallel_mode.using.parallel_mode"></a>Using Parallel Mode</h3></div></div></div><p>
  20   To use the libstdc++ parallel mode, compile your application with
  21   the prerequisite flags as detailed above, and in addition
  22   add <code class="constant">-D_GLIBCXX_PARALLEL</code>. This will convert all
  23   use of the standard (sequential) algorithms to the appropriate parallel
  24   equivalents. Please note that this doesn't necessarily mean that
  25   everything will end up being executed in a parallel manner, but
  26   rather that the heuristics and settings coded into the parallel
  27   versions will be used to determine if all, some, or no algorithms
  28   will be executed using parallel variants.
  29 </p><p>Note that the <code class="constant">_GLIBCXX_PARALLEL</code> define may change the
  30   sizes and behavior of standard class templates such as
  31   <code class="function">std::search</code>, and therefore one can only link code
  32   compiled with parallel mode and code compiled without parallel mode
  33   if no instantiation of a container is passed between the two
  34   translation units. Parallel mode functionality has distinct linkage,
  35   and cannot be confused with normal mode symbols.
  36 </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="parallel_mode.using.specific"></a>Using Specific Parallel Components</h3></div></div></div><p>When it is not feasible to recompile your entire application, or
  37   only specific algorithms need to be parallel-aware, individual
  38   parallel algorithms can be made available explicitly. These
  39   parallel algorithms are functionally equivalent to the standard
  40   drop-in algorithms used in parallel mode, but they are available in
  41   a separate namespace as GNU extensions and may be used in programs
  42   compiled with either release mode or with parallel mode.
  43 </p><p>An example of using a parallel version
  44 of <code class="function">std::sort</code>, but no other parallel algorithms, is:
  45 </p><pre class="programlisting">
  46 #include &lt;vector&gt;
  47 #include &lt;parallel/algorithm&gt;
  48
  49 int main()
  50 {
  51   std::vector&lt;int&gt; v(100);
  52
  53   // ...
  54
  55   // Explicitly force a call to parallel sort.
  56   __gnu_parallel::sort(v.begin(), v.end());
  57   return 0;
  58 }
  59 </pre><p>
  60 Then compile this code with the prerequisite compiler flags
  61 (<code class="literal">-fopenmp</code> and any necessary architecture-specific
  62 flags for atomic operations.)
  63 </p><p> The following table provides the names and headers of all the
  64   parallel algorithms that can be used in a similar manner:
  65 </p><div class="table"><a id="table.parallel_algos"></a><p class="title"><strong>Table 18.1. Parallel Algorithms</strong></p><div class="table-contents"><table summary="Parallel Algorithms" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /><col align="left" class="c3" /><col align="left" class="c4" /></colgroup><thead><tr><th align="left">Algorithm</th><th align="left">Header</th><th align="left">Parallel algorithm</th><th align="left">Parallel header</th></tr></thead><tbody><tr><td align="left"><code class="function">std::accumulate</code></td><td align="left"><code class="filename">numeric</code></td><td align="left"><code class="function">__gnu_parallel::accumulate</code></td><td align="left"><code class="filename">parallel/numeric</code></td></tr><tr><td align="left"><code class="function">std::adjacent_difference</code></td><td align="left"><code class="filename">numeric</code></td><td align="left"><code class="function">__gnu_parallel::adjacent_difference</code></td><td align="left"><code class="filename">parallel/numeric</code></td></tr><tr><td align="left"><code class="function">std::inner_product</code></td><td align="left"><code class="filename">numeric</code></td><td align="left"><code class="function">__gnu_parallel::inner_product</code></td><td align="left"><code class="filename">parallel/numeric</code></td></tr><tr><td align="left"><code class="function">std::partial_sum</code></td><td align="left"><code class="filename">numeric</code></td><td align="left"><code class="function">__gnu_parallel::partial_sum</code></td><td align="left"><code class="filename">parallel/numeric</code></td></tr><tr><td align="left"><code class="function">std::adjacent_find</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::adjacent_find</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::count</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::count</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::count_if</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::count_if</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::equal</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::equal</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::find</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::find</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::find_if</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::find_if</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::find_first_of</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::find_first_of</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::for_each</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::for_each</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::generate</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::generate</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::generate_n</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::generate_n</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::lexicographical_compare</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::lexicographical_compare</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::mismatch</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::mismatch</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::search</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::search</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::search_n</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::search_n</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::transform</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::transform</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::replace</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::replace</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::replace_if</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::replace_if</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::max_element</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::max_element</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::merge</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::merge</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::min_element</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::min_element</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::nth_element</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::nth_element</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::partial_sort</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::partial_sort</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::partition</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::partition</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::random_shuffle</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::random_shuffle</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::set_union</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::set_union</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::set_intersection</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::set_intersection</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::set_symmetric_difference</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::set_symmetric_difference</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::set_difference</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::set_difference</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::sort</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::sort</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::stable_sort</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::stable_sort</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr><tr><td align="left"><code class="function">std::unique_copy</code></td><td align="left"><code class="filename">algorithm</code></td><td align="left"><code class="function">__gnu_parallel::unique_copy</code></td><td align="left"><code class="filename">parallel/algorithm</code></td></tr></tbody></table></div></div><br class="table-break" /></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="parallel_mode_semantics.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="parallel_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="parallel_mode_design.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Semantics </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Design</td></tr></table></div></body></html>