libstdc++-v3/doc/xml/manual/parallel_mode.xml

   1 <chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
   2          xml:id="manual.ext.parallel_mode" xreflabel="Parallel Mode">
   3 <?dbhtml filename="parallel_mode.html"?>
   4
   5 <info><title>Parallel Mode</title>
   6   <keywordset>
   7     <keyword>
   8       C++
   9     </keyword>
  10     <keyword>
  11       library
  12     </keyword>
  13     <keyword>
  14       parallel
  15     </keyword>
  16   </keywordset>
  17 </info>
  18
  19
  20
  21 <para> The libstdc++ parallel mode is an experimental parallel
  22 implementation of many algorithms the C++ Standard Library.
  23 </para>
  24
  25 <para>
  26 Several of the standard algorithms, for instance
  27 <function>std::sort</function>, are made parallel using OpenMP
  28 annotations. These parallel mode constructs and can be invoked by
  29 explicit source declaration or by compiling existing sources with a
  30 specific compiler flag.
  31 </para>
  32
  33
  34 <section xml:id="manual.ext.parallel_mode.intro" xreflabel="Intro"><info><title>Intro</title></info>
  35
  36
  37 <para>The following library components in the include
  38 <filename class="headerfile">numeric</filename> are included in the parallel mode:</para>
  39 <itemizedlist>
  40   <listitem><para><function>std::accumulate</function></para></listitem>
  41   <listitem><para><function>std::adjacent_difference</function></para></listitem>
  42   <listitem><para><function>std::inner_product</function></para></listitem>
  43   <listitem><para><function>std::partial_sum</function></para></listitem>
  44 </itemizedlist>
  45
  46 <para>The following library components in the include
  47 <filename class="headerfile">algorithm</filename> are included in the parallel mode:</para>
  48 <itemizedlist>
  49   <listitem><para><function>std::adjacent_find</function></para></listitem>
  50   <listitem><para><function>std::count</function></para></listitem>
  51   <listitem><para><function>std::count_if</function></para></listitem>
  52   <listitem><para><function>std::equal</function></para></listitem>
  53   <listitem><para><function>std::find</function></para></listitem>
  54   <listitem><para><function>std::find_if</function></para></listitem>
  55   <listitem><para><function>std::find_first_of</function></para></listitem>
  56   <listitem><para><function>std::for_each</function></para></listitem>
  57   <listitem><para><function>std::generate</function></para></listitem>
  58   <listitem><para><function>std::generate_n</function></para></listitem>
  59   <listitem><para><function>std::lexicographical_compare</function></para></listitem>
  60   <listitem><para><function>std::mismatch</function></para></listitem>
  61   <listitem><para><function>std::search</function></para></listitem>
  62   <listitem><para><function>std::search_n</function></para></listitem>
  63   <listitem><para><function>std::transform</function></para></listitem>
  64   <listitem><para><function>std::replace</function></para></listitem>
  65   <listitem><para><function>std::replace_if</function></para></listitem>
  66   <listitem><para><function>std::max_element</function></para></listitem>
  67   <listitem><para><function>std::merge</function></para></listitem>
  68   <listitem><para><function>std::min_element</function></para></listitem>
  69   <listitem><para><function>std::nth_element</function></para></listitem>
  70   <listitem><para><function>std::partial_sort</function></para></listitem>
  71   <listitem><para><function>std::partition</function></para></listitem>
  72   <listitem><para><function>std::random_shuffle</function></para></listitem>
  73   <listitem><para><function>std::set_union</function></para></listitem>
  74   <listitem><para><function>std::set_intersection</function></para></listitem>
  75   <listitem><para><function>std::set_symmetric_difference</function></para></listitem>
  76   <listitem><para><function>std::set_difference</function></para></listitem>
  77   <listitem><para><function>std::sort</function></para></listitem>
  78   <listitem><para><function>std::stable_sort</function></para></listitem>
  79   <listitem><para><function>std::unique_copy</function></para></listitem>
  80 </itemizedlist>
  81
  82 </section>
  83
  84 <section xml:id="manual.ext.parallel_mode.semantics" xreflabel="Semantics"><info><title>Semantics</title></info>
  85
  86
  87 <para> The parallel mode STL algorithms are currently not exception-safe,
  88 i.e. user-defined functors must not throw exceptions.
  89 Also, the order of execution is not guaranteed for some functions, of course.
  90 Therefore, user-defined functors should not have any concurrent side effects.
  91 </para>
  92
  93 <para> Since the current GCC OpenMP implementation does not support
  94 OpenMP parallel regions in concurrent threads,
  95 it is not possible to call parallel STL algorithm in
  96 concurrent threads, either.
  97 It might work with other compilers, though.</para>
  98
  99 </section>
 100
 101 <section xml:id="manual.ext.parallel_mode.using" xreflabel="Using"><info><title>Using</title></info>
 102
 103
 104 <section xml:id="parallel_mode.using.prereq_flags"><info><title>Prerequisite Compiler Flags</title></info>
 105
 106
 107 <para>
 108   Any use of parallel functionality requires additional compiler
 109   and runtime support, in particular support for OpenMP. Adding this support is
 110   not difficult: just compile your application with the compiler
 111   flag <literal>-fopenmp</literal>. This will link
 112   in <code>libgomp</code>, the GNU
 113   OpenMP <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libgomp">implementation</link>,
 114   whose presence is mandatory.
 115 </para>
 116
 117 <para>
 118 In addition, hardware that supports atomic operations and a compiler
 119   capable of producing atomic operations is mandatory: GCC defaults to no
 120   support for atomic operations on some common hardware
 121   architectures. Activating atomic operations may require explicit
 122   compiler flags on some targets (like sparc and x86), such
 123   as <literal>-march=i686</literal>,
 124   <literal>-march=native</literal> or <literal>-mcpu=v9</literal>. See
 125   the GCC manual for more information.
 126 </para>
 127
 128 </section>
 129
 130 <section xml:id="parallel_mode.using.parallel_mode"><info><title>Using Parallel Mode</title></info>
 131
 132
 133 <para>
 134   To use the libstdc++ parallel mode, compile your application with
 135   the prerequisite flags as detailed above, and in addition
 136   add <constant>-D_GLIBCXX_PARALLEL</constant>. This will convert all
 137   use of the standard (sequential) algorithms to the appropriate parallel
 138   equivalents. Please note that this doesn't necessarily mean that
 139   everything will end up being executed in a parallel manner, but
 140   rather that the heuristics and settings coded into the parallel
 141   versions will be used to determine if all, some, or no algorithms
 142   will be executed using parallel variants.
 143 </para>
 144
 145 <para>Note that the <constant>_GLIBCXX_PARALLEL</constant> define may change the
 146   sizes and behavior of standard class templates such as
 147   <function>std::search</function>, and therefore one can only link code
 148   compiled with parallel mode and code compiled without parallel mode
 149   if no instantiation of a container is passed between the two
 150   translation units. Parallel mode functionality has distinct linkage,
 151   and cannot be confused with normal mode symbols.
 152 </para>
 153 </section>
 154
 155 <section xml:id="parallel_mode.using.specific"><info><title>Using Specific Parallel Components</title></info>
 156
 157
 158 <para>When it is not feasible to recompile your entire application, or
 159   only specific algorithms need to be parallel-aware, individual
 160   parallel algorithms can be made available explicitly. These
 161   parallel algorithms are functionally equivalent to the standard
 162   drop-in algorithms used in parallel mode, but they are available in
 163   a separate namespace as GNU extensions and may be used in programs
 164   compiled with either release mode or with parallel mode.
 165 </para>
 166
 167
 168 <para>An example of using a parallel version
 169 of <function>std::sort</function>, but no other parallel algorithms, is:
 170 </para>
 171
 172 <programlisting>
 173 #include &lt;vector&gt;
 174 #include &lt;parallel/algorithm&gt;
 175
 176 int main()
 177 {
 178   std::vector&lt;int&gt; v(100);
 179
 180   // ...
 181
 182   // Explicitly force a call to parallel sort.
 183   __gnu_parallel::sort(v.begin(), v.end());
 184   return 0;
 185 }
 186 </programlisting>
 187
 188 <para>
 189 Then compile this code with the prerequisite compiler flags
 190 (<literal>-fopenmp</literal> and any necessary architecture-specific
 191 flags for atomic operations.)
 192 </para>
 193
 194 <para> The following table provides the names and headers of all the
 195   parallel algorithms that can be used in a similar manner:
 196 </para>
 197
 198 <table frame="all">
 199 <title>Parallel Algorithms</title>
 200
 201 <tgroup cols="4" align="left" colsep="1" rowsep="1">
 202 <colspec colname="c1"/>
 203 <colspec colname="c2"/>
 204 <colspec colname="c3"/>
 205 <colspec colname="c4"/>
 206
 207 <thead>
 208   <row>
 209     <entry>Algorithm</entry>
 210     <entry>Header</entry>
 211     <entry>Parallel algorithm</entry>
 212     <entry>Parallel header</entry>
 213   </row>
 214 </thead>
 215
 216 <tbody>
 217   <row>
 218     <entry><function>std::accumulate</function></entry>
 219     <entry><filename class="headerfile">numeric</filename></entry>
 220     <entry><function>__gnu_parallel::accumulate</function></entry>
 221     <entry><filename class="headerfile">parallel/numeric</filename></entry>
 222   </row>
 223   <row>
 224     <entry><function>std::adjacent_difference</function></entry>
 225     <entry><filename class="headerfile">numeric</filename></entry>
 226     <entry><function>__gnu_parallel::adjacent_difference</function></entry>
 227     <entry><filename class="headerfile">parallel/numeric</filename></entry>
 228   </row>
 229   <row>
 230     <entry><function>std::inner_product</function></entry>
 231     <entry><filename class="headerfile">numeric</filename></entry>
 232     <entry><function>__gnu_parallel::inner_product</function></entry>
 233     <entry><filename class="headerfile">parallel/numeric</filename></entry>
 234   </row>
 235   <row>
 236     <entry><function>std::partial_sum</function></entry>
 237     <entry><filename class="headerfile">numeric</filename></entry>
 238     <entry><function>__gnu_parallel::partial_sum</function></entry>
 239     <entry><filename class="headerfile">parallel/numeric</filename></entry>
 240   </row>
 241   <row>
 242     <entry><function>std::adjacent_find</function></entry>
 243     <entry><filename class="headerfile">algorithm</filename></entry>
 244     <entry><function>__gnu_parallel::adjacent_find</function></entry>
 245     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 246   </row>
 247
 248   <row>
 249     <entry><function>std::count</function></entry>
 250     <entry><filename class="headerfile">algorithm</filename></entry>
 251     <entry><function>__gnu_parallel::count</function></entry>
 252     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 253   </row>
 254
 255   <row>
 256     <entry><function>std::count_if</function></entry>
 257     <entry><filename class="headerfile">algorithm</filename></entry>
 258     <entry><function>__gnu_parallel::count_if</function></entry>
 259     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 260   </row>
 261
 262   <row>
 263     <entry><function>std::equal</function></entry>
 264     <entry><filename class="headerfile">algorithm</filename></entry>
 265     <entry><function>__gnu_parallel::equal</function></entry>
 266     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 267   </row>
 268
 269   <row>
 270     <entry><function>std::find</function></entry>
 271     <entry><filename class="headerfile">algorithm</filename></entry>
 272     <entry><function>__gnu_parallel::find</function></entry>
 273     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 274   </row>
 275
 276   <row>
 277     <entry><function>std::find_if</function></entry>
 278     <entry><filename class="headerfile">algorithm</filename></entry>
 279     <entry><function>__gnu_parallel::find_if</function></entry>
 280     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 281   </row>
 282
 283   <row>
 284     <entry><function>std::find_first_of</function></entry>
 285     <entry><filename class="headerfile">algorithm</filename></entry>
 286     <entry><function>__gnu_parallel::find_first_of</function></entry>
 287     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 288   </row>
 289
 290   <row>
 291     <entry><function>std::for_each</function></entry>
 292     <entry><filename class="headerfile">algorithm</filename></entry>
 293     <entry><function>__gnu_parallel::for_each</function></entry>
 294     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 295   </row>
 296
 297   <row>
 298     <entry><function>std::generate</function></entry>
 299     <entry><filename class="headerfile">algorithm</filename></entry>
 300     <entry><function>__gnu_parallel::generate</function></entry>
 301     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 302   </row>
 303
 304   <row>
 305     <entry><function>std::generate_n</function></entry>
 306     <entry><filename class="headerfile">algorithm</filename></entry>
 307     <entry><function>__gnu_parallel::generate_n</function></entry>
 308     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 309   </row>
 310
 311   <row>
 312     <entry><function>std::lexicographical_compare</function></entry>
 313     <entry><filename class="headerfile">algorithm</filename></entry>
 314     <entry><function>__gnu_parallel::lexicographical_compare</function></entry>
 315     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 316   </row>
 317
 318   <row>
 319     <entry><function>std::mismatch</function></entry>
 320     <entry><filename class="headerfile">algorithm</filename></entry>
 321     <entry><function>__gnu_parallel::mismatch</function></entry>
 322     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 323   </row>
 324
 325   <row>
 326     <entry><function>std::search</function></entry>
 327     <entry><filename class="headerfile">algorithm</filename></entry>
 328     <entry><function>__gnu_parallel::search</function></entry>
 329     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 330   </row>
 331
 332   <row>
 333     <entry><function>std::search_n</function></entry>
 334     <entry><filename class="headerfile">algorithm</filename></entry>
 335     <entry><function>__gnu_parallel::search_n</function></entry>
 336     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 337   </row>
 338
 339   <row>
 340     <entry><function>std::transform</function></entry>
 341     <entry><filename class="headerfile">algorithm</filename></entry>
 342     <entry><function>__gnu_parallel::transform</function></entry>
 343     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 344   </row>
 345
 346   <row>
 347     <entry><function>std::replace</function></entry>
 348     <entry><filename class="headerfile">algorithm</filename></entry>
 349     <entry><function>__gnu_parallel::replace</function></entry>
 350     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 351   </row>
 352
 353   <row>
 354     <entry><function>std::replace_if</function></entry>
 355     <entry><filename class="headerfile">algorithm</filename></entry>
 356     <entry><function>__gnu_parallel::replace_if</function></entry>
 357     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 358   </row>
 359
 360   <row>
 361     <entry><function>std::max_element</function></entry>
 362     <entry><filename class="headerfile">algorithm</filename></entry>
 363     <entry><function>__gnu_parallel::max_element</function></entry>
 364     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 365   </row>
 366
 367   <row>
 368     <entry><function>std::merge</function></entry>
 369     <entry><filename class="headerfile">algorithm</filename></entry>
 370     <entry><function>__gnu_parallel::merge</function></entry>
 371     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 372   </row>
 373
 374   <row>
 375     <entry><function>std::min_element</function></entry>
 376     <entry><filename class="headerfile">algorithm</filename></entry>
 377     <entry><function>__gnu_parallel::min_element</function></entry>
 378     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 379   </row>
 380
 381   <row>
 382     <entry><function>std::nth_element</function></entry>
 383     <entry><filename class="headerfile">algorithm</filename></entry>
 384     <entry><function>__gnu_parallel::nth_element</function></entry>
 385     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 386   </row>
 387
 388   <row>
 389     <entry><function>std::partial_sort</function></entry>
 390     <entry><filename class="headerfile">algorithm</filename></entry>
 391     <entry><function>__gnu_parallel::partial_sort</function></entry>
 392     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 393   </row>
 394
 395   <row>
 396     <entry><function>std::partition</function></entry>
 397     <entry><filename class="headerfile">algorithm</filename></entry>
 398     <entry><function>__gnu_parallel::partition</function></entry>
 399     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 400   </row>
 401
 402   <row>
 403     <entry><function>std::random_shuffle</function></entry>
 404     <entry><filename class="headerfile">algorithm</filename></entry>
 405     <entry><function>__gnu_parallel::random_shuffle</function></entry>
 406     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 407   </row>
 408
 409   <row>
 410     <entry><function>std::set_union</function></entry>
 411     <entry><filename class="headerfile">algorithm</filename></entry>
 412     <entry><function>__gnu_parallel::set_union</function></entry>
 413     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 414   </row>
 415
 416   <row>
 417     <entry><function>std::set_intersection</function></entry>
 418     <entry><filename class="headerfile">algorithm</filename></entry>
 419     <entry><function>__gnu_parallel::set_intersection</function></entry>
 420     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 421   </row>
 422
 423   <row>
 424     <entry><function>std::set_symmetric_difference</function></entry>
 425     <entry><filename class="headerfile">algorithm</filename></entry>
 426     <entry><function>__gnu_parallel::set_symmetric_difference</function></entry>
 427     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 428   </row>
 429
 430   <row>
 431     <entry><function>std::set_difference</function></entry>
 432     <entry><filename class="headerfile">algorithm</filename></entry>
 433     <entry><function>__gnu_parallel::set_difference</function></entry>
 434     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 435   </row>
 436
 437   <row>
 438     <entry><function>std::sort</function></entry>
 439     <entry><filename class="headerfile">algorithm</filename></entry>
 440     <entry><function>__gnu_parallel::sort</function></entry>
 441     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 442   </row>
 443
 444   <row>
 445     <entry><function>std::stable_sort</function></entry>
 446     <entry><filename class="headerfile">algorithm</filename></entry>
 447     <entry><function>__gnu_parallel::stable_sort</function></entry>
 448     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 449   </row>
 450
 451   <row>
 452     <entry><function>std::unique_copy</function></entry>
 453     <entry><filename class="headerfile">algorithm</filename></entry>
 454     <entry><function>__gnu_parallel::unique_copy</function></entry>
 455     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 456   </row>
 457 </tbody>
 458 </tgroup>
 459 </table>
 460
 461 </section>
 462
 463 </section>
 464
 465 <section xml:id="manual.ext.parallel_mode.design" xreflabel="Design"><info><title>Design</title></info>
 466
 467   <para>
 468   </para>
 469 <section xml:id="parallel_mode.design.intro" xreflabel="Intro"><info><title>Interface Basics</title></info>
 470
 471
 472 <para>
 473 All parallel algorithms are intended to have signatures that are
 474 equivalent to the ISO C++ algorithms replaced. For instance, the
 475 <function>std::adjacent_find</function> function is declared as:
 476 </para>
 477 <programlisting>
 478 namespace std
 479 {
 480   template&lt;typename _FIter&gt;
 481     _FIter
 482     adjacent_find(_FIter, _FIter);
 483 }
 484 </programlisting>
 485
 486 <para>
 487 Which means that there should be something equivalent for the parallel
 488 version. Indeed, this is the case:
 489 </para>
 490
 491 <programlisting>
 492 namespace std
 493 {
 494   namespace __parallel
 495   {
 496     template&lt;typename _FIter&gt;
 497       _FIter
 498       adjacent_find(_FIter, _FIter);
 499
 500     ...
 501   }
 502 }
 503 </programlisting>
 504
 505 <para>But.... why the ellipses?
 506 </para>
 507
 508 <para> The ellipses in the example above represent additional overloads
 509 required for the parallel version of the function. These additional
 510 overloads are used to dispatch calls from the ISO C++ function
 511 signature to the appropriate parallel function (or sequential
 512 function, if no parallel functions are deemed worthy), based on either
 513 compile-time or run-time conditions.
 514 </para>
 515
 516 <para> The available signature options are specific for the different
 517 algorithms/algorithm classes.</para>
 518
 519 <para> The general view of overloads for the parallel algorithms look like this:
 520 </para>
 521 <itemizedlist>
 522    <listitem><para>ISO C++ signature</para></listitem>
 523    <listitem><para>ISO C++ signature + sequential_tag argument</para></listitem>
 524    <listitem><para>ISO C++ signature + algorithm-specific tag type
 525     (several signatures)</para></listitem>
 526 </itemizedlist>
 527
 528 <para> Please note that the implementation may use additional functions
 529 (designated with the <code>_switch</code> suffix) to dispatch from the
 530 ISO C++ signature to the correct parallel version. Also, some of the
 531 algorithms do not have support for run-time conditions, so the last
 532 overload is therefore missing.
 533 </para>
 534
 535
 536 </section>
 537
 538 <section xml:id="parallel_mode.design.tuning" xreflabel="Tuning"><info><title>Configuration and Tuning</title></info>
 539
 540
 541
 542 <section xml:id="parallel_mode.design.tuning.omp" xreflabel="OpenMP Environment"><info><title>Setting up the OpenMP Environment</title></info>
 543
 544
 545 <para>
 546 Several aspects of the overall runtime environment can be manipulated
 547 by standard OpenMP function calls.
 548 </para>
 549
 550 <para>
 551 To specify the number of threads to be used for the algorithms globally,
 552 use the function <function>omp_set_num_threads</function>. An example:
 553 </para>
 554
 555 <programlisting>
 556 #include &lt;stdlib.h&gt;
 557 #include &lt;omp.h&gt;
 558
 559 int main()
 560 {
 561   // Explicitly set number of threads.
 562   const int threads_wanted = 20;
 563   omp_set_dynamic(false);
 564   omp_set_num_threads(threads_wanted);
 565
 566   // Call parallel mode algorithms.
 567
 568   return 0;
 569 }
 570 </programlisting>
 571
 572 <para>
 573  Some algorithms allow the number of threads being set for a particular call,
 574  by augmenting the algorithm variant.
 575  See the next section for further information.
 576 </para>
 577
 578 <para>
 579 Other parts of the runtime environment able to be manipulated include
 580 nested parallelism (<function>omp_set_nested</function>), schedule kind
 581 (<function>omp_set_schedule</function>), and others. See the OpenMP
 582 documentation for more information.
 583 </para>
 584
 585 </section>
 586
 587 <section xml:id="parallel_mode.design.tuning.compile" xreflabel="Compile Switches"><info><title>Compile Time Switches</title></info>
 588
 589
 590 <para>
 591 To force an algorithm to execute sequentially, even though parallelism
 592 is switched on in general via the macro <constant>_GLIBCXX_PARALLEL</constant>,
 593 add <classname>__gnu_parallel::sequential_tag()</classname> to the end
 594 of the algorithm's argument list.
 595 </para>
 596
 597 <para>
 598 Like so:
 599 </para>
 600
 601 <programlisting>
 602 std::sort(v.begin(), v.end(), __gnu_parallel::sequential_tag());
 603 </programlisting>
 604
 605 <para>
 606 Some parallel algorithm variants can be excluded from compilation by
 607 preprocessor defines. See the doxygen documentation on
 608 <code>compiletime_settings.h</code> and <code>features.h</code> for details.
 609 </para>
 610
 611 <para>
 612 For some algorithms, the desired variant can be chosen at compile-time by
 613 appending a tag object. The available options are specific to the particular
 614 algorithm (class).
 615 </para>
 616
 617 <para>
 618 For the "embarrassingly parallel" algorithms, there is only one "tag object
 619 type", the enum _Parallelism.
 620 It takes one of the following values,
 621 <code>__gnu_parallel::parallel_tag</code>,
 622 <code>__gnu_parallel::balanced_tag</code>,
 623 <code>__gnu_parallel::unbalanced_tag</code>,
 624 <code>__gnu_parallel::omp_loop_tag</code>,
 625 <code>__gnu_parallel::omp_loop_static_tag</code>.
 626 This means that the actual parallelization strategy is chosen at run-time.
 627 (Choosing the variants at compile-time will come soon.)
 628 </para>
 629
 630 <para>
 631 For the following algorithms in general, we have
 632 <code>__gnu_parallel::parallel_tag</code> and
 633 <code>__gnu_parallel::default_parallel_tag</code>, in addition to
 634 <code>__gnu_parallel::sequential_tag</code>.
 635 <code>__gnu_parallel::default_parallel_tag</code> chooses the default
 636 algorithm at compiletime, as does omitting the tag.
 637 <code>__gnu_parallel::parallel_tag</code> postpones the decision to runtime
 638 (see next section).
 639 For all tags, the number of threads desired for this call can optionally be
 640 passed to the respective tag's constructor.
 641 </para>
 642
 643 <para>
 644 The <code>multiway_merge</code> algorithm comes with the additional choices,
 645 <code>__gnu_parallel::exact_tag</code> and
 646 <code>__gnu_parallel::sampling_tag</code>.
 647 Exact and sampling are the two available splitting strategies.
 648 </para>
 649
 650 <para>
 651 For the <code>sort</code> and <code>stable_sort</code> algorithms, there are
 652 several additional choices, namely
 653 <code>__gnu_parallel::multiway_mergesort_tag</code>,
 654 <code>__gnu_parallel::multiway_mergesort_exact_tag</code>,
 655 <code>__gnu_parallel::multiway_mergesort_sampling_tag</code>,
 656 <code>__gnu_parallel::quicksort_tag</code>, and
 657 <code>__gnu_parallel::balanced_quicksort_tag</code>.
 658 Multiway mergesort comes with the two splitting strategies for multi-way
 659 merging. The quicksort options cannot be used for <code>stable_sort</code>.
 660 </para>
 661
 662 </section>
 663
 664 <section xml:id="parallel_mode.design.tuning.settings" xreflabel="_Settings"><info><title>Run Time Settings and Defaults</title></info>
 665
 666
 667 <para>
 668 The default parallelization strategy, the choice of specific algorithm
 669 strategy, the minimum threshold limits for individual parallel
 670 algorithms, and aspects of the underlying hardware can be specified as
 671 desired via manipulation
 672 of <classname>__gnu_parallel::_Settings</classname> member data.
 673 </para>
 674
 675 <para>
 676 First off, the choice of parallelization strategy: serial, parallel,
 677 or heuristically deduced. This corresponds
 678 to <code>__gnu_parallel::_Settings::algorithm_strategy</code> and is a
 679 value of enum <type>__gnu_parallel::_AlgorithmStrategy</type>
 680 type. Choices
 681 include: <type>heuristic</type>, <type>force_sequential</type>,
 682 and <type>force_parallel</type>. The default is <type>heuristic</type>.
 683 </para>
 684
 685
 686 <para>
 687 Next, the sub-choices for algorithm variant, if not fixed at compile-time.
 688 Specific algorithms like <function>find</function> or <function>sort</function>
 689 can be implemented in multiple ways: when this is the case,
 690 a <classname>__gnu_parallel::_Settings</classname> member exists to
 691 pick the default strategy. For
 692 example, <code>__gnu_parallel::_Settings::sort_algorithm</code> can
 693 have any values of
 694 enum <type>__gnu_parallel::_SortAlgorithm</type>: <type>MWMS</type>, <type>QS</type>,
 695 or <type>QS_BALANCED</type>.
 696 </para>
 697
 698 <para>
 699 Likewise for setting the minimal threshold for algorithm
 700 parallelization.  Parallelism always incurs some overhead. Thus, it is
 701 not helpful to parallelize operations on very small sets of
 702 data. Because of this, measures are taken to avoid parallelizing below
 703 a certain, pre-determined threshold. For each algorithm, a minimum
 704 problem size is encoded as a variable in the
 705 active <classname>__gnu_parallel::_Settings</classname> object.  This
 706 threshold variable follows the following naming scheme:
 707 <code>__gnu_parallel::_Settings::[algorithm]_minimal_n</code>.  So,
 708 for <function>fill</function>, the threshold variable
 709 is <code>__gnu_parallel::_Settings::fill_minimal_n</code>,
 710 </para>
 711
 712 <para>
 713 Finally, hardware details like L1/L2 cache size can be hardwired
 714 via <code>__gnu_parallel::_Settings::L1_cache_size</code> and friends.
 715 </para>
 716
 717 <para>
 718 </para>
 719
 720 <para>
 721 All these configuration variables can be changed by the user, if
 722 desired.
 723 There exists one global instance of the class <classname>_Settings</classname>,
 724 i. e. it is a singleton. It can be read and written by calling
 725 <code>__gnu_parallel::_Settings::get</code> and
 726 <code>__gnu_parallel::_Settings::set</code>, respectively.
 727 Please note that the first call return a const object, so direct manipulation
 728 is forbidden.
 729 See <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a01005.html">
 730   <filename class="headerfile">settings.h</filename></link>
 731 for complete details.
 732 </para>
 733
 734 <para>
 735 A small example of tuning the default:
 736 </para>
 737
 738 <programlisting>
 739 #include &lt;parallel/algorithm&gt;
 740 #include &lt;parallel/settings.h&gt;
 741
 742 int main()
 743 {
 744   __gnu_parallel::_Settings s;
 745   s.algorithm_strategy = __gnu_parallel::force_parallel;
 746   __gnu_parallel::_Settings::set(s);
 747
 748   // Do work... all algorithms will be parallelized, always.
 749
 750   return 0;
 751 }
 752 </programlisting>
 753
 754 </section>
 755
 756 </section>
 757
 758 <section xml:id="parallel_mode.design.impl" xreflabel="Impl"><info><title>Implementation Namespaces</title></info>
 759
 760
 761 <para> One namespace contain versions of code that are always
 762 explicitly sequential:
 763 <code>__gnu_serial</code>.
 764 </para>
 765
 766 <para> Two namespaces contain the parallel mode:
 767 <code>std::__parallel</code> and <code>__gnu_parallel</code>.
 768 </para>
 769
 770 <para> Parallel implementations of standard components, including
 771 template helpers to select parallelism, are defined in <code>namespace
 772 std::__parallel</code>. For instance, <function>std::transform</function> from <filename class="headerfile">algorithm</filename> has a parallel counterpart in
 773 <function>std::__parallel::transform</function> from <filename class="headerfile">parallel/algorithm</filename>. In addition, these parallel
 774 implementations are injected into <code>namespace
 775 __gnu_parallel</code> with using declarations.
 776 </para>
 777
 778 <para> Support and general infrastructure is in <code>namespace
 779 __gnu_parallel</code>.
 780 </para>
 781
 782 <para> More information, and an organized index of types and functions
 783 related to the parallel mode on a per-namespace basis, can be found in
 784 the generated source documentation.
 785 </para>
 786
 787 </section>
 788
 789 </section>
 790
 791 <section xml:id="manual.ext.parallel_mode.test" xreflabel="Testing"><info><title>Testing</title></info>
 792
 793
 794   <para>
 795     Both the normal conformance and regression tests and the
 796     supplemental performance tests work.
 797   </para>
 798
 799   <para>
 800     To run the conformance and regression tests with the parallel mode
 801     active,
 802   </para>
 803
 804   <screen>
 805   <userinput>make check-parallel</userinput>
 806   </screen>
 807
 808   <para>
 809     The log and summary files for conformance testing are in the
 810     <filename class="directory">testsuite/parallel</filename> directory.
 811   </para>
 812
 813   <para>
 814     To run the performance tests with the parallel mode active,
 815   </para>
 816
 817   <screen>
 818   <userinput>make check-performance-parallel</userinput>
 819   </screen>
 820
 821   <para>
 822     The result file for performance testing are in the
 823     <filename class="directory">testsuite</filename> directory, in the file
 824     <filename>libstdc++_performance.sum</filename>. In addition, the
 825     policy-based containers have their own visualizations, which have
 826     additional software dependencies than the usual bare-boned text
 827     file, and can be generated by using the <code>make
 828     doc-performance</code> rule in the testsuite's Makefile.
 829 </para>
 830 </section>
 831
 832 <bibliography xml:id="parallel_mode.biblio"><info><title>Bibliography</title></info>
 833
 834
 835   <biblioentry>
 836     <citetitle>
 837       Parallelization of Bulk Operations for STL Dictionaries
 838     </citetitle>
 839
 840     <author><personname><firstname>Johannes</firstname><surname>Singler</surname></personname></author>
 841     <author><personname><firstname>Leonor</firstname><surname>Frias</surname></personname></author>
 842
 843     <copyright>
 844       <year>2007</year>
 845       <holder/>
 846     </copyright>
 847
 848     <publisher>
 849       <publishername>
 850         Workshop on Highly Parallel Processing on a Chip (HPPC) 2007. (LNCS)
 851       </publishername>
 852     </publisher>
 853   </biblioentry>
 854
 855   <biblioentry>
 856     <citetitle>
 857       The Multi-Core Standard Template Library
 858     </citetitle>
 859
 860     <author><personname><firstname>Johannes</firstname><surname>Singler</surname></personname></author>
 861     <author><personname><firstname>Peter</firstname><surname>Sanders</surname></personname></author>
 862     <author><personname><firstname>Felix</firstname><surname>Putze</surname></personname></author>
 863
 864     <copyright>
 865       <year>2007</year>
 866       <holder/>
 867     </copyright>
 868
 869     <publisher>
 870       <publishername>
 871          Euro-Par 2007: Parallel Processing. (LNCS 4641)
 872       </publishername>
 873     </publisher>
 874   </biblioentry>
 875
 876 </bibliography>
 877
 878 </chapter>