granicus.if.org Git - apache/blob - docs/manual/mod/mod_lbmethod_byrequests.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <modulesynopsis metafile="mod_lbmethod_byrequests.xml.meta">
  24
  25 <name>mod_lbmethod_byrequests</name>
  26 <description>Request Counting load balancer scheduler algorithm for <module
  27 >mod_proxy_balancer</module></description>
  28 <status>Extension</status>
  29 <sourcefile>mod_lbmethod_byrequests.c</sourcefile>
  30 <identifier>lbmethod_byrequests_module</identifier>
  31 <compatibility>Split off from <module>mod_proxy_balancer</module> in 2.3</compatibility>
  32
  33 <summary>
  34 <!-- FIXME: --> <p>This document is still under development.</p>
  35 </summary>
  36 <seealso><module>mod_proxy</module></seealso>
  37 <seealso><module>mod_proxy_balancer</module></seealso>
  38
  39 <section id="requests">
  40     <title>Request Counting Algorithm</title>
  41     <p>Enabled via <code>lbmethod=byrequests</code>, the idea behind this
  42     scheduler is that we distribute the requests among the
  43     various workers to ensure that each gets their configured share
  44     of the number of requests. It works as follows:</p>
  45
  46     <p><dfn>lbfactor</dfn> is <em>how much we expect this worker
  47     to work</em>, or <em>the workers's work quota</em>. This is
  48     a normalized value representing their "share" of the amount of
  49     work to be done.</p>
  50
  51     <p><dfn>lbstatus</dfn> is <em>how urgent this worker has to work
  52     to fulfill its quota of work</em>.</p>
  53
  54     <p>The <dfn>worker</dfn> is a member of the load balancer,
  55     usually a remote host serving one of the supported protocols.</p>
  56
  57     <p>We distribute each worker's work quota to the worker, and then look
  58     which of them needs to work most urgently (biggest lbstatus).  This
  59     worker is then selected for work, and its lbstatus reduced by the
  60     total work quota we distributed to all workers.  Thus the sum of all
  61     lbstatus does not change(*) and we distribute the requests
  62     as desired.</p>
  63
  64     <p>If some workers are disabled, the others will
  65     still be scheduled correctly.</p>
  66
  67     <example><pre><code>for each worker in workers
  68     worker lbstatus += worker lbfactor
  69     total factor    += worker lbfactor
  70     if worker lbstatus > candidate lbstatus
  71         candidate = worker
  72
  73 candidate lbstatus -= total factor</code></pre>
  74     </example>
  75
  76     <p>If a balancer is configured as follows:</p>
  77
  78     <table style="data">
  79     <tr><th>worker</th>
  80         <th>a</th>
  81         <th>b</th>
  82         <th>c</th>
  83         <th>d</th></tr>
  84     <tr><th>lbfactor</th>
  85         <td>25</td>
  86         <td>25</td>
  87         <td>25</td>
  88         <td>25</td></tr>
  89     <tr><th>lbstatus</th>
  90         <td>0</td>
  91         <td>0</td>
  92         <td>0</td>
  93         <td>0</td></tr>
  94     </table>
  95
  96     <p>And <var>b</var> gets disabled, the following schedule is produced:</p>
  97
  98     <table style="data">
  99     <tr><th>worker</th>
 100         <th>a</th>
 101         <th>b</th>
 102         <th>c</th>
 103         <th>d</th></tr>
 104     <tr><th>lbstatus</th>
 105         <td><em>-50</em></td>
 106         <td>0</td>
 107         <td>25</td>
 108         <td>25</td></tr>
 109     <tr><th>lbstatus</th>
 110         <td>-25</td>
 111         <td>0</td>
 112         <td><em>-25</em></td>
 113         <td>50</td></tr>
 114     <tr><th>lbstatus</th>
 115         <td>0</td>
 116         <td>0</td>
 117         <td>0</td>
 118         <td><em>0</em></td></tr>
 119     <tr><td colspan="5">(repeat)</td></tr>
 120     </table>
 121
 122     <p>That is it schedules: <var>a</var> <var>c</var> <var>d</var>
 123     <var>a</var> <var>c</var> <var>d</var> <var>a</var> <var>c</var>
 124     <var>d</var> ... Please note that:</p>
 125
 126     <table style="data">
 127     <tr><th>worker</th>
 128         <th>a</th>
 129         <th>b</th>
 130         <th>c</th>
 131         <th>d</th></tr>
 132     <tr><th>lbfactor</th>
 133         <td>25</td>
 134         <td>25</td>
 135         <td>25</td>
 136         <td>25</td></tr>
 137     </table>
 138
 139     <p>Has the exact same behavior as:</p>
 140
 141     <table style="data">
 142     <tr><th>worker</th>
 143         <th>a</th>
 144         <th>b</th>
 145         <th>c</th>
 146         <th>d</th></tr>
 147     <tr><th>lbfactor</th>
 148         <td>1</td>
 149         <td>1</td>
 150         <td>1</td>
 151         <td>1</td></tr>
 152     </table>
 153
 154     <p>This is because all values of <dfn>lbfactor</dfn> are normalized
 155     with respect to the others. For:</p>
 156
 157     <table style="data">
 158     <tr><th>worker</th>
 159         <th>a</th>
 160         <th>b</th>
 161         <th>c</th></tr>
 162     <tr><th>lbfactor</th>
 163         <td>1</td>
 164         <td>4</td>
 165         <td>1</td></tr>
 166     </table>
 167
 168     <p>worker <var>b</var> will, on average, get 4 times the requests
 169     that <var>a</var> and <var>c</var> will.</p>
 170
 171     <p>The following asymmetric configuration works as one would expect:</p>
 172
 173     <table style="data">
 174     <tr><th>worker</th>
 175         <th>a</th>
 176         <th>b</th></tr>
 177     <tr><th>lbfactor</th>
 178         <td>70</td>
 179         <td>30</td></tr>
 180     <tr><td colspan="2">&nbsp;</td></tr>
 181     <tr><th>lbstatus</th>
 182         <td><em>-30</em></td>
 183         <td>30</td></tr>
 184     <tr><th>lbstatus</th>
 185         <td>40</td>
 186         <td><em>-40</em></td></tr>
 187     <tr><th>lbstatus</th>
 188         <td><em>10</em></td>
 189         <td>-10</td></tr>
 190     <tr><th>lbstatus</th>
 191         <td><em>-20</em></td>
 192         <td>20</td></tr>
 193     <tr><th>lbstatus</th>
 194         <td><em>-50</em></td>
 195         <td>50</td></tr>
 196     <tr><th>lbstatus</th>
 197         <td>20</td>
 198         <td><em>-20</em></td></tr>
 199     <tr><th>lbstatus</th>
 200         <td><em>-10</em></td>
 201         <td>10</td></tr>
 202     <tr><th>lbstatus</th>
 203         <td><em>-40</em></td>
 204         <td>40</td></tr>
 205     <tr><th>lbstatus</th>
 206         <td>30</td>
 207         <td><em>-30</em></td></tr>
 208     <tr><th>lbstatus</th>
 209         <td><em>0</em></td>
 210         <td>0</td></tr>
 211     <tr><td colspan="3">(repeat)</td></tr>
 212     </table>
 213
 214     <p>That is after 10 schedules, the schedule repeats and 7 <var>a</var>
 215     are selected with 3 <var>b</var> interspersed.</p>
 216 </section>
 217
 218 </modulesynopsis>