Sync with the codes about the independence of load balancing scheduler algorithms. (r722948 - r722952)

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

4 files changed, 356 insertions, 234 deletions

diff --git a/docs/manual/mod/mod_lbmethod_bybusyness.xml b/docs/manual/mod/mod_lbmethod_bybusyness.xml
new file mode 100644
index 0000000000..07fe1f14da
--- /dev/null
+++ b/docs/manual/mod/mod_lbmethod_bybusyness.xml
@@ -0,0 +1,57 @@
+<?xml version="1.0"?>
+<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+<!-- $LastChangedRevision$ -->
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements.  See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<modulesynopsis metafile="mod_lbmethod_bybusyness.xml.meta">
+
+<name>mod_lbmethod_bybusyness</name>
+<description>Pending Request Counting load balancer scheduler algorithm for <module
+>mod_proxy_balancer</module></description>
+<status>Extension</status>
+<sourcefile>mod_lbmethod_bybusyness.c</sourcefile>
+<identifier>lbmethod_bybusyness_module</identifier>
+<compatibility>Split off from <module>mod_proxy_balancer</module> in 2.3</compatibility>
+
+<summary>
+</summary>
+<seealso><module>mod_proxy</module></seealso>
+<seealso><module>mod_proxy_balancer</module></seealso>
+
+<section id="busyness">
+
+    <title>Pending Request Counting Algorithm</title>
+
+    <p>Enabled via <code>lbmethod=bybusyness</code>, this scheduler keeps
+    track of how many requests each worker is assigned at present. A new
+    request is automatically assigned to the worker with the lowest
+    number of active requests. This is useful in the case of workers
+    that queue incoming requests independently of Apache, to ensure that
+    queue length stays even and a request is always given to the worker
+    most likely to service it fastest.</p>
+
+    <p>In the case of multiple least-busy workers, the statistics (and
+    weightings) used by the Request Counting method are used to break the
+    tie. Over time, the distribution of work will come to resemble that
+    characteristic of <code>byrequests</code>.</p>
+
+</section>
+
+</modulesynopsis>
diff --git a/docs/manual/mod/mod_lbmethod_byrequests.xml b/docs/manual/mod/mod_lbmethod_byrequests.xml
new file mode 100644
index 0000000000..3a2c257594
--- /dev/null
+++ b/docs/manual/mod/mod_lbmethod_byrequests.xml
@@ -0,0 +1,217 @@
+<?xml version="1.0"?>
+<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+<!-- $LastChangedRevision$ -->
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements.  See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<modulesynopsis metafile="mod_lbmethod_byrequests.xml.meta">
+
+<name>mod_lbmethod_byrequests</name>
+<description>Request Counting load balancer scheduler algorithm for <module
+>mod_proxy_balancer</module></description>
+<status>Extension</status>
+<sourcefile>mod_lbmethod_byrequests.c</sourcefile>
+<identifier>lbmethod_byrequests_module</identifier>
+<compatibility>Split off from <module>mod_proxy_balancer</module> in 2.3</compatibility>
+
+<summary>
+</summary>
+<seealso><module>mod_proxy</module></seealso>
+<seealso><module>mod_proxy_balancer</module></seealso>
+
+<section id="requests">
+    <title>Request Counting Algorithm</title>
+    <p>Enabled via <code>lbmethod=byrequests</code>, the idea behind this
+    scheduler is that we distribute the requests among the
+    various workers to ensure that each gets their configured share
+    of the number of requests. It works as follows:</p>
+
+    <p><dfn>lbfactor</dfn> is <em>how much we expect this worker
+    to work</em>, or <em>the workers's work quota</em>. This is
+    a normalized value representing their "share" of the amount of
+    work to be done.</p>
+
+    <p><dfn>lbstatus</dfn> is <em>how urgent this worker has to work
+    to fulfill its quota of work</em>.</p>
+
+    <p>The <dfn>worker</dfn> is a member of the load balancer,
+    usually a remote host serving one of the supported protocols.</p>
+
+    <p>We distribute each worker's work quota to the worker, and then look
+    which of them needs to work most urgently (biggest lbstatus).  This
+    worker is then selected for work, and its lbstatus reduced by the
+    total work quota we distributed to all workers.  Thus the sum of all
+    lbstatus does not change(*) and we distribute the requests
+    as desired.</p>
+
+    <p>If some workers are disabled, the others will
+    still be scheduled correctly.</p>
+
+    <example><pre><code>for each worker in workers
+    worker lbstatus += worker lbfactor
+    total factor    += worker lbfactor
+    if worker lbstatus > candidate lbstatus
+        candidate = worker
+
+candidate lbstatus -= total factor</code></pre>
+    </example>
+
+    <p>If a balancer is configured as follows:</p>
+    
+    <table style="data">
+    <tr><th>worker</th>
+        <th>a</th>
+        <th>b</th>
+        <th>c</th>
+        <th>d</th></tr>
+    <tr><th>lbfactor</th>
+        <td>25</td>
+        <td>25</td>
+        <td>25</td>
+        <td>25</td></tr>
+    <tr><th>lbstatus</th>
+        <td>0</td>
+        <td>0</td>
+        <td>0</td>
+        <td>0</td></tr>
+    </table>
+
+    <p>And <var>b</var> gets disabled, the following schedule is produced:</p>
+
+    <table style="data">
+    <tr><th>worker</th>
+        <th>a</th>
+        <th>b</th>
+        <th>c</th>
+        <th>d</th></tr>
+    <tr><th>lbstatus</th>
+        <td><em>-50</em></td>
+        <td>0</td>
+        <td>25</td>
+        <td>25</td></tr>
+    <tr><th>lbstatus</th>
+        <td>-25</td>
+        <td>0</td>
+        <td><em>-25</em></td>
+        <td>50</td></tr>
+    <tr><th>lbstatus</th>
+        <td>0</td>
+        <td>0</td>
+        <td>0</td>
+        <td><em>0</em></td></tr>
+    <tr><td colspan="5">(repeat)</td></tr>
+    </table>
+
+    <p>That is it schedules: <var>a</var> <var>c</var> <var>d</var>
+    <var>a</var> <var>c</var> <var>d</var> <var>a</var> <var>c</var>
+    <var>d</var> ... Please note that:</p>
+
+    <table style="data">
+    <tr><th>worker</th>
+        <th>a</th>
+        <th>b</th>
+        <th>c</th>
+        <th>d</th></tr>
+    <tr><th>lbfactor</th>
+        <td>25</td>
+        <td>25</td>
+        <td>25</td>
+        <td>25</td></tr>
+    </table>
+
+    <p>Has the exact same behavior as:</p>
+
+    <table style="data">
+    <tr><th>worker</th>
+        <th>a</th>
+        <th>b</th>
+        <th>c</th>
+        <th>d</th></tr>
+    <tr><th>lbfactor</th>
+        <td>1</td>
+        <td>1</td>
+        <td>1</td>
+        <td>1</td></tr>
+    </table>
+
+    <p>This is because all values of <dfn>lbfactor</dfn> are normalized
+    with respect to the others. For:</p>
+
+    <table style="data">
+    <tr><th>worker</th>
+        <th>a</th>
+        <th>b</th>
+        <th>c</th></tr>
+    <tr><th>lbfactor</th>
+        <td>1</td>
+        <td>4</td>
+        <td>1</td></tr>
+    </table>
+
+    <p>worker <var>b</var> will, on average, get 4 times the requests
+    that <var>a</var> and <var>c</var> will.</p>
+
+    <p>The following asymmetric configuration works as one would expect:</p>
+
+    <table style="data">
+    <tr><th>worker</th>
+        <th>a</th>
+        <th>b</th></tr>
+    <tr><th>lbfactor</th>
+        <td>70</td>
+        <td>30</td></tr>
+    <tr><td colspan="2">&nbsp;</td></tr>
+    <tr><th>lbstatus</th>
+        <td><em>-30</em></td>
+        <td>30</td></tr>
+    <tr><th>lbstatus</th>
+        <td>40</td>
+        <td><em>-40</em></td></tr>
+    <tr><th>lbstatus</th>
+        <td><em>10</em></td>
+        <td>-10</td></tr>
+    <tr><th>lbstatus</th>
+        <td><em>-20</em></td>
+        <td>20</td></tr>
+    <tr><th>lbstatus</th>
+        <td><em>-50</em></td>
+        <td>50</td></tr>
+    <tr><th>lbstatus</th>
+        <td>20</td>
+        <td><em>-20</em></td></tr>
+    <tr><th>lbstatus</th>
+        <td><em>-10</em></td>
+        <td>10</td></tr>
+    <tr><th>lbstatus</th>
+        <td><em>-40</em></td>
+        <td>40</td></tr>
+    <tr><th>lbstatus</th>
+        <td>30</td>
+        <td><em>-30</em></td></tr>
+    <tr><th>lbstatus</th>
+        <td><em>0</em></td>
+        <td>0</td></tr>
+    <tr><td colspan="3">(repeat)</td></tr>
+    </table>
+
+    <p>That is after 10 schedules, the schedule repeats and 7 <var>a</var>
+    are selected with 3 <var>b</var> interspersed.</p>
+</section>
+
+</modulesynopsis>
diff --git a/docs/manual/mod/mod_lbmethod_bytraffic.xml b/docs/manual/mod/mod_lbmethod_bytraffic.xml
new file mode 100644
index 0000000000..5cb01c3585
--- /dev/null
+++ b/docs/manual/mod/mod_lbmethod_bytraffic.xml
@@ -0,0 +1,72 @@
+<?xml version="1.0"?>
+<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+<!-- $LastChangedRevision$ -->
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements.  See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<modulesynopsis metafile="mod_lbmethod_bytraffic.xml.meta">
+
+<name>mod_lbmethod_bytraffic</name>
+<description>Weighted Traffic Counting load balancer scheduler algorithm for <module
+>mod_proxy_balancer</module></description>
+<status>Extension</status>
+<sourcefile>mod_lbmethod_bytraffic.c</sourcefile>
+<identifier>lbmethod_bytraffic_module</identifier>
+<compatibility>Split off from <module>mod_proxy_balancer</module> in 2.3</compatibility>
+
+<summary>
+</summary>
+<seealso><module>mod_proxy</module></seealso>
+<seealso><module>mod_proxy_balancer</module></seealso>
+
+<section id="traffic">
+    <title>Weighted Traffic Counting Algorithm</title>
+    <p>Enabled via <code>lbmethod=bytraffic</code>, the idea behind this
+    scheduler is very similar to the Request Counting method, with
+    the following changes:</p>
+
+    <p><dfn>lbfactor</dfn> is <em>how much traffic, in bytes, we want
+    this worker to handle</em>. This is also a normalized value
+    representing their "share" of the amount of work to be done,
+    but instead of simply counting the number of requests, we take
+    into account the amount of traffic this worker has seen.</p>
+
+    <p>If a balancer is configured as follows:</p>
+    
+    <table style="data">
+    <tr><th>worker</th>
+        <th>a</th>
+        <th>b</th>
+        <th>c</th></tr>
+    <tr><th>lbfactor</th>
+        <td>1</td>
+        <td>2</td>
+        <td>1</td></tr>
+    </table>
+
+    <p>Then we mean that we want <var>b</var> to process twice the
+    amount of bytes than <var>a</var> or <var>c</var> should. It does
+    not necessarily mean that <var>b</var> would handle twice as
+    many requests, but it would process twice the I/O. Thus, the
+    size of the request and response are applied to the weighting
+    and selection algorithm.</p>
+
+</section>
+
+</modulesynopsis>
diff --git a/docs/manual/mod/mod_proxy_balancer.xml b/docs/manual/mod/mod_proxy_balancer.xml
index 1097f71d81..98efcfd0ff 100644
--- a/docs/manual/mod/mod_proxy_balancer.xml
+++ b/docs/manual/mod/mod_proxy_balancer.xml
@@ -35,9 +35,17 @@
     <code>HTTP</code>, <code>FTP</code> and <code>AJP13</code> protocols
     </p>
 
+    <p>Load balancing scheduler algorithm is provided by not this
+    module but other modules such as:
+    <module>mod_lbmethod_byrequests</module>,
+    <module>mod_lbmethod_bytraffic</module> and
+    <module>mod_lbmethod_bybusyness</module>.
+    </p>
+
     <p>Thus, in order to get the ability of load balancing,
-    <module>mod_proxy</module> and <module>mod_proxy_balancer</module>
-    have to be present in the server.</p>
+    <module>mod_proxy</module>, <module>mod_proxy_balancer</module>
+    and at least one of load balancing scheduler algorithm modules have
+    to be present in the server.</p>
 
     <note type="warning"><title>Warning</title>
       <p>Do not enable proxying until you have <a
@@ -74,238 +82,6 @@
     </example>
 </section>
 
-<section id="requests">
-    <title>Request Counting Algorithm</title>
-    <p>Enabled via <code>lbmethod=byrequests</code>, the idea behind this
-    scheduler is that we distribute the requests among the
-    various workers to ensure that each gets their configured share
-    of the number of requests. It works as follows:</p>
-
-    <p><dfn>lbfactor</dfn> is <em>how much we expect this worker
-    to work</em>, or <em>the workers's work quota</em>. This is
-    a normalized value representing their "share" of the amount of
-    work to be done.</p>
-
-    <p><dfn>lbstatus</dfn> is <em>how urgent this worker has to work
-    to fulfill its quota of work</em>.</p>
-
-    <p>The <dfn>worker</dfn> is a member of the load balancer,
-    usually a remote host serving one of the supported protocols.</p>
-
-    <p>We distribute each worker's work quota to the worker, and then look
-    which of them needs to work most urgently (biggest lbstatus).  This
-    worker is then selected for work, and its lbstatus reduced by the
-    total work quota we distributed to all workers.  Thus the sum of all
-    lbstatus does not change(*) and we distribute the requests
-    as desired.</p>
-
-    <p>If some workers are disabled, the others will
-    still be scheduled correctly.</p>
-
-    <example><pre><code>for each worker in workers
-    worker lbstatus += worker lbfactor
-    total factor    += worker lbfactor
-    if worker lbstatus > candidate lbstatus
-        candidate = worker
-
-candidate lbstatus -= total factor</code></pre>
-    </example>
-
-    <p>If a balancer is configured as follows:</p>
-    
-    <table style="data">
-    <tr><th>worker</th>
-        <th>a</th>
-        <th>b</th>
-        <th>c</th>
-        <th>d</th></tr>
-    <tr><th>lbfactor</th>
-        <td>25</td>
-        <td>25</td>
-        <td>25</td>
-        <td>25</td></tr>
-    <tr><th>lbstatus</th>
-        <td>0</td>
-        <td>0</td>
-        <td>0</td>
-        <td>0</td></tr>
-    </table>
-
-    <p>And <var>b</var> gets disabled, the following schedule is produced:</p>
-
-    <table style="data">
-    <tr><th>worker</th>
-        <th>a</th>
-        <th>b</th>
-        <th>c</th>
-        <th>d</th></tr>
-    <tr><th>lbstatus</th>
-        <td><em>-50</em></td>
-        <td>0</td>
-        <td>25</td>
-        <td>25</td></tr>
-    <tr><th>lbstatus</th>
-        <td>-25</td>
-        <td>0</td>
-        <td><em>-25</em></td>
-        <td>50</td></tr>
-    <tr><th>lbstatus</th>
-        <td>0</td>
-        <td>0</td>
-        <td>0</td>
-        <td><em>0</em></td></tr>
-    <tr><td colspan="5">(repeat)</td></tr>
-    </table>
-
-    <p>That is it schedules: <var>a</var> <var>c</var> <var>d</var>
-    <var>a</var> <var>c</var> <var>d</var> <var>a</var> <var>c</var>
-    <var>d</var> ... Please note that:</p>
-
-    <table style="data">
-    <tr><th>worker</th>
-        <th>a</th>
-        <th>b</th>
-        <th>c</th>
-        <th>d</th></tr>
-    <tr><th>lbfactor</th>
-        <td>25</td>
-        <td>25</td>
-        <td>25</td>
-        <td>25</td></tr>
-    </table>
-
-    <p>Has the exact same behavior as:</p>
-
-    <table style="data">
-    <tr><th>worker</th>
-        <th>a</th>
-        <th>b</th>
-        <th>c</th>
-        <th>d</th></tr>
-    <tr><th>lbfactor</th>
-        <td>1</td>
-        <td>1</td>
-        <td>1</td>
-        <td>1</td></tr>
-    </table>
-
-    <p>This is because all values of <dfn>lbfactor</dfn> are normalized
-    with respect to the others. For:</p>
-
-    <table style="data">
-    <tr><th>worker</th>
-        <th>a</th>
-        <th>b</th>
-        <th>c</th></tr>
-    <tr><th>lbfactor</th>
-        <td>1</td>
-        <td>4</td>
-        <td>1</td></tr>
-    </table>
-
-    <p>worker <var>b</var> will, on average, get 4 times the requests
-    that <var>a</var> and <var>c</var> will.</p>
-
-    <p>The following asymmetric configuration works as one would expect:</p>
-
-    <table style="data">
-    <tr><th>worker</th>
-        <th>a</th>
-        <th>b</th></tr>
-    <tr><th>lbfactor</th>
-        <td>70</td>
-        <td>30</td></tr>
-    <tr><td colspan="2">&nbsp;</td></tr>
-    <tr><th>lbstatus</th>
-        <td><em>-30</em></td>
-        <td>30</td></tr>
-    <tr><th>lbstatus</th>
-        <td>40</td>
-        <td><em>-40</em></td></tr>
-    <tr><th>lbstatus</th>
-        <td><em>10</em></td>
-        <td>-10</td></tr>
-    <tr><th>lbstatus</th>
-        <td><em>-20</em></td>
-        <td>20</td></tr>
-    <tr><th>lbstatus</th>
-        <td><em>-50</em></td>
-        <td>50</td></tr>
-    <tr><th>lbstatus</th>
-        <td>20</td>
-        <td><em>-20</em></td></tr>
-    <tr><th>lbstatus</th>
-        <td><em>-10</em></td>
-        <td>10</td></tr>
-    <tr><th>lbstatus</th>
-        <td><em>-40</em></td>
-        <td>40</td></tr>
-    <tr><th>lbstatus</th>
-        <td>30</td>
-        <td><em>-30</em></td></tr>
-    <tr><th>lbstatus</th>
-        <td><em>0</em></td>
-        <td>0</td></tr>
-    <tr><td colspan="3">(repeat)</td></tr>
-    </table>
-
-    <p>That is after 10 schedules, the schedule repeats and 7 <var>a</var>
-    are selected with 3 <var>b</var> interspersed.</p>
-</section>
-
-<section id="traffic">
-    <title>Weighted Traffic Counting Algorithm</title>
-    <p>Enabled via <code>lbmethod=bytraffic</code>, the idea behind this
-    scheduler is very similar to the Request Counting method, with
-    the following changes:</p>
-
-    <p><dfn>lbfactor</dfn> is <em>how much traffic, in bytes, we want
-    this worker to handle</em>. This is also a normalized value
-    representing their "share" of the amount of work to be done,
-    but instead of simply counting the number of requests, we take
-    into account the amount of traffic this worker has seen.</p>
-
-    <p>If a balancer is configured as follows:</p>
-    
-    <table style="data">
-    <tr><th>worker</th>
-        <th>a</th>
-        <th>b</th>
-        <th>c</th></tr>
-    <tr><th>lbfactor</th>
-        <td>1</td>
-        <td>2</td>
-        <td>1</td></tr>
-    </table>
-
-    <p>Then we mean that we want <var>b</var> to process twice the
-    amount of bytes than <var>a</var> or <var>c</var> should. It does
-    not necessarily mean that <var>b</var> would handle twice as
-    many requests, but it would process twice the I/O. Thus, the
-    size of the request and response are applied to the weighting
-    and selection algorithm.</p>
-
-</section>
-
-<section id="busyness">
-
-    <title>Pending Request Counting Algorithm</title>
-
-    <p>Enabled via <code>lbmethod=bybusyness</code>, this scheduler keeps
-    track of how many requests each worker is assigned at present. A new
-    request is automatically assigned to the worker with the lowest
-    number of active requests. This is useful in the case of workers
-    that queue incoming requests independently of Apache, to ensure that
-    queue length stays even and a request is always given to the worker
-    most likely to service it fastest.</p>
-
-    <p>In the case of multiple least-busy workers, the statistics (and
-    weightings) used by the Request Counting method are used to break the
-    tie. Over time, the distribution of work will come to resemble that
-    characteristic of <code>byrequests</code>.</p>
-
-</section>
-
 <section id="environment">
     <title>Exported Environment Variables</title>
     <p>At present there are 6 environment variables exported:</p>