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

   1 <?xml version='1.0'?>
   2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
   4 [ ]>
   5
   6 <chapter id="manual.ext.parallel_mode" xreflabel="Parallel Mode">
   7 <?dbhtml filename="parallel_mode.html"?>
   8
   9 <chapterinfo>
  10   <keywordset>
  11     <keyword>
  12       C++
  13     </keyword>
  14     <keyword>
  15       library
  16     </keyword>
  17     <keyword>
  18       parallel
  19     </keyword>
  20   </keywordset>
  21 </chapterinfo>
  22
  23 <title>Parallel Mode</title>
  24
  25 <para> The libstdc++ parallel mode is an experimental parallel
  26 implementation of many algorithms the C++ Standard Library.
  27 </para>
  28
  29 <para>
  30 Several of the standard algorithms, for instance
  31 <code>std::sort</code>, are made parallel using OpenMP
  32 annotations. These parallel mode constructs and can be invoked by
  33 explicit source declaration or by compiling existing sources with a
  34 specific compiler flag.
  35 </para>
  36
  37
  38 <sect1 id="manual.ext.parallel_mode.intro" xreflabel="Intro">
  39   <title>Intro</title>
  40
  41 <para>The following library components in the include
  42 <code>&lt;numeric&gt;</code> are included in the parallel mode:</para>
  43 <itemizedlist>
  44   <listitem><para><code>std::accumulate</code></para></listitem>
  45   <listitem><para><code>std::adjacent_difference</code></para></listitem>
  46   <listitem><para><code>std::inner_product</code></para></listitem>
  47   <listitem><para><code>std::partial_sum</code></para></listitem>
  48 </itemizedlist>
  49
  50 <para>The following library components in the include
  51 <code>&lt;algorithm&gt;</code> are included in the parallel mode:</para>
  52 <itemizedlist>
  53   <listitem><para><code>std::adjacent_find</code></para></listitem>
  54   <listitem><para><code>std::count</code></para></listitem>
  55   <listitem><para><code>std::count_if</code></para></listitem>
  56   <listitem><para><code>std::equal</code></para></listitem>
  57   <listitem><para><code>std::find</code></para></listitem>
  58   <listitem><para><code>std::find_if</code></para></listitem>
  59   <listitem><para><code>std::find_first_of</code></para></listitem>
  60   <listitem><para><code>std::for_each</code></para></listitem>
  61   <listitem><para><code>std::generate</code></para></listitem>
  62   <listitem><para><code>std::generate_n</code></para></listitem>
  63   <listitem><para><code>std::lexicographical_compare</code></para></listitem>
  64   <listitem><para><code>std::mismatch</code></para></listitem>
  65   <listitem><para><code>std::search</code></para></listitem>
  66   <listitem><para><code>std::search_n</code></para></listitem>
  67   <listitem><para><code>std::transform</code></para></listitem>
  68   <listitem><para><code>std::replace</code></para></listitem>
  69   <listitem><para><code>std::replace_if</code></para></listitem>
  70   <listitem><para><code>std::max_element</code></para></listitem>
  71   <listitem><para><code>std::merge</code></para></listitem>
  72   <listitem><para><code>std::min_element</code></para></listitem>
  73   <listitem><para><code>std::nth_element</code></para></listitem>
  74   <listitem><para><code>std::partial_sort</code></para></listitem>
  75   <listitem><para><code>std::partition</code></para></listitem>
  76   <listitem><para><code>std::random_shuffle</code></para></listitem>
  77   <listitem><para><code>std::set_union</code></para></listitem>
  78   <listitem><para><code>std::set_intersection</code></para></listitem>
  79   <listitem><para><code>std::set_symmetric_difference</code></para></listitem>
  80   <listitem><para><code>std::set_difference</code></para></listitem>
  81   <listitem><para><code>std::sort</code></para></listitem>
  82   <listitem><para><code>std::stable_sort</code></para></listitem>
  83   <listitem><para><code>std::unique_copy</code></para></listitem>
  84 </itemizedlist>
  85
  86 <para>The following library components in the includes
  87 <code>&lt;set&gt;</code> and <code>&lt;map&gt;</code> are included in the parallel mode:</para>
  88 <itemizedlist>
  89   <listitem><para><code>std::(multi_)map/set&lt;T&gt;::(multi_)map/set(Iterator begin, Iterator end)</code> (bulk construction)</para></listitem>
  90   <listitem><para><code>std::(multi_)map/set&lt;T&gt;::insert(Iterator begin, Iterator end)</code> (bulk insertion)</para></listitem>
  91 </itemizedlist>
  92
  93 </sect1>
  94
  95 <sect1 id="manual.ext.parallel_mode.semantics" xreflabel="Semantics">
  96   <title>Semantics</title>
  97
  98 <para> The parallel mode STL algorithms are currently not exception-safe,
  99 i. e. user-defined functors must not throw exceptions.
 100 </para>
 101
 102 <para> Since the current GCC OpenMP implementation does not support
 103 OpenMP parallel regions in concurrent threads,
 104 it is not possible to call parallel STL algorithm in
 105 concurrent threads, either.
 106 It might work with other compilers, though.</para>
 107
 108 </sect1>
 109
 110 <sect1 id="manual.ext.parallel_mode.using" xreflabel="Using">
 111   <title>Using</title>
 112
 113 <sect2 id="parallel_mode.using.parallel_mode" xreflabel="using.parallel_mode">
 114   <title>Using Parallel Mode</title>
 115
 116 <para>To use the libstdc++ parallel mode, compile your application with
 117   the compiler flag <code>-D_GLIBCXX_PARALLEL -fopenmp</code>. This
 118   will link in <code>libgomp</code>, the GNU OpenMP <ulink url="http://gcc.gnu.org/onlinedocs/libgomp">implementation</ulink>,
 119   whose presence is mandatory. In addition, hardware capable of atomic
 120   operations is mandatory. Actually activating these atomic
 121   operations may require explicit compiler flags on some targets
 122   (like sparc and x86), such as <code>-march=i686</code>,
 123   <code>-march=native</code> or <code>-mcpu=v9</code>.
 124 </para>
 125
 126 <para>Note that the <code>_GLIBCXX_PARALLEL</code> define may change the
 127   sizes and behavior of standard class templates such as
 128   <code>std::search</code>, and therefore one can only link code
 129   compiled with parallel mode and code compiled without parallel mode
 130   if no instantiation of a container is passed between the two
 131   translation units. Parallel mode functionality has distinct linkage,
 132   and cannot be confused with normal mode symbols.</para>
 133 </sect2>
 134
 135 <sect2 id="manual.ext.parallel_mode.usings" xreflabel="using.specific">
 136   <title>Using Specific Parallel Components</title>
 137
 138 <para>When it is not feasible to recompile your entire application, or
 139   only specific algorithms need to be parallel-aware, individual
 140   parallel algorithms can be made available explicitly. These
 141   parallel algorithms are functionally equivalent to the standard
 142   drop-in algorithms used in parallel mode, but they are available in
 143   a separate namespace as GNU extensions and may be used in programs
 144   compiled with either release mode or with parallel mode. The
 145   following table provides the names and headers of the parallel
 146   algorithms:
 147 </para>
 148
 149 <table frame='all'>
 150 <title>Parallel Algorithms</title>
 151 <tgroup cols='4' align='left' colsep='1' rowsep='1'>
 152 <colspec colname='c1'></colspec>
 153 <colspec colname='c2'></colspec>
 154 <colspec colname='c3'></colspec>
 155 <colspec colname='c4'></colspec>
 156
 157 <thead>
 158   <row>
 159     <entry>Algorithm</entry>
 160     <entry>Header</entry>
 161     <entry>Parallel algorithm</entry>
 162     <entry>Parallel header</entry>
 163   </row>
 164 </thead>
 165
 166 <tbody>
 167   <row>
 168     <entry><function>std::accumulate</function></entry>
 169     <entry><filename class="headerfile">numeric</filename></entry>
 170     <entry><function>__gnu_parallel::accumulate</function></entry>
 171     <entry><filename class="headerfile">parallel/numeric</filename></entry>
 172   </row>
 173   <row>
 174     <entry><function>std::adjacent_difference</function></entry>
 175     <entry><filename class="headerfile">numeric</filename></entry>
 176     <entry><function>__gnu_parallel::adjacent_difference</function></entry>
 177     <entry><filename class="headerfile">parallel/numeric</filename></entry>
 178   </row>
 179   <row>
 180     <entry><function>std::inner_product</function></entry>
 181     <entry><filename class="headerfile">numeric</filename></entry>
 182     <entry><function>__gnu_parallel::inner_product</function></entry>
 183     <entry><filename class="headerfile">parallel/numeric</filename></entry>
 184   </row>
 185   <row>
 186     <entry><function>std::partial_sum</function></entry>
 187     <entry><filename class="headerfile">numeric</filename></entry>
 188     <entry><function>__gnu_parallel::partial_sum</function></entry>
 189     <entry><filename class="headerfile">parallel/numeric</filename></entry>
 190   </row>
 191   <row>
 192     <entry><function>std::adjacent_find</function></entry>
 193     <entry><filename class="headerfile">algorithm</filename></entry>
 194     <entry><function>__gnu_parallel::adjacent_find</function></entry>
 195     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 196   </row>
 197
 198   <row>
 199     <entry><function>std::count</function></entry>
 200     <entry><filename class="headerfile">algorithm</filename></entry>
 201     <entry><function>__gnu_parallel::count</function></entry>
 202     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 203   </row>
 204
 205   <row>
 206     <entry><function>std::count_if</function></entry>
 207     <entry><filename class="headerfile">algorithm</filename></entry>
 208     <entry><function>__gnu_parallel::count_if</function></entry>
 209     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 210   </row>
 211
 212   <row>
 213     <entry><function>std::equal</function></entry>
 214     <entry><filename class="headerfile">algorithm</filename></entry>
 215     <entry><function>__gnu_parallel::equal</function></entry>
 216     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 217   </row>
 218
 219   <row>
 220     <entry><function>std::find</function></entry>
 221     <entry><filename class="headerfile">algorithm</filename></entry>
 222     <entry><function>__gnu_parallel::find</function></entry>
 223     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 224   </row>
 225
 226   <row>
 227     <entry><function>std::find_if</function></entry>
 228     <entry><filename class="headerfile">algorithm</filename></entry>
 229     <entry><function>__gnu_parallel::find_if</function></entry>
 230     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 231   </row>
 232
 233   <row>
 234     <entry><function>std::find_first_of</function></entry>
 235     <entry><filename class="headerfile">algorithm</filename></entry>
 236     <entry><function>__gnu_parallel::find_first_of</function></entry>
 237     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 238   </row>
 239
 240   <row>
 241     <entry><function>std::for_each</function></entry>
 242     <entry><filename class="headerfile">algorithm</filename></entry>
 243     <entry><function>__gnu_parallel::for_each</function></entry>
 244     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 245   </row>
 246
 247   <row>
 248     <entry><function>std::generate</function></entry>
 249     <entry><filename class="headerfile">algorithm</filename></entry>
 250     <entry><function>__gnu_parallel::generate</function></entry>
 251     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 252   </row>
 253
 254   <row>
 255     <entry><function>std::generate_n</function></entry>
 256     <entry><filename class="headerfile">algorithm</filename></entry>
 257     <entry><function>__gnu_parallel::generate_n</function></entry>
 258     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 259   </row>
 260
 261   <row>
 262     <entry><function>std::lexicographical_compare</function></entry>
 263     <entry><filename class="headerfile">algorithm</filename></entry>
 264     <entry><function>__gnu_parallel::lexicographical_compare</function></entry>
 265     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 266   </row>
 267
 268   <row>
 269     <entry><function>std::mismatch</function></entry>
 270     <entry><filename class="headerfile">algorithm</filename></entry>
 271     <entry><function>__gnu_parallel::mismatch</function></entry>
 272     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 273   </row>
 274
 275   <row>
 276     <entry><function>std::search</function></entry>
 277     <entry><filename class="headerfile">algorithm</filename></entry>
 278     <entry><function>__gnu_parallel::search</function></entry>
 279     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 280   </row>
 281
 282   <row>
 283     <entry><function>std::search_n</function></entry>
 284     <entry><filename class="headerfile">algorithm</filename></entry>
 285     <entry><function>__gnu_parallel::search_n</function></entry>
 286     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 287   </row>
 288
 289   <row>
 290     <entry><function>std::transform</function></entry>
 291     <entry><filename class="headerfile">algorithm</filename></entry>
 292     <entry><function>__gnu_parallel::transform</function></entry>
 293     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 294   </row>
 295
 296   <row>
 297     <entry><function>std::replace</function></entry>
 298     <entry><filename class="headerfile">algorithm</filename></entry>
 299     <entry><function>__gnu_parallel::replace</function></entry>
 300     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 301   </row>
 302
 303   <row>
 304     <entry><function>std::replace_if</function></entry>
 305     <entry><filename class="headerfile">algorithm</filename></entry>
 306     <entry><function>__gnu_parallel::replace_if</function></entry>
 307     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 308   </row>
 309
 310   <row>
 311     <entry><function>std::max_element</function></entry>
 312     <entry><filename class="headerfile">algorithm</filename></entry>
 313     <entry><function>__gnu_parallel::max_element</function></entry>
 314     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 315   </row>
 316
 317   <row>
 318     <entry><function>std::merge</function></entry>
 319     <entry><filename class="headerfile">algorithm</filename></entry>
 320     <entry><function>__gnu_parallel::merge</function></entry>
 321     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 322   </row>
 323
 324   <row>
 325     <entry><function>std::min_element</function></entry>
 326     <entry><filename class="headerfile">algorithm</filename></entry>
 327     <entry><function>__gnu_parallel::min_element</function></entry>
 328     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 329   </row>
 330
 331   <row>
 332     <entry><function>std::nth_element</function></entry>
 333     <entry><filename class="headerfile">algorithm</filename></entry>
 334     <entry><function>__gnu_parallel::nth_element</function></entry>
 335     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 336   </row>
 337
 338   <row>
 339     <entry><function>std::partial_sort</function></entry>
 340     <entry><filename class="headerfile">algorithm</filename></entry>
 341     <entry><function>__gnu_parallel::partial_sort</function></entry>
 342     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 343   </row>
 344
 345   <row>
 346     <entry><function>std::partition</function></entry>
 347     <entry><filename class="headerfile">algorithm</filename></entry>
 348     <entry><function>__gnu_parallel::partition</function></entry>
 349     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 350   </row>
 351
 352   <row>
 353     <entry><function>std::random_shuffle</function></entry>
 354     <entry><filename class="headerfile">algorithm</filename></entry>
 355     <entry><function>__gnu_parallel::random_shuffle</function></entry>
 356     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 357   </row>
 358
 359   <row>
 360     <entry><function>std::set_union</function></entry>
 361     <entry><filename class="headerfile">algorithm</filename></entry>
 362     <entry><function>__gnu_parallel::set_union</function></entry>
 363     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 364   </row>
 365
 366   <row>
 367     <entry><function>std::set_intersection</function></entry>
 368     <entry><filename class="headerfile">algorithm</filename></entry>
 369     <entry><function>__gnu_parallel::set_intersection</function></entry>
 370     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 371   </row>
 372
 373   <row>
 374     <entry><function>std::set_symmetric_difference</function></entry>
 375     <entry><filename class="headerfile">algorithm</filename></entry>
 376     <entry><function>__gnu_parallel::set_symmetric_difference</function></entry>
 377     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 378   </row>
 379
 380   <row>
 381     <entry><function>std::set_difference</function></entry>
 382     <entry><filename class="headerfile">algorithm</filename></entry>
 383     <entry><function>__gnu_parallel::set_difference</function></entry>
 384     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 385   </row>
 386
 387   <row>
 388     <entry><function>std::sort</function></entry>
 389     <entry><filename class="headerfile">algorithm</filename></entry>
 390     <entry><function>__gnu_parallel::sort</function></entry>
 391     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 392   </row>
 393
 394   <row>
 395     <entry><function>std::stable_sort</function></entry>
 396     <entry><filename class="headerfile">algorithm</filename></entry>
 397     <entry><function>__gnu_parallel::stable_sort</function></entry>
 398     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 399   </row>
 400
 401   <row>
 402     <entry><function>std::unique_copy</function></entry>
 403     <entry><filename class="headerfile">algorithm</filename></entry>
 404     <entry><function>__gnu_parallel::unique_copy</function></entry>
 405     <entry><filename class="headerfile">parallel/algorithm</filename></entry>
 406   </row>
 407 </tbody>
 408 </tgroup>
 409 </table>
 410
 411 </sect2>
 412
 413 </sect1>
 414
 415 <sect1 id="manual.ext.parallel_mode.design" xreflabel="Design">
 416   <title>Design</title>
 417   <para>
 418   </para>
 419 <sect2 id="manual.ext.parallel_mode.design.intro" xreflabel="Intro">
 420   <title>Interface Basics</title>
 421
 422
 423 <para>All parallel algorithms are intended to have signatures that are
 424 equivalent to the ISO C++ algorithms replaced. For instance, the
 425 <code>std::adjacent_find</code> function is declared as:
 426 </para>
 427 <programlisting>
 428 namespace std
 429 {
 430   template&lt;typename _FIter&gt;
 431     _FIter
 432     adjacent_find(_FIter, _FIter);
 433 }
 434 </programlisting>
 435
 436 <para>
 437 Which means that there should be something equivalent for the parallel
 438 version. Indeed, this is the case:
 439 </para>
 440
 441 <programlisting>
 442 namespace std
 443 {
 444   namespace __parallel
 445   {
 446     template&lt;typename _FIter&gt;
 447       _FIter
 448       adjacent_find(_FIter, _FIter);
 449
 450     ...
 451   }
 452 }
 453 </programlisting>
 454
 455 <para>But.... why the elipses?
 456 </para>
 457
 458 <para> The elipses in the example above represent additional overloads
 459 required for the parallel version of the function. These additional
 460 overloads are used to dispatch calls from the ISO C++ function
 461 signature to the appropriate parallel function (or sequential
 462 function, if no parallel functions are deemed worthy), based on either
 463 compile-time or run-time conditions.
 464 </para>
 465
 466 <para> Compile-time conditions are referred to as "embarrassingly
 467 parallel," and are denoted with the appropriate dispatch object, ie
 468 one of <code>__gnu_parallel::sequential_tag</code>,
 469 <code>__gnu_parallel::parallel_tag</code>,
 470 <code>__gnu_parallel::balanced_tag</code>,
 471 <code>__gnu_parallel::unbalanced_tag</code>,
 472 <code>__gnu_parallel::omp_loop_tag</code>, or
 473 <code>__gnu_parallel::omp_loop_static_tag</code>.
 474 </para>
 475
 476 <para> Run-time conditions depend on the hardware being used, the number
 477 of threads available, etc., and are denoted by the use of the enum
 478 <code>__gnu_parallel::parallelism</code>. Values of this enum include
 479 <code>__gnu_parallel::sequential</code>,
 480 <code>__gnu_parallel::parallel_unbalanced</code>,
 481 <code>__gnu_parallel::parallel_balanced</code>,
 482 <code>__gnu_parallel::parallel_omp_loop</code>,
 483 <code>__gnu_parallel::parallel_omp_loop_static</code>, or
 484 <code>__gnu_parallel::parallel_taskqueue</code>.
 485 </para>
 486
 487 <para> Putting all this together, the general view of overloads for the
 488 parallel algorithms look like this:
 489 </para>
 490 <itemizedlist>
 491    <listitem><para>ISO C++ signature</para></listitem>
 492    <listitem><para>ISO C++ signature + sequential_tag argument</para></listitem>
 493    <listitem><para>ISO C++ signature + parallelism argument</para></listitem>
 494 </itemizedlist>
 495
 496 <para> Please note that the implementation may use additional functions
 497 (designated with the <code>_switch</code> suffix) to dispatch from the
 498 ISO C++ signature to the correct parallel version. Also, some of the
 499 algorithms do not have support for run-time conditions, so the last
 500 overload is therefore missing.
 501 </para>
 502
 503
 504 </sect2>
 505
 506 <sect2 id="manual.ext.parallel_mode.design.tuning" xreflabel="Tuning">
 507   <title>Configuration and Tuning</title>
 508
 509 <para> Some algorithm variants can be enabled/disabled/selected at compile-time.
 510 See <ulink url="latest-doxygen/compiletime__settings_8h.html">
 511 <code>&lt;compiletime_settings.h&gt;</code></ulink> and
 512 See <ulink url="latest-doxygen/compiletime__settings_8h.html">
 513 <code>&lt;features.h&gt;</code></ulink> for details.
 514 </para>
 515
 516 <para>
 517 To specify the number of threads to be used for an algorithm,
 518 use <code>omp_set_num_threads</code>.
 519 To force a function to execute sequentially,
 520 even though parallelism is switched on in general,
 521 add <code>__gnu_parallel::sequential_tag()</code>
 522 to the end of the argument list.
 523 </para>
 524
 525 <para>
 526 Parallelism always incurs some overhead. Thus, it is not
 527 helpful to parallelize operations on very small sets of data.
 528 There are measures to avoid parallelizing stuff that is not worth it.
 529 For each algorithm, a minimum problem size can be stated,
 530 usually using the variable
 531 <code>__gnu_parallel::Settings::[algorithm]_minimal_n</code>.
 532 Please see <ulink url="latest-doxygen/settings_8h.html">
 533 <code>&lt;settings.h&gt;</code></ulink> for details.</para>
 534
 535
 536 </sect2>
 537
 538 <sect2 id="manual.ext.parallel_mode.design.impl" xreflabel="Impl">
 539   <title>Implementation Namespaces</title>
 540
 541 <para> One namespace contain versions of code that are explicitly sequential:
 542 <code>__gnu_serial</code>.
 543 </para>
 544
 545 <para> Two namespaces contain the parallel mode:
 546 <code>std::__parallel</code> and <code>__gnu_parallel</code>.
 547 </para>
 548
 549 <para> Parallel implementations of standard components, including
 550 template helpers to select parallelism, are defined in <code>namespace
 551 std::__parallel</code>. For instance, <code>std::transform</code> from
 552 &lt;algorithm&gt; has a parallel counterpart in
 553 <code>std::__parallel::transform</code> from
 554 &lt;parallel/algorithm&gt;. In addition, these parallel
 555 implementations are injected into <code>namespace
 556 __gnu_parallel</code> with using declarations.
 557 </para>
 558
 559 <para> Support and general infrastructure is in <code>namespace
 560 __gnu_parallel</code>.
 561 </para>
 562
 563 <para> More information, and an organized index of types and functions
 564 related to the parallel mode on a per-namespace basis, can be found in
 565 the generated source documentation.
 566 </para>
 567
 568 </sect2>
 569
 570 </sect1>
 571
 572 <sect1 id="manual.ext.parallel_mode.test" xreflabel="Testing">
 573   <title>Testing</title>
 574
 575   <para>
 576     Both the normal conformance and regression tests and the
 577     supplemental performance tests work.
 578   </para>
 579
 580   <para>
 581     To run the conformance and regression tests with the parallel mode
 582     active,
 583   </para>
 584
 585   <screen>
 586   <userinput>make check-parallel</userinput>
 587   </screen>
 588
 589   <para>
 590     The log and summary files for conformance testing are in the
 591     <code>testsuite/parallel</code> directory.
 592   </para>
 593
 594   <para>
 595     To run the performance tests with the parallel mode active,
 596   </para>
 597
 598   <screen>
 599   <userinput>check-performance-parallel</userinput>
 600   </screen>
 601
 602   <para>
 603     The result file for performance testing are in the
 604     <code>testsuite</code> directory, in the file
 605     <code>libstdc++_performance.sum</code>. In addition, the
 606     policy-based containers have their own visualizations, which have
 607     additional software dependencies than the usual bare-boned text
 608     file, and can be generated by using the <code>make
 609     doc-performance</code> rule in the testsuite's Makefile.
 610 </para>
 611 </sect1>
 612
 613 <bibliography id="parallel_mode.biblio" xreflabel="parallel_mode.biblio">
 614 <title>Bibliography</title>
 615
 616   <biblioentry>
 617     <title>
 618       Parallelization of Bulk Operations for STL Dictionaries
 619     </title>
 620
 621     <author>
 622       <firstname>Johannes</firstname>
 623       <surname>Singler</surname>
 624     </author>
 625     <author>
 626       <firstname>Leonor</firstname>
 627       <surname>Frias</surname>
 628     </author>
 629
 630     <copyright>
 631       <year>2007</year>
 632       <holder></holder>
 633     </copyright>
 634
 635     <publisher>
 636       <publishername>
 637         Workshop on Highly Parallel Processing on a Chip (HPPC) 2007. (LNCS)
 638       </publishername>
 639     </publisher>
 640   </biblioentry>
 641
 642   <biblioentry>
 643     <title>
 644       The Multi-Core Standard Template Library
 645     </title>
 646
 647     <author>
 648       <firstname>Johannes</firstname>
 649       <surname>Singler</surname>
 650     </author>
 651     <author>
 652       <firstname>Peter</firstname>
 653       <surname>Sanders</surname>
 654     </author>
 655     <author>
 656       <firstname>Felix</firstname>
 657       <surname>Putze</surname>
 658     </author>
 659
 660     <copyright>
 661       <year>2007</year>
 662       <holder></holder>
 663     </copyright>
 664
 665     <publisher>
 666       <publishername>
 667          Euro-Par 2007: Parallel Processing. (LNCS 4641)
 668       </publishername>
 669     </publisher>
 670   </biblioentry>
 671
 672 </bibliography>
 673
 674 </chapter>