<para> The parallel mode STL algorithms are currently not exception-safe,
i.e. user-defined functors must not throw exceptions.
+Also, the order of execution is not guaranteed for some functions, of course.
+Therefore, user-defined functors should not have any concurrent side effects.
</para>
<para> Since the current GCC OpenMP implementation does not support
compile-time or run-time conditions.
</para>
-<para> Compile-time conditions are referred to as "embarrassingly
-parallel," and are denoted with the appropriate dispatch object, i.e.,
-one of <code>__gnu_parallel::sequential_tag</code>,
-<code>__gnu_parallel::parallel_tag</code>,
-<code>__gnu_parallel::balanced_tag</code>,
-<code>__gnu_parallel::unbalanced_tag</code>,
-<code>__gnu_parallel::omp_loop_tag</code>, or
-<code>__gnu_parallel::omp_loop_static_tag</code>.
-</para>
-
-<para> Run-time conditions depend on the hardware being used, the number
-of threads available, etc., and are denoted by the use of the enum
-<code>__gnu_parallel::parallelism</code>. Values of this enum include
-<code>__gnu_parallel::sequential</code>,
-<code>__gnu_parallel::parallel_unbalanced</code>,
-<code>__gnu_parallel::parallel_balanced</code>,
-<code>__gnu_parallel::parallel_omp_loop</code>,
-<code>__gnu_parallel::parallel_omp_loop_static</code>, or
-<code>__gnu_parallel::parallel_taskqueue</code>.
-</para>
+<para> The available signature options are specific for the different
+algorithms/algorithm classes.</para>
-<para> Putting all this together, the general view of overloads for the
-parallel algorithms look like this:
+<para> The general view of overloads for the parallel algorithms look like this:
</para>
<itemizedlist>
<listitem><para>ISO C++ signature</para></listitem>
<listitem><para>ISO C++ signature + sequential_tag argument</para></listitem>
- <listitem><para>ISO C++ signature + parallelism argument</para></listitem>
+ <listitem><para>ISO C++ signature + algorithm-specific tag type
+ (several signatures)</para></listitem>
</itemizedlist>
<para> Please note that the implementation may use additional functions
</para>
<para>
-To specify the number of threads to be used for an algorithm, use the
-function <function>omp_set_num_threads</function>. An example:
+To specify the number of threads to be used for the algorithms globally,
+use the function <function>omp_set_num_threads</function>. An example:
</para>
<programlisting>
omp_set_dynamic(false);
omp_set_num_threads(threads_wanted);
- // Do work.
+ // Call parallel mode algorithms.
return 0;
}
</programlisting>
+<para>
+ Some algorithms allow the number of threads being set for a particular call,
+ by augmenting the algorithm variant.
+ See the next section for further information.
+</para>
+
<para>
Other parts of the runtime environment able to be manipulated include
nested parallelism (<function>omp_set_nested</function>), schedule kind
To force an algorithm to execute sequentially, even though parallelism
is switched on in general via the macro <constant>_GLIBCXX_PARALLEL</constant>,
add <classname>__gnu_parallel::sequential_tag()</classname> to the end
-of the algorithm's argument list, or explicitly qualify the algorithm
-with the <code>__gnu_parallel::</code> namespace.
+of the algorithm's argument list.
</para>
<para>
</programlisting>
<para>
-or
+Some parallel algorithm variants can be excluded from compilation by
+preprocessor defines. See the doxygen documentation on
+<code>compiletime_settings.h</code> and <code>features.h</code> for details.
</para>
-<programlisting>
-__gnu_serial::sort(v.begin(), v.end());
-</programlisting>
+<para>
+For some algorithms, the desired variant can be chosen at compile-time by
+appending a tag object. The available options are specific to the particular
+algorithm (class).
+</para>
-<para>
-In addition, some parallel algorithm variants can be enabled/disabled/selected
-at compile-time.
+<para>
+For the "embarrassingly parallel" algorithms, there is only one "tag object
+type", the enum _Parallelism.
+It takes one of the following values,
+<code>__gnu_parallel::parallel_tag</code>,
+<code>__gnu_parallel::balanced_tag</code>,
+<code>__gnu_parallel::unbalanced_tag</code>,
+<code>__gnu_parallel::omp_loop_tag</code>,
+<code>__gnu_parallel::omp_loop_static_tag</code>.
+This means that the actual parallelization strategy is chosen at run-time.
+(Choosing the variants at compile-time will come soon.)
</para>
<para>
-See <ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00446.html"><filename class="headerfile">compiletime_settings.h</filename></ulink> and
-See <ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00505.html"><filename class="headerfile">features.h</filename></ulink> for details.
+For the <code>sort</code> and <code>stable_sort</code> algorithms, there are
+several possible choices,
+<code>__gnu_parallel::parallel_tag</code>,
+<code>__gnu_parallel::default_parallel_tag</code>,
+<code>__gnu_parallel::multiway_mergesort_tag</code>,
+<code>__gnu_parallel::multiway_mergesort_exact_tag</code>,
+<code>__gnu_parallel::multiway_mergesort_sampling_tag</code>,
+<code>__gnu_parallel::quicksort_tag</code>,
+<code>__gnu_parallel::balanced_quicksort_tag</code>.
+Multiway mergesort comes with two splitting strategies for merging, therefore
+the extra choice. If non is chosen, the default splitting strategy is selected.
+<code>__gnu_parallel::default_parallel_tag</code> chooses the default parallel
+sorting algorithm at runtime. <code>__gnu_parallel::parallel_tag</code>
+postpones the decision to runtime (see next section).
+The quicksort options cannot be used for <code>stable_sort</code>.
+For all tags, the number of threads desired for this call can optionally be
+passed to the tag's constructor.
</para>
+
</sect3>
<sect3 id="parallel_mode.design.tuning.settings" xreflabel="_Settings">
<para>
First off, the choice of parallelization strategy: serial, parallel,
-or implementation-deduced. This corresponds
+or heuristically deduced. This corresponds
to <code>__gnu_parallel::_Settings::algorithm_strategy</code> and is a
value of enum <type>__gnu_parallel::_AlgorithmStrategy</type>
type. Choices
include: <type>heuristic</type>, <type>force_sequential</type>,
-and <type>force_parallel</type>. The default is
-implementation-deduced, i.e. <type>heuristic</type>.
+and <type>force_parallel</type>. The default is <type>heuristic</type>.
</para>
<para>
-Next, the sub-choices for algorithm implementation. Specific
-algorithms like <function>find</function> or <function>sort</function>
+Next, the sub-choices for algorithm variant, if not fixed at compile-time.
+Specific algorithms like <function>find</function> or <function>sort</function>
can be implemented in multiple ways: when this is the case,
a <classname>__gnu_parallel::_Settings</classname> member exists to
pick the default strategy. For
threshold variable follows the following naming scheme:
<code>__gnu_parallel::_Settings::[algorithm]_minimal_n</code>. So,
for <function>fill</function>, the threshold variable
-is <code>__gnu_parallel::_Settings::fill_minimal_n</code>
+is <code>__gnu_parallel::_Settings::fill_minimal_n</code>,
</para>
<para>
via <code>__gnu_parallel::_Settings::L1_cache_size</code> and friends.
</para>
+<para>
+</para>
+
<para>
All these configuration variables can be changed by the user, if
-desired. Please
-see <ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00640.html"><filename class="headerfile">settings.h</filename></ulink>
+desired.
+There exists one global instance of the class <classname>_Settings</classname>,
+i. e. it is a singleton. It can be read and written by calling
+<code>__gnu_parallel::_Settings::get</code> and
+<code>__gnu_parallel::_Settings::set</code>, respectively.
+Please note that the first call return a const object, so direct manipulation
+is forbidden.
+See <ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00640.html">
+ <filename class="headerfile">settings.h</filename></ulink>
for complete details.
</para>
projects / gcc.git / commitdiff