From: Brian Pane <brianp@apache.org>
Date: Fri, 3 Jan 2003 23:12:56 +0000 (+0000)
Subject: added some documentation about MPM selection and atomic operations
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=cfe6a823a6a2902a9eea7ca0fb64261f7703d213;p=apache

added some documentation about MPM selection and atomic operations


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@98160 13f79535-47bb-0310-9956-ffa450edef68
---

diff --git a/docs/manual/misc/perf-tuning.html.en b/docs/manual/misc/perf-tuning.html.en
index 38421e654b..41a22b052e 100644
--- a/docs/manual/misc/perf-tuning.html.en
+++ b/docs/manual/misc/perf-tuning.html.en
@@ -386,6 +386,100 @@
 
     
 
+    <h3>Choosing an MPM</h3>
+
+      
+
+      <p>Apache 2.x supports pluggable concurrency models, called
+      <a href="../mpm.html">Multi-Processing Modules</a> (MPMs).
+      When building Apache, you must choose an MPM to use.  There
+      are platform-specific MPMs for some platforms:
+      <code class="module"><a href="../mod/beos.html">beos</a></code>, <code class="module"><a href="../mod/mpm_netware.html">mpm_netware</a></code>,
+      <code class="module"><a href="../mod/mpmt_os2.html">mpmt_os2</a></code>, and <code class="module"><a href="../mod/mpm_winnt.html">mpm_winnt</a></code>.  For
+      general Unix-type systems, there are several MPMs from which
+      to choose.  The choice of MPM can affect the speed and scalability
+      of the httpd:</p>
+
+      <ul>
+
+        <li>The <code class="module"><a href="../mod/worker.html">worker</a></code> MPM uses multiple child
+        processes with many threads each.  Each thread handles
+        one connection at a time.  Worker generally is a good
+        choice for high-traffic servers because it has a smaller
+        memory footprint than the prefork MPM.</li>
+
+        <li>The <code class="module"><a href="../mod/prefork.html">prefork</a></code> MPM uses multiple child
+        processes with one thread each.  Each process handles
+        one connection at a time.  On many systems, prefork is
+        comparable in speed to worker, but it uses more memory.
+        Prefork's threadless design has advantages over worker
+        in some situations: it can be used with non-thread-safe
+        third-party modules, and it is easier to debug on platforms
+        with poor thread debugging support.</li>
+
+      </ul>
+
+      <p>For more information on these and other MPMs, please
+      see the MPM <a href="../mpm.html">documentation</a>.</p>
+
+    
+
+    <h3>Atomic Operations</h3>
+
+      
+
+      <p>Some modules, such as <code class="module"><a href="../mod/mod_cache.html">mod_cache</a></code> and
+      recent development builds of the worker MPM, use APR's
+      atomic API.  This API provides atomic operations that can
+      be used for lightweight thread synchronization.</p>
+
+      <p>By default, APR implements these operations using the
+      most efficient mechanism available on each target
+      OS/CPU platform.  Many modern CPUs, for example, have
+      an instruction that does an atomic compare-and-swap (CAS)
+      operation in hardware.  On some platforms, however, APR
+      defaults to a slower, mutex-based implementation of the
+      atomic API in order to ensure compatibility with older
+      CPU models that lack such instructions.  If you are
+      building Apache for one of these platforms, and you plan
+      to run only on newer CPUs, you can select a faster atomic
+      implementation at build time by configuring Apache with
+      the <code>--enable-nonportable-atomics</code> option:</p>
+
+      <div class="example"><p><code>
+        ./buildconf<br />
+        ./configure --with-mpm=worker --enable-nonportable-atomics=yes
+      </code></p></div>
+
+      <p>The <code>--enable-nonportable-atomics</code> option is
+      relevant for the following platforms:</p>
+
+      <ul>
+
+        <li>Solaris on SPARC<br />
+            By default, APR uses mutex-based atomics on Solaris/SPARC.
+            If you configure with <code>--enable-nonportable-atomics</code>,
+            however, APR generates code that uses a SPARC v8plus opcode for
+            fast hardware compare-and-swap.  If you configure Apache with
+            this option, the atomic operations will be more efficient
+            (allowing for lower CPU utilization and higher concurrency),
+            but the resulting executable will run only on UltraSPARC
+            chips.
+        </li>
+
+        <li>Linux on x86<br />
+            By default, APR uses mutex-based atomics on Linux.  If you
+            configure with <code>--enable-nonportable-atomics</code>,
+            however, APR generates code that uses a 486 opcode for fast
+            hardware compare-and-swap.  This will result in more efficient
+            atomic operations, but the resulting executable will run only
+            on 486 and later chips (and not on 386).
+        </li>
+
+      </ul>
+
+    
+
     <h3>mod_status and ExtendedStatus On</h3>
 
       
diff --git a/docs/manual/misc/perf-tuning.xml b/docs/manual/misc/perf-tuning.xml
index 5c7db1f20f..115edd6635 100644
--- a/docs/manual/misc/perf-tuning.xml
+++ b/docs/manual/misc/perf-tuning.xml
@@ -402,6 +402,100 @@
 
     <title>Compile-Time Configuration Issues</title>
 
+    <section>
+
+      <title>Choosing an MPM</title>
+
+      <p>Apache 2.x supports pluggable concurrency models, called
+      <a href="../mpm.html">Multi-Processing Modules</a> (MPMs).
+      When building Apache, you must choose an MPM to use.  There
+      are platform-specific MPMs for some platforms:
+      <module>beos</module>, <module>mpm_netware</module>,
+      <module>mpmt_os2</module>, and <module>mpm_winnt</module>.  For
+      general Unix-type systems, there are several MPMs from which
+      to choose.  The choice of MPM can affect the speed and scalability
+      of the httpd:</p>
+
+      <ul>
+
+        <li>The <module>worker</module> MPM uses multiple child
+        processes with many threads each.  Each thread handles
+        one connection at a time.  Worker generally is a good
+        choice for high-traffic servers because it has a smaller
+        memory footprint than the prefork MPM.</li>
+
+        <li>The <module>prefork</module> MPM uses multiple child
+        processes with one thread each.  Each process handles
+        one connection at a time.  On many systems, prefork is
+        comparable in speed to worker, but it uses more memory.
+        Prefork's threadless design has advantages over worker
+        in some situations: it can be used with non-thread-safe
+        third-party modules, and it is easier to debug on platforms
+        with poor thread debugging support.</li>
+
+      </ul>
+
+      <p>For more information on these and other MPMs, please
+      see the MPM <a href="../mpm.html">documentation</a>.</p>
+
+    </section>
+
+    <section>
+
+      <title>Atomic Operations</title>
+
+      <p>Some modules, such as <module>mod_cache</module> and
+      recent development builds of the worker MPM, use APR's
+      atomic API.  This API provides atomic operations that can
+      be used for lightweight thread synchronization.</p>
+
+      <p>By default, APR implements these operations using the
+      most efficient mechanism available on each target
+      OS/CPU platform.  Many modern CPUs, for example, have
+      an instruction that does an atomic compare-and-swap (CAS)
+      operation in hardware.  On some platforms, however, APR
+      defaults to a slower, mutex-based implementation of the
+      atomic API in order to ensure compatibility with older
+      CPU models that lack such instructions.  If you are
+      building Apache for one of these platforms, and you plan
+      to run only on newer CPUs, you can select a faster atomic
+      implementation at build time by configuring Apache with
+      the <code>--enable-nonportable-atomics</code> option:</p>
+
+      <example>
+        ./buildconf<br />
+        ./configure --with-mpm=worker --enable-nonportable-atomics=yes
+      </example>
+
+      <p>The <code>--enable-nonportable-atomics</code> option is
+      relevant for the following platforms:</p>
+
+      <ul>
+
+        <li>Solaris on SPARC<br />
+            By default, APR uses mutex-based atomics on Solaris/SPARC.
+            If you configure with <code>--enable-nonportable-atomics</code>,
+            however, APR generates code that uses a SPARC v8plus opcode for
+            fast hardware compare-and-swap.  If you configure Apache with
+            this option, the atomic operations will be more efficient
+            (allowing for lower CPU utilization and higher concurrency),
+            but the resulting executable will run only on UltraSPARC
+            chips.
+        </li>
+
+        <li>Linux on x86<br />
+            By default, APR uses mutex-based atomics on Linux.  If you
+            configure with <code>--enable-nonportable-atomics</code>,
+            however, APR generates code that uses a 486 opcode for fast
+            hardware compare-and-swap.  This will result in more efficient
+            atomic operations, but the resulting executable will run only
+            on 486 and later chips (and not on 386).
+        </li>
+
+      </ul>
+
+    </section>
+
     <section>
 
       <title>mod_status and ExtendedStatus On</title>