2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $Revision: 1.19 $ -->
7 Copyright 2002-2004 The Apache Software Foundation
9 Licensed under the Apache License, Version 2.0 (the "License");
10 you may not use this file except in compliance with the License.
11 You may obtain a copy of the License at
13 http://www.apache.org/licenses/LICENSE-2.0
15 Unless required by applicable law or agreed to in writing, software
16 distributed under the License is distributed on an "AS IS" BASIS,
17 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18 See the License for the specific language governing permissions and
19 limitations under the License.
22 <modulesynopsis metafile="worker.xml.meta">
24 <description>Multi-Processing Module implementing a hybrid
25 multi-threaded multi-process web server</description>
27 <sourcefile>worker.c</sourcefile>
28 <identifier>mpm_worker_module</identifier>
31 <p>This Multi-Processing Module (MPM) implements a hybrid
32 multi-process multi-threaded server. By using threads to serve
33 requests, it is able to serve a large number of requests with
34 less system resources than a process-based server. Yet it
35 retains much of the stability of a process-based server by
36 keeping multiple processes available, each with many threads.</p>
38 <p>The most important directives used to control this MPM are
39 <directive module="mpm_common">ThreadsPerChild</directive>, which
40 controls the number of threads deployed by each child process and
41 <directive module="mpm_common">MaxClients</directive>, which
42 controls the maximum total number of threads that may be
45 <seealso><a href="../bind.html">Setting which addresses and ports Apache
48 <section id="how-it-works"><title>How it Works</title>
49 <p>A single control process (the parent) is responsible for launching
50 child processes. Each child process creates a fixed number of server
51 threads as specified in the <directive
52 module="mpm_common">ThreadsPerChild</directive> directive, as well
53 as a listener thread which listens for connections and passes them
54 to a server thread for processing when they arrive.</p>
56 <p>Apache always tries to maintain a pool of <dfn>spare</dfn> or
57 idle server threads, which stand ready to serve incoming
58 requests. In this way, clients do not need to wait for a new
59 threads or processes to be created before their requests can be
60 served. The number of processes that will initially launched is
61 set by the <directive module="mpm_common">StartServers</directive>
62 directive. Then during operation, Apache assesses the total number
63 of idle threads in all processes, and forks or kills processes to
64 keep this number within the boundaries specified by <directive
65 module="mpm_common">MinSpareThreads</directive> and <directive
66 module="mpm_common">MaxSpareThreads</directive>. Since this
67 process is very self-regulating, it is rarely necessary to modify
68 these directives from their default values. The maximum number of
69 clients that may be served simultaneously (i.e., the maximum total
70 number of threads in all processes) is determined by the
71 <directive module="mpm_common">MaxClients</directive> directive.
72 The maximum number of active child processes is determined by
73 the <directive module="mpm_common">MaxClients</directive>
74 directive divided by the <directive module="mpm_common">
75 ThreadsPerChild</directive> directive.</p>
77 <p>Two directives set hard limits on the number of active child
78 processes and the number of server threads in a child process,
79 and can only be changed by fully stopping the server and then
80 starting it again. <directive module="mpm_common">ServerLimit
81 </directive> is a hard limit on the number of active child
82 processes, and must be greater than or equal to the
83 <directive module="mpm_common">MaxClients</directive>
84 directive divided by the <directive module="mpm_common">
85 ThreadsPerChild</directive> directive.
86 <directive module="mpm_common">ThreadLimit</directive> is a hard
87 limit of the number of server threads, and must be greater than
88 or equal to the <directive
89 module="mpm_common">ThreadsPerChild</directive> directive. If
90 non-default values are specified for these directives, they
91 should appear before other <module>worker</module> directives.</p>
93 <p>In addition to a the set of active child processes, there may
94 be additional child processes which are terminating but where at
95 least one server thread is still handling an existing client
96 connection. Up to <directive
97 module="mpm_common">MaxClients</directive> terminating processes
98 may be present, though the actual number can be expected to be
99 much smaller. This behavior can be avoided by disabling the
100 termination of individual child processes, which is achieved by
104 <li>set the value of <directive module="mpm_common">
105 MaxRequestsPerChild</directive> to zero</li>
107 <li>set the value of <directive module="mpm_common">
108 MaxSpareThreads</directive> to the same value as
109 <directive module="mpm_common">MaxClients</directive></li>
112 <p>A typical configuration of the process-thread controls in
113 the <module>worker</module> MPM could look as follows:</p>
119 MinSpareThreads 25<br />
120 MaxSpareThreads 75<br />
124 <p>While the parent process is usually started as <code>root</code>
125 under Unix in order to bind to port 80, the child processes and threads
126 are launched by Apache as a less-privileged user. The <directive
127 module="mpm_common">User</directive> and <directive
128 module="mpm_common">Group</directive> directives are used to set
129 the privileges of the Apache child processes. The child processes
130 must be able to read all the content that will be served, but
131 should have as few privileges beyond that as possible. In
132 addition, unless <a href="../suexec.html">suexec</a> is used,
133 these directives also set the privileges which will be inherited
136 <p><directive module="mpm_common">MaxRequestsPerChild</directive>
137 controls how frequently the server recycles processes by killing
138 old ones and launching new ones.</p>
141 <directivesynopsis location="mpm_common"><name>AcceptMutex</name>
143 <directivesynopsis location="mpm_common"><name>CoreDumpDirectory</name>
145 <directivesynopsis location="mpm_common"><name>EnableExceptionHook</name>
147 <directivesynopsis location="mpm_common"><name>Group</name>
149 <directivesynopsis location="mpm_common"><name>PidFile</name>
151 <directivesynopsis location="mpm_common"><name>Listen</name>
153 <directivesynopsis location="mpm_common"><name>ListenBacklog</name>
155 <directivesynopsis location="mpm_common"><name>LockFile</name>
157 <directivesynopsis location="mpm_common"><name>MaxClients</name>
159 <directivesynopsis location="mpm_common"><name>MaxMemFree</name>
161 <directivesynopsis location="mpm_common"><name>MaxRequestsPerChild</name>
163 <directivesynopsis location="mpm_common"><name>MaxSpareThreads</name>
165 <directivesynopsis location="mpm_common"><name>MinSpareThreads</name>
167 <directivesynopsis location="mpm_common"><name>ScoreBoardFile</name>
169 <directivesynopsis location="mpm_common"><name>SendBufferSize</name>
171 <directivesynopsis location="mpm_common"><name>ServerLimit</name>
173 <directivesynopsis location="mpm_common"><name>StartServers</name>
175 <directivesynopsis location="mpm_common"><name>ThreadLimit</name>
177 <directivesynopsis location="mpm_common"><name>ThreadsPerChild</name>
179 <directivesynopsis location="mpm_common"><name>ThreadStackSize</name>
181 <directivesynopsis location="mpm_common"><name>User</name>