2008-06-24 Benjamin Kosnik <bkoz@redhat.com>

[pf3gnuchains/gcc-fork.git] / libstdc++-v3 / doc / xml / manual / parallel_mode.xml

diff --git a/libstdc++-v3/doc/xml/manual/parallel_mode.xml b/libstdc++-v3/doc/xml/manual/parallel_mode.xml
index faea5a9..7cb2a05 100644 (file)
--- a/libstdc++-v3/doc/xml/manual/parallel_mode.xml
+++ b/libstdc++-v3/doc/xml/manual/parallel_mode.xml
@@ -105,18 +105,45 @@ It might work with other compilers, though.</para>
 <sect1 id="manual.ext.parallel_mode.using" xreflabel="Using">
   <title>Using</title>
 
+<sect2 id="parallel_mode.using.prereq_flags" xreflabel="using.prereq_flags">
+  <title>Prerequisite Compiler Flags</title>
+
+<para>
+  Any use of parallel functionality requires additional compiler
+  and runtime support, in particular support for OpenMP. Adding this support is
+  not difficult: just compile your application with the compiler
+  flag <literal>-fopenmp</literal>. This will link
+  in <code>libgomp</code>, the GNU
+  OpenMP <ulink url="http://gcc.gnu.org/onlinedocs/libgomp/">implementation</ulink>,
+  whose presence is mandatory. 
+</para>
+
+<para>
+In addition, hardware that supports atomic operations and a compiler
+  capable of producing atomic operations is mandatory: GCC defaults to no
+  support for atomic operations on some common hardware
+  architectures. Activating atomic operations may require explicit
+  compiler flags on some targets (like sparc and x86), such
+  as <literal>-march=i686</literal>,
+  <literal>-march=native</literal> or <literal>-mcpu=v9</literal>. See
+  the GCC manual for more information.
+</para>
+
+</sect2>
+
 <sect2 id="parallel_mode.using.parallel_mode" xreflabel="using.parallel_mode">
   <title>Using Parallel Mode</title>
 
 <para>
   To use the libstdc++ parallel mode, compile your application with
-  the compiler flag <constant>-D_GLIBCXX_PARALLEL -fopenmp</constant>. This
-  will link in <code>libgomp</code>, the GNU OpenMP <ulink url="http://gcc.gnu.org/onlinedocs/libgomp/">implementation</ulink>,
-  whose presence is mandatory. In addition, hardware capable of atomic
-  operations is mandatory. Actually activating these atomic
-  operations may require explicit compiler flags on some targets
-  (like sparc and x86), such as <literal>-march=i686</literal>,
-  <literal>-march=native</literal> or <literal>-mcpu=v9</literal>.
+  the prerequisite flags as detailed above, and in addition
+  add <constant>-D_GLIBCXX_PARALLEL</constant>. This will convert all
+  use of the standard (sequential) algorithms to the appropriate parallel
+  equivalents. Please note that this doesn't necessarily mean that
+  everything will end up being executed in a parallel manner, but
+  rather that the heuristics and settings coded into the parallel
+  versions will be used to determine if all, some, or no algorithms
+  will be executed using parallel variants.
 </para>
 
 <para>Note that the <constant>_GLIBCXX_PARALLEL</constant> define may change the
@@ -129,7 +156,7 @@ It might work with other compilers, though.</para>
 </para>
 </sect2>
 
-<sect2 id="manual.ext.parallel_mode.usings" xreflabel="using.specific">
+<sect2 id="parallel_mode.using.specific" xreflabel="using.specific">
   <title>Using Specific Parallel Components</title>
 
 <para>When it is not feasible to recompile your entire application, or
@@ -138,9 +165,38 @@ It might work with other compilers, though.</para>
   parallel algorithms are functionally equivalent to the standard
   drop-in algorithms used in parallel mode, but they are available in
   a separate namespace as GNU extensions and may be used in programs
-  compiled with either release mode or with parallel mode. The
-  following table provides the names and headers of the parallel
-  algorithms:
+  compiled with either release mode or with parallel mode.
+</para>
+
+
+<para>An example of using a parallel version
+of <function>std::sort</function>, but no other parallel algorithms, is:
+</para>
+
+<programlisting>
+#include &lt;vector&gt;
+#include &lt;parallel/algorithm&gt;
+
+int main()
+{
+  std::vector&lt;int&gt; v(100);
+
+  // ...
+
+  // Explicitly force a call to parallel sort.
+  __gnu_parallel::sort(v.begin(), v.end());
+  return 0;
+}
+</programlisting>
+
+<para>
+Then compile this code with the prerequisite compiler flags
+(<literal>-fopenmp</literal> and any necessary architecture-specific
+flags for atomic operations.)
+</para>
+
+<para> The following table provides the names and headers of all the
+  parallel algorithms that can be used in a similar manner:
 </para>
 
 <table frame='all'>
@@ -416,7 +472,6 @@ It might work with other compilers, though.</para>
 <sect2 id="manual.ext.parallel_mode.design.intro" xreflabel="Intro">
   <title>Interface Basics</title>
 
-
 <para>
 All parallel algorithms are intended to have signatures that are
 equivalent to the ISO C++ algorithms replaced. For instance, the