svn commit: r1000474 - /httpd/httpd/trunk/docs/manual/mod/mod_proxy.xml

[tr...@apache.org]

Author: trawick
Date: Thu Sep 23 14:01:02 2010
New Revision: 1000474

URL: http://svn.apache.org/viewvc?rev=1000474&view=rev
Log:
follow up r956069 and r1000130 with additional corrections
and clarifications

Deemphasize and re-document min and smax, which are only to be
used in special circumstances.

Stop using the terms "Hard maximum" and "Soft maximum" since they
imply incorrectly that max and smax are closely related parameters
which should be considered in tandem.  That may be true from the
apr_reslist perspective, but not from that of the httpd admin.

Thanks, Rüdiger (but of course all bugs are mine)

Modified:
    httpd/httpd/trunk/docs/manual/mod/mod_proxy.xml

Modified: httpd/httpd/trunk/docs/manual/mod/mod_proxy.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/mod_proxy.xml?rev=1000474&r1=1000473&r2=1000474&view=diff
==============================================================================
--- httpd/httpd/trunk/docs/manual/mod/mod_proxy.xml (original)
+++ httpd/httpd/trunk/docs/manual/mod/mod_proxy.xml Thu Sep 23 14:01:02 2010
@@ -764,21 +764,22 @@ expressions</description>
     using  <code>key=value</code> parameters, described in the table
     below.</p>
 
-    <p>Setting <code>min</code> to non-zero allows connections to the
-    backend server to be retained after use; at least <code>min</code>
-    connections will be retained.  Any idle connections above
-    <code>smax</code> are subject to a time to live, or <code>ttl</code>.
-    Up to the hard maximum, or <code>max</code>, number of connections
-    may be created.</p>
+    <p>By default, mod_proxy will allow and retain the maximum number of
+    connections that could be used simultaneously by that web server child
+    process.  Use the <code>max</code> parameter to reduce the number from
+    the default.  Use the <code>ttl</code> parameter to set an optional
+    time to live; connections which have been unused for at least
+    <code>ttl</code> seconds will be closed.  <code>ttl</code> can be used
+    to avoid using a connection which is subject to closing because of the
+    backend server's keep-alive timeout.</p>
 
     <p>The pool of connections is maintained per web server child
-    process, and the <code>min</code>, <code>max</code>, and
-    and <code>smax</code> settings are not coordinated among all child
-    processes, except when only one child process is allowed by
-    configuration or MPM design.</p>
+    process, and <code>max</code> and other settings are not coordinated 
+    among all child processes, except when only one child process is allowed
+    by configuration or MPM design.</p>
 
     <example><title>Example</title>
-        ProxyPass /example http://backend.example.com smax=5 max=20 ttl=120 retry=300
+        ProxyPass /example http://backend.example.com max=20 ttl=120 retry=300
     </example>
 
     <table>
@@ -787,22 +788,27 @@ expressions</description>
         <th>Description</th></tr>
     <tr><td>min</td>
         <td>0</td>
-        <td>Minimum number of connections to the backend server that
-            will be retained after use.</td></tr>
+        <td>Minimum number of connection pool entries, unrelated to the
+    actual number of connections.  This only needs to be modified from the
+    default for special circumstances where heap memory associated with the
+    backend connections should be preallocated or retained.</td></tr>
     <tr><td>max</td>
         <td>1...n</td>
-        <td>Hard Maximum number of connections that will be
-    allowed to the backend server. The default for a Hard Maximum
-    for the number of connections is the number of threads per process in the 
-    active MPM. In the Prefork MPM, this is always 1, while with the Worker MPM
-    it is controlled by the <directive>ThreadsPerChild</directive>.
-    Apache httpd will never create more than the Hard Maximum connections
-    to the backend server.</td></tr>
+        <td>Maximum number of connections that will be allowed to the
+    backend server. The default for this limit is the number of threads
+    per process in the active MPM. In the Prefork MPM, this is always 1,
+    while with other MPMs it is controlled by the
+    <directive>ThreadsPerChild</directive> directive.</td></tr>
     <tr><td>smax</td>
         <td>max</td>
-        <td>Retained connections above the soft maximum, or <code>smax</code>,
-    are subject to a time to live, controlled by the <code>ttl</code> parameter.
-    </td></tr>
+        <td>Retained connection pool entries above this limit are freed
+    during certain operations if they have been unused for longer than
+    the time to live, controlled by the <code>ttl</code> parameter.  If
+    the connection pool entry has an associated connection, it will be
+    closed.  This only needs to be modified from the default for special
+    circumstances where connection pool entries and any associated
+    connections which have exceeded the time to live need to be freed or
+    closed more aggressively.</td></tr>
     <tr><td>acquire</td>
         <td>-</td>
         <td>If set this will be the maximum time to wait for a free
@@ -929,9 +935,9 @@ expressions</description>
     </td></tr>
     <tr><td>ttl</td>
         <td>-</td>
-        <td>Time to live for the inactive connections above <code>smax</code>,
-        in seconds.  Connections above <code>smax</code> will be closed
-        if they have not been used inside that time period.
+        <td>Time to live for inactive connections and associated connection
+        pool entries, in seconds.  Those which are unused for at least
+        <code>ttl</code> seconds will be destroyed.
     </td></tr>
 
     </table>