re PR libstdc++/33487 (parallel v3: more functions not in right namespace)

2007-10-06  Benjamin Kosnik  <bkoz@redhat.com>

	PR libstdc++/33487
	* include/parallel/algorithmfwd.h (for_each, generate, generate_n,
	transform, replace, replace_if, max_element, min_element, count,
	count_if): Consistently construct overloads.
	* include/parallel/numericfwd.h (accumulate, adjacent_difference,
	inner_product): Same.
	* include/parallel/algobase.h: Same.
	* include/parallel/algo.h: Same.
	* include/parallel/numeric: Same.

	* include/bits/algorithmfwd.h: Correct find_end placement.

	* docs/html/parallel_mode.html: Document some of the interface
	conventions.

	* include/parallel/search.h (calc_borders): Only use operator ==.
	
	* include/parallel/algorithmfwd.h: Move __gnu_sequential bits to...
	* include/parallel/tags.h: ...here, and use a using directive.

	* include/parallel/random_shuffle.h: Include stl_numeric. Qualify
	uses of partial_num with __gnu_sequential.

	* include/parallel/tree.h: Formatting.

From-SVN: r129054

1 files changed, 92 insertions, 9 deletions

diff --git a/libstdc++-v3/docs/html/parallel_mode.html b/libstdc++-v3/docs/html/parallel_mode.html
index 74db8ca..5843ae8 100644
--- a/libstdc++-v3/docs/html/parallel_mode.html
+++ b/libstdc++-v3/docs/html/parallel_mode.html
@@ -388,26 +388,109 @@ computing.</p>
 <p> Something about compile-time settings and configuration, ie using
 <code>__gnu_parallel::Settings</code>. XXX Up in the air.</p>
 
-<h4 class="left">Interface basics and relevant namespaces</h4>
+<h4 class="left">Interface basics and general design</h4>
+
+<p>All parallel algorithms are intended to have signatures that are
+equivalent to the ISO C++ algorithms replaced. For instance, the
+<code>std::adjacent_find</code> function is declared as:
+
+<pre>
+namespace std
+{
+  template&lt;typename _FIter&gt;
+    _FIter
+    adjacent_find(_FIter, _FIter);
+}
+</pre>
+
+Which means that there should be something equivalent for the parallel
+version. Indeed, this is the case:
+
+<pre>
+namespace std
+{
+  namespace __parallel
+  {
+    template&lt;typename _FIter&gt;
+      _FIter
+      adjacent_find(_FIter, _FIter);
+
+    ...
+  }
+}
+</pre>
+
+<p>But.... why the elipses?
+</p>
 
-<p> Two namespaces contain the parallel mode:
-<code>std::__parallel</code> and <code>__gnu_parallel</code>. 
+<p> The elipses in the example above represent additional overloads
+required for the parallel version of the function. These additional
+overloads are used to dispatch calls from the ISO C++ function
+signature to the appropriate parallel function (or sequential
+function, if no parallel functions are deemed worthy), based on either
+compile-time or run-time conditions.
+</p>
+
+<p> Compile-time conditions are referred to as "embarrassingly
+parallel," and are denoted with the appropriate dispatch object, ie
+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>.
 </p>
 
+<p> 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>.
+</p>
+
+<p> Putting all this together, the general view of overloads for the
+parallel algorithms look like this:
+<p>
+<ul>
+   <li>ISO C++ signature</li>
+   <li>ISO C++ signature + sequential_tag argument</li>
+   <li>ISO C++ signature + parallelism argument</li>
+</ul>
+
+<p> Please note that the implementation may use additional functions
+(designated with the <code>_switch</code> suffix) to dispatch from the
+ISO C++ signature to the correct parallel version. Also, some of the
+algorithms do not have support for run-time conditions, so the last
+overload is therefore missing.
+</p>
+
+
+<h4 class="left">Relevant namespaces</h4>
+
 <p> One namespace contain versions of code that are explicitly sequential:
 <code>__gnu_serial</code>.
 </p>
 
-<p> Parallel implementations of the sequential standard components are
-defined in <code>namespace std::__parallel</code>. For instance,
-<code>std::transform</code> from &lt;algorithm&gt; has a parallel
-counterpart in <code>std::__parallel::transform</code> from
+<p> Two namespaces contain the parallel mode:
+<code>std::__parallel</code> and <code>__gnu_parallel</code>. 
+</p>
+
+<p> Parallel implementations of standard components, including
+template helpers to select parallelism, are defined in <code>namespace
+std::__parallel</code>. For instance, <code>std::transform</code> from
+&lt;algorithm&gt; has a parallel counterpart in
+<code>std::__parallel::transform</code> from
 &lt;parallel/algorithm&gt;. In addition, these parallel
 implementatations are injected into <code>namespace
-__gnu_parallel</code> with using declarations. 
+__gnu_parallel</code> with using declarations.
 </p>
 
-<p> Support and infrastructure is in <code>namespace __gnu_parallel</code>.
+<p> Support and general infrastructure is in <code>namespace
+__gnu_parallel</code>.
 </p>
 
 <p> More information, and an organized index of types and functions