From: Jeff Trawick <trawick@apache.org>
Date: Sun, 19 Dec 2010 22:46:23 +0000 (+0000)
Subject: merge r956059, 1000130, and 1000474 from trunk:
X-Git-Tag: 2.2.18~232
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3923e0e2c63b55771d1f8a95f07ae73d621ab9b1;p=thirdparty%2Fapache%2Fhttpd.git

merge r956059, 1000130, and 1000474 from trunk:

improve connection pooling overview and descriptions of
min, max, smax, and ttl parameters


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.2.x@1050958 13f79535-47bb-0310-9956-ffa450edef68
---

diff --git a/docs/manual/mod/mod_proxy.xml b/docs/manual/mod/mod_proxy.xml
index 249631a5fbe..b55b7b121b9 100644
--- a/docs/manual/mod/mod_proxy.xml
+++ b/docs/manual/mod/mod_proxy.xml
@@ -764,23 +764,30 @@ expressions</description>
 
     </note> <!-- /ordering_proxypass -->
 
-    <p>As of Apache 2.1, the ability to use pooled connections to a backend
-    server is available. Using the <code>key=value</code> parameters it is
-    possible to tune this connection pooling. The default for a <code>Hard
-    Maximum</code> 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>.</p>
-
-    <p>Setting <code>min</code> will determine how many connections will always 
-    be open to the backend server. Upto the Soft Maximum or <code>smax</code> 
-    number of connections will be created on demand. Any connections above 
-    <code>smax</code> are subject to a time to live or <code>ttl</code>.  Apache
-    will never create more than the Hard Maximum or <code>max</code> connections
-    to the backend server.</p>
+    <p>In Apache HTTP Server 2.1 and later, mod_proxy supports pooled
+    connections to a backend server.  Connections created on demand
+    can be retained in a pool for future use.  Limits on the pool size
+    and other settings can be coded on
+    the <directive>ProxyPass</directive> directive
+    using  <code>key=value</code> parameters, described in the table
+    below.</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 <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>
-        ProxyPass /example http://backend.example.com smax=5 max=20 ttl=120 retry=300
+    <example><title>Example</title>
+        ProxyPass /example http://backend.example.com max=20 ttl=120 retry=300
     </example>
 
     <table>
@@ -789,23 +796,27 @@ expressions</description>
         <th>Description</th></tr>
     <tr><td>min</td>
         <td>0</td>
-        <td>Minimum number of connections that will always
-            be open to the backend server.</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 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>Upto the Soft Maximum
-    number of connections will be created on demand. Any connections above 
-    <code>smax</code> are subject to a time to live or <code>ttl</code>.
-    </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
@@ -924,9 +935,9 @@ expressions</description>
     </td></tr>
     <tr><td>ttl</td>
         <td>-</td>
-        <td>Time To Live for the inactive connections above the
-        <code>smax</code> connections in seconds. Apache will close all
-        connections that has 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>