From a17fd1388f1c1517a771239fa83a72bb32f5396f Mon Sep 17 00:00:00 2001
From: Jeff Trawick <trawick@apache.org>
Date: Mon, 12 Jan 2004 16:22:35 +0000
Subject: [PATCH] update worker doc to mention that

. a potentially large number of child processes can be in
  termination state

. ServerLimit/ThreadLimit should be coded before other worker
  MPM directives which control processes/threads


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@102295 13f79535-47bb-0310-9956-ffa450edef68
---
 docs/manual/mod/worker.html.en | 62 ++++++++++++++++++++++---------
 docs/manual/mod/worker.xml     | 68 ++++++++++++++++++++++++----------
 2 files changed, 93 insertions(+), 37 deletions(-)

diff --git a/docs/manual/mod/worker.html.en b/docs/manual/mod/worker.html.en
index dc1af0f352..faffd70b8a 100644
--- a/docs/manual/mod/worker.html.en
+++ b/docs/manual/mod/worker.html.en
@@ -79,15 +79,11 @@ uses</a></li>
 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="section">
 <h2><a name="how-it-works" id="how-it-works">How it Works</a></h2>
-    <p>Each process has a fixed
-    number of threads. The server adjusts to handle load by
-    increasing or decreasing the number of processes.</p>
-
-    <p>A single control process is responsible for launching child
-    processes. Each child process creates a fixed number of threads as
-    specified in the <code class="directive"><a href="../mod/mpm_common.html#threadsperchild">ThreadsPerChild</a></code> directive. The
-    individual threads then listen for connections and serve them when
-    they arrive.</p>
+    <p>A single control process (the parent) is responsible for launching 
+    child processes. Each child process creates a fixed number of server
+    threads as specified in the <code class="directive"><a href="../mod/mpm_common.html#threadsperchild">ThreadsPerChild</a></code> directive, as well
+    as a listener thread which listens for connections and passes them
+    to a server thread for processing when they arrive.</p>
 
     <p>Apache always tries to maintain a pool of <dfn>spare</dfn> or
     idle server threads, which stand ready to serve incoming
@@ -102,23 +98,55 @@ uses</a></li>
     these directives from their default values. The maximum number of
     clients that may be served simultaneously (i.e., the maximum total
     number of threads in all processes) is determined by the
-    <code class="directive"><a href="../mod/mpm_common.html#maxclients">MaxClients</a></code> directive,
-    while the maximum number of processes that can be launched is set
-    by the <code class="directive"><a href="../mod/mpm_common.html#serverlimit">ServerLimit</a></code>
-    directive.  <code class="directive"><a href="../mod/mpm_common.html#serverlimit">ServerLimit</a></code>
-    multiplied by <code class="directive"><a href="../mod/mpm_common.html#threadsperchild">ThreadsPerChild</a></code> must be greater
-    than or equal to <code class="directive"><a href="../mod/mpm_common.html#maxclients">MaxClients</a></code></p>
+    <code class="directive"><a href="../mod/mpm_common.html#maxclients">MaxClients</a></code> directive.
+    The maximum number of active child processes is determined by
+    the <code class="directive"><a href="../mod/mpm_common.html#maxclients">MaxClients</a></code>
+    directive divided by the <code class="directive"><a href="../mod/mpm_common.html#&#10;    threadsperchild">
+    ThreadsPerChild</a></code> directive.</p>
+
+    <p>Two directives set hard limits on the number of active child
+    processes and the number of server threads in a child process,
+    and can only be changed by fully stopping the server and then 
+    starting it again.  <code class="directive"><a href="../mod/mpm_common.html#serverlimit&#10;    ">ServerLimit
+    </a></code> is a hard limit on the number of active child 
+    processes, and must be greater than or equal to the 
+    <code class="directive"><a href="../mod/mpm_common.html#maxclients">MaxClients</a></code>
+    directive divided by the <code class="directive"><a href="../mod/mpm_common.html#&#10;    threadsperchild">
+    ThreadsPerChild</a></code> directive.  
+    <code class="directive"><a href="../mod/mpm_common.html#threadlimit">ThreadLimit</a></code> is a hard
+    limit of the number of server threads, and must be greater than
+    or equal to the <code class="directive"><a href="../mod/mpm_common.html#threadsperchild">ThreadsPerChild</a></code> directive.  If 
+    non-default values are specified for these directives, they 
+    should appear before other <code class="module"><a href="../mod/worker.html">worker</a></code> directives.</p>
+
+    <p>In addition to a the set of active child processes, there may 
+    be additional child processes which are terminating but where at
+    least one server thread is still handling an existing client
+    connection.  Up to <code class="directive"><a href="../mod/mpm_common.html#maxclient">MaxClient</a></code> terminating processes 
+    may be present, though the actual number can be expected to be 
+    much smaller.  This behavior can be avoided by disabling the 
+    termination of individual child processes, which is achieved by 
+    the following:</p>
+
+    <ul>
+      <li>set the value of <code class="directive"><a href="../mod/mpm_common.html#&#10;      maxrequestsperchild">
+      MaxRequestsPerChild</a></code> to zero</li>
+
+      <li>set the value of <code class="directive"><a href="../mod/mpm_common.html#&#10;      maxsparethreads">
+      MaxSpareThreads</a></code> to the same value as
+      <code class="directive"><a href="../mod/mpm_common.html#maxclients">MaxClients</a></code></li>
+    </ul>
 
     <p>A typical configuration of the process-thread controls in
     the <code class="module"><a href="../mod/worker.html">worker</a></code> MPM could look as follows:</p>
 
     <div class="example"><p><code>
+      ServerLimit         16<br />
       StartServers         2<br />
       MaxClients         150<br />
       MinSpareThreads     25<br />
       MaxSpareThreads     75<br />
-      ThreadsPerChild     25<br />
-      ServerLimit         16
+      ThreadsPerChild     25
     </code></p></div>
 
     <p>While the parent process is usually started as <code>root</code>
diff --git a/docs/manual/mod/worker.xml b/docs/manual/mod/worker.xml
index 4a74086a10..d1e72a36b8 100644
--- a/docs/manual/mod/worker.xml
+++ b/docs/manual/mod/worker.xml
@@ -28,16 +28,12 @@
 uses</a></seealso>
 
 <section id="how-it-works"><title>How it Works</title>
-    <p>Each process has a fixed
-    number of threads. The server adjusts to handle load by
-    increasing or decreasing the number of processes.</p>
-
-    <p>A single control process is responsible for launching child
-    processes. Each child process creates a fixed number of threads as
-    specified in the <directive
-    module="mpm_common">ThreadsPerChild</directive> directive. The
-    individual threads then listen for connections and serve them when
-    they arrive.</p>
+    <p>A single control process (the parent) is responsible for launching 
+    child processes. Each child process creates a fixed number of server
+    threads as specified in the <directive 
+    module="mpm_common">ThreadsPerChild</directive> directive, as well
+    as a listener thread which listens for connections and passes them
+    to a server thread for processing when they arrive.</p>
 
     <p>Apache always tries to maintain a pool of <dfn>spare</dfn> or
     idle server threads, which stand ready to serve incoming
@@ -54,25 +50,57 @@ uses</a></seealso>
     these directives from their default values. The maximum number of
     clients that may be served simultaneously (i.e., the maximum total
     number of threads in all processes) is determined by the
-    <directive module="mpm_common">MaxClients</directive> directive,
-    while the maximum number of processes that can be launched is set
-    by the <directive module="mpm_common">ServerLimit</directive>
-    directive.  <directive module="mpm_common">ServerLimit</directive>
-    multiplied by <directive
-    module="mpm_common">ThreadsPerChild</directive> must be greater
-    than or equal to <directive
-    module="mpm_common">MaxClients</directive></p>
+    <directive module="mpm_common">MaxClients</directive> directive.
+    The maximum number of active child processes is determined by
+    the <directive module="mpm_common">MaxClients</directive>
+    directive divided by the <directive module="mpm_common">
+    ThreadsPerChild</directive> directive.</p>
+
+    <p>Two directives set hard limits on the number of active child
+    processes and the number of server threads in a child process,
+    and can only be changed by fully stopping the server and then 
+    starting it again.  <directive module="mpm_common">ServerLimit
+    </directive> is a hard limit on the number of active child 
+    processes, and must be greater than or equal to the 
+    <directive module="mpm_common">MaxClients</directive>
+    directive divided by the <directive module="mpm_common">
+    ThreadsPerChild</directive> directive.  
+    <directive module="mpm_common">ThreadLimit</directive> is a hard
+    limit of the number of server threads, and must be greater than
+    or equal to the <directive 
+    module="mpm_common">ThreadsPerChild</directive> directive.  If 
+    non-default values are specified for these directives, they 
+    should appear before other <module>worker</module> directives.</p>
+
+    <p>In addition to a the set of active child processes, there may 
+    be additional child processes which are terminating but where at
+    least one server thread is still handling an existing client
+    connection.  Up to <directive 
+    module="mpm_common">MaxClient</directive> terminating processes 
+    may be present, though the actual number can be expected to be 
+    much smaller.  This behavior can be avoided by disabling the 
+    termination of individual child processes, which is achieved by 
+    the following:</p>
+
+    <ul>
+      <li>set the value of <directive module="mpm_common">
+      MaxRequestsPerChild</directive> to zero</li>
+
+      <li>set the value of <directive module="mpm_common">
+      MaxSpareThreads</directive> to the same value as
+      <directive module="mpm_common">MaxClients</directive></li>
+    </ul>
 
     <p>A typical configuration of the process-thread controls in
     the <module>worker</module> MPM could look as follows:</p>
 
     <example>
+      ServerLimit         16<br />
       StartServers         2<br />
       MaxClients         150<br />
       MinSpareThreads     25<br />
       MaxSpareThreads     75<br />
-      ThreadsPerChild     25<br />
-      ServerLimit         16
+      ThreadsPerChild     25
     </example>
 
     <p>While the parent process is usually started as <code>root</code>
-- 
2.50.1