granicus.if.org Git - apache/blob - docs/manual/mod/worker.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="worker.xml.meta">
  24 <name>worker</name>
  25 <description>Multi-Processing Module implementing a hybrid
  26     multi-threaded multi-process web server</description>
  27 <status>MPM</status>
  28 <sourcefile>worker.c</sourcefile>
  29 <identifier>mpm_worker_module</identifier>
  30
  31 <summary>
  32     <p>This Multi-Processing Module (MPM) implements a hybrid
  33     multi-process multi-threaded server. By using threads to serve
  34     requests, it is able to serve a large number of requests with
  35     fewer system resources than a process-based server. However, it
  36     retains much of the stability of a process-based server by
  37     keeping multiple processes available, each with many threads.</p>
  38
  39     <p>The most important directives used to control this MPM are
  40     <directive module="mpm_common">ThreadsPerChild</directive>, which
  41     controls the number of threads deployed by each child process and
  42     <directive module="mpm_common">MaxClients</directive>, which
  43     controls the maximum total number of threads that may be
  44     launched.</p>
  45 </summary>
  46 <seealso><a href="../bind.html">Setting which addresses and ports Apache
  47 uses</a></seealso>
  48
  49 <section id="how-it-works"><title>How it Works</title>
  50     <p>A single control process (the parent) is responsible for launching
  51     child processes. Each child process creates a fixed number of server
  52     threads as specified in the <directive
  53     module="mpm_common">ThreadsPerChild</directive> directive, as well
  54     as a listener thread which listens for connections and passes them
  55     to a server thread for processing when they arrive.</p>
  56
  57     <p>Apache always tries to maintain a pool of <dfn>spare</dfn> or
  58     idle server threads, which stand ready to serve incoming
  59     requests. In this way, clients do not need to wait for a new
  60     threads or processes to be created before their requests can be
  61     served. The number of processes that will initially launched is
  62     set by the <directive module="mpm_common">StartServers</directive>
  63     directive. During operation, Apache assesses the total number
  64     of idle threads in all processes, and forks or kills processes to
  65     keep this number within the boundaries specified by <directive
  66     module="mpm_common">MinSpareThreads</directive> and <directive
  67     module="mpm_common">MaxSpareThreads</directive>. Since this
  68     process is very self-regulating, it is rarely necessary to modify
  69     these directives from their default values. The maximum number of
  70     clients that may be served simultaneously (i.e., the maximum total
  71     number of threads in all processes) is determined by the
  72     <directive module="mpm_common">MaxClients</directive> directive.
  73     The maximum number of active child processes is determined by
  74     the <directive module="mpm_common">MaxClients</directive>
  75     directive divided by the <directive module="mpm_common">
  76     ThreadsPerChild</directive> directive.</p>
  77
  78     <p>Two directives set hard limits on the number of active child
  79     processes and the number of server threads in a child process,
  80     and can only be changed by fully stopping the server and then
  81     starting it again.  <directive module="mpm_common">ServerLimit
  82     </directive> is a hard limit on the number of active child
  83     processes, and must be greater than or equal to the
  84     <directive module="mpm_common">MaxClients</directive>
  85     directive divided by the <directive module="mpm_common">
  86     ThreadsPerChild</directive> directive.
  87     <directive module="mpm_common">ThreadLimit</directive> is a hard
  88     limit of the number of server threads, and must be greater than
  89     or equal to the <directive
  90     module="mpm_common">ThreadsPerChild</directive> directive.  If
  91     non-default values are specified for these directives, they
  92     should appear before other <module>worker</module> directives.</p>
  93
  94     <p>In addition to the set of active child processes, there may
  95     be additional child processes which are terminating, but where at
  96     least one server thread is still handling an existing client
  97     connection.  Up to <directive
  98     module="mpm_common">MaxClients</directive> terminating processes
  99     may be present, though the actual number can be expected to be
 100     much smaller.  This behavior can be avoided by disabling the
 101     termination of individual child processes, which is achieved using
 102     the following:</p>
 103
 104     <ul>
 105       <li>set the value of <directive module="mpm_common">
 106       MaxRequestsPerChild</directive> to zero</li>
 107
 108       <li>set the value of <directive module="mpm_common">
 109       MaxSpareThreads</directive> to the same value as
 110       <directive module="mpm_common">MaxClients</directive></li>
 111     </ul>
 112
 113     <p>A typical configuration of the process-thread controls in
 114     the <module>worker</module> MPM could look as follows:</p>
 115
 116     <example>
 117       ServerLimit         16<br />
 118       StartServers         2<br />
 119       MaxClients         150<br />
 120       MinSpareThreads     25<br />
 121       MaxSpareThreads     75<br />
 122       ThreadsPerChild     25
 123     </example>
 124
 125     <p>While the parent process is usually started as <code>root</code>
 126     under Unix in order to bind to port 80, the child processes and threads
 127     are launched by Apache as a less-privileged user. The <directive
 128     module="mpm_common">User</directive> and <directive
 129     module="mpm_common">Group</directive> directives are used to set
 130     the privileges of the Apache child processes. The child processes
 131     must be able to read all the content that will be served, but
 132     should have as few privileges beyond that as possible. In
 133     addition, unless <program>suexec</program> is used,
 134     these directives also set the privileges which will be inherited
 135     by CGI scripts.</p>
 136
 137     <p><directive module="mpm_common">MaxRequestsPerChild</directive>
 138     controls how frequently the server recycles processes by killing
 139     old ones and launching new ones.</p>
 140 </section>
 141
 142 <directivesynopsis location="mpm_common"><name>AcceptMutex</name>
 143 </directivesynopsis>
 144 <directivesynopsis location="mpm_common"><name>CoreDumpDirectory</name>
 145 </directivesynopsis>
 146 <directivesynopsis location="mpm_common"><name>EnableExceptionHook</name>
 147 </directivesynopsis>
 148 <directivesynopsis location="mpm_common"><name>Group</name>
 149 </directivesynopsis>
 150 <directivesynopsis location="mpm_common"><name>PidFile</name>
 151 </directivesynopsis>
 152 <directivesynopsis location="mpm_common"><name>Listen</name>
 153 </directivesynopsis>
 154 <directivesynopsis location="mpm_common"><name>ListenBacklog</name>
 155 </directivesynopsis>
 156 <directivesynopsis location="mpm_common"><name>LockFile</name>
 157 </directivesynopsis>
 158 <directivesynopsis location="mpm_common"><name>MaxClients</name>
 159 </directivesynopsis>
 160 <directivesynopsis location="mpm_common"><name>MaxMemFree</name>
 161 </directivesynopsis>
 162 <directivesynopsis location="mpm_common"><name>MaxRequestsPerChild</name>
 163 </directivesynopsis>
 164 <directivesynopsis location="mpm_common"><name>MaxSpareThreads</name>
 165 </directivesynopsis>
 166 <directivesynopsis location="mpm_common"><name>MinSpareThreads</name>
 167 </directivesynopsis>
 168 <directivesynopsis location="mpm_common"><name>ScoreBoardFile</name>
 169 </directivesynopsis>
 170 <directivesynopsis location="mpm_common"><name>ReceiveBufferSize</name>
 171 </directivesynopsis>
 172 <directivesynopsis location="mpm_common"><name>SendBufferSize</name>
 173 </directivesynopsis>
 174 <directivesynopsis location="mpm_common"><name>ServerLimit</name>
 175 </directivesynopsis>
 176 <directivesynopsis location="mpm_common"><name>StartServers</name>
 177 </directivesynopsis>
 178 <directivesynopsis location="mpm_common"><name>ThreadLimit</name>
 179 </directivesynopsis>
 180 <directivesynopsis location="mpm_common"><name>ThreadsPerChild</name>
 181 </directivesynopsis>
 182 <directivesynopsis location="mpm_common"><name>ThreadStackSize</name>
 183 </directivesynopsis>
 184 <directivesynopsis location="mpm_common"><name>User</name>
 185 </directivesynopsis>
 186
 187 </modulesynopsis>