event.xml revision b884d054f44c014e2590ca3b0d9c384dfa549f74
d24d4c5159bcb11c25bb294926cfe7105c789ea9slive<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
e942c741056732f50da2074b36fe59805d370650slive<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
5f5d1b4cc970b7f06ff8ef6526128e9a27303d88nd<!-- $LastChangedRevision$ -->
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding Licensed to the Apache Software Foundation (ASF) under one or more
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding contributor license agreements. See the NOTICE file distributed with
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding this work for additional information regarding copyright ownership.
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding The ASF licenses this file to You under the Apache License, Version 2.0
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding (the "License"); you may not use this file except in compliance with
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding the License. You may obtain a copy of the License at
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd Unless required by applicable law or agreed to in writing, software
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd distributed under the License is distributed on an "AS IS" BASIS,
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd See the License for the specific language governing permissions and
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd limitations under the License.
88f76f668542dcd72fc9d71577997967c6bf123bslive<description>A variant of the <module>worker</module> MPM with the goal
88f76f668542dcd72fc9d71577997967c6bf123bsliveof consuming threads only for connections with active processing</description>
88f76f668542dcd72fc9d71577997967c6bf123bslive <p>The <module>event</module> Multi-Processing Module (MPM) is
88f76f668542dcd72fc9d71577997967c6bf123bslive designed to allow more requests to be served simultaneously by
88f76f668542dcd72fc9d71577997967c6bf123bslive passing off some processing work to supporting threads, freeing up
88f76f668542dcd72fc9d71577997967c6bf123bslive the main threads to work on new requests. It is based on the
88f76f668542dcd72fc9d71577997967c6bf123bslive <module>worker</module> MPM, which implements a hybrid
88f76f668542dcd72fc9d71577997967c6bf123bslive multi-process multi-threaded server. Run-time configuration
88f76f668542dcd72fc9d71577997967c6bf123bslive directives are identical to those provided by
88f76f668542dcd72fc9d71577997967c6bf123bslive <code>--with-mpm=event</code> to the <program>configure</program>
88f76f668542dcd72fc9d71577997967c6bf123bslive script's arguments when building the <program>httpd</program>.</p>
88f76f668542dcd72fc9d71577997967c6bf123bslive<seealso><a href="worker.html">The worker MPM</a></seealso>
ed213de6d7481be782a20ecc2675bc57fd4fac69slive <p>This MPM tries to fix the 'keep alive problem' in HTTP. After a client
ed213de6d7481be782a20ecc2675bc57fd4fac69slive completes the first request, the client can keep the connection
ed213de6d7481be782a20ecc2675bc57fd4fac69slive open, and send further requests using the same socket. This can
ed213de6d7481be782a20ecc2675bc57fd4fac69slive save signifigant overhead in creating TCP connections. However,
ed213de6d7481be782a20ecc2675bc57fd4fac69slive Apache HTTP Server traditionally keeps an entire child process/thread waiting
88f76f668542dcd72fc9d71577997967c6bf123bslive for data from the client, which brings its own disadvantages. To
88f76f668542dcd72fc9d71577997967c6bf123bslive solve this problem, this MPM uses a dedicated thread to handle both
38677582e6ddf26e810728a68cbe560345486e48slive the Listening sockets, all sockets that are in a Keep Alive state,
38677582e6ddf26e810728a68cbe560345486e48slive and sockets where the handler and protocol filters have done their work
38677582e6ddf26e810728a68cbe560345486e48slive and the only remaining thing to do is send the data to the client. The
7647551a51db086eef1f5b651b2d6f174dffb8b3slive status page of <module>mod_status</module> shows how many connections are
7647551a51db086eef1f5b651b2d6f174dffb8b3slive in the mentioned states.</p>
0222f4c188bbd414e293e0b78a8e350e3054322anilgun <p>The improved connection handling does not yet work for certain
0222f4c188bbd414e293e0b78a8e350e3054322anilgun connection filters, in particular SSL. For SSL connections, this MPM will
0222f4c188bbd414e293e0b78a8e350e3054322anilgun fall back to the behaviour of the <module>worker</module> MPM and
0222f4c188bbd414e293e0b78a8e350e3054322anilgun reserve one worker thread per connection.</p>
0222f4c188bbd414e293e0b78a8e350e3054322anilgun <p>The MPM assumes that the underlying <code>apr_pollset</code>
0222f4c188bbd414e293e0b78a8e350e3054322anilgun implementation is reasonably threadsafe. This enables the MPM to
0222f4c188bbd414e293e0b78a8e350e3054322anilgun avoid excessive high level locking, or having to wake up the listener
0222f4c188bbd414e293e0b78a8e350e3054322anilgun thread in order to send it a keep-alive socket. This is currently
0222f4c188bbd414e293e0b78a8e350e3054322anilgun only compatible with KQueue and EPoll.</p>
0222f4c188bbd414e293e0b78a8e350e3054322anilgun<section id="requirements"><title>Requirements</title>
0222f4c188bbd414e293e0b78a8e350e3054322anilgun <p>This MPM depends on <glossary>APR</glossary>'s atomic
0222f4c188bbd414e293e0b78a8e350e3054322anilgun compare-and-swap operations for thread synchronization. If you are
0222f4c188bbd414e293e0b78a8e350e3054322anilgun compiling for an x86 target and you don't need to support 386s, or
0222f4c188bbd414e293e0b78a8e350e3054322anilgun you are compiling for a SPARC and you don't need to run on
0222f4c188bbd414e293e0b78a8e350e3054322anilgun pre-UltraSPARC chips, add
0222f4c188bbd414e293e0b78a8e350e3054322anilgun <program>configure</program> script's arguments. This will cause
0222f4c188bbd414e293e0b78a8e350e3054322anilgun APR to implement atomic operations using efficient opcodes not
0222f4c188bbd414e293e0b78a8e350e3054322anilgun available in older CPUs.</p>
0222f4c188bbd414e293e0b78a8e350e3054322anilgun <p>This MPM does not perform well on older platforms which lack good
0222f4c188bbd414e293e0b78a8e350e3054322anilgun threading, but the requirement for EPoll or KQueue makes this
7647551a51db086eef1f5b651b2d6f174dffb8b3slive <li>To use this MPM on FreeBSD, FreeBSD 5.3 or higher is recommended.
7647551a51db086eef1f5b651b2d6f174dffb8b3slive However, it is possible to run this MPM on FreeBSD 5.2.1, if you
7647551a51db086eef1f5b651b2d6f174dffb8b3slive use <code>libkse</code> (see <code>man libmap.conf</code>).</li>
88f76f668542dcd72fc9d71577997967c6bf123bslive <li>For NetBSD, at least version 2.0 is recommended.</li>
67a715b4352c3e25bff32fccad48350180393f5end <li>For Linux, a 2.6 kernel is recommended. It is also necessary to
67a715b4352c3e25bff32fccad48350180393f5end ensure that your version of <code>glibc</code> has been compiled
88f76f668542dcd72fc9d71577997967c6bf123bslive with support for EPoll.</li>
88f76f668542dcd72fc9d71577997967c6bf123bslive<directivesynopsis location="mpm_common"><name>CoreDumpDirectory</name>
0222f4c188bbd414e293e0b78a8e350e3054322anilgun</directivesynopsis>
88f76f668542dcd72fc9d71577997967c6bf123bslive<directivesynopsis location="mpm_common"><name>EnableExceptionHook</name>
67a715b4352c3e25bff32fccad48350180393f5end</directivesynopsis>
0222f4c188bbd414e293e0b78a8e350e3054322anilgun<directivesynopsis location="mpm_unixd"><name>Group</name>
0222f4c188bbd414e293e0b78a8e350e3054322anilgun</directivesynopsis>
aa997d6b651a6ac262d708b7f807a080d57c3844slive<directivesynopsis location="mpm_common"><name>Listen</name>
88f76f668542dcd72fc9d71577997967c6bf123bslive</directivesynopsis>
67a715b4352c3e25bff32fccad48350180393f5end<directivesynopsis location="mpm_common"><name>ListenBacklog</name>
67a715b4352c3e25bff32fccad48350180393f5end</directivesynopsis>
67a715b4352c3e25bff32fccad48350180393f5end<directivesynopsis location="mpm_common"><name>SendBufferSize</name>
88f76f668542dcd72fc9d71577997967c6bf123bslive</directivesynopsis>
39b600973267f27982523479ea58fd57414acd1ecovener<directivesynopsis location="mpm_common"><name>MaxRequestWorkers</name>
0222f4c188bbd414e293e0b78a8e350e3054322anilgun</directivesynopsis>
0222f4c188bbd414e293e0b78a8e350e3054322anilgun<directivesynopsis location="mpm_common"><name>MaxMemFree</name>
39b600973267f27982523479ea58fd57414acd1ecovener</directivesynopsis>
0222f4c188bbd414e293e0b78a8e350e3054322anilgun<directivesynopsis location="mpm_common"><name>MaxConnectionsPerChild</name>
0222f4c188bbd414e293e0b78a8e350e3054322anilgun</directivesynopsis>
88f76f668542dcd72fc9d71577997967c6bf123bslive<directivesynopsis location="mpm_common"><name>MaxSpareThreads</name>
88f76f668542dcd72fc9d71577997967c6bf123bslive</directivesynopsis>
67a715b4352c3e25bff32fccad48350180393f5end<directivesynopsis location="mpm_common"><name>MinSpareThreads</name>
0222f4c188bbd414e293e0b78a8e350e3054322anilgun</directivesynopsis>
0222f4c188bbd414e293e0b78a8e350e3054322anilgun<directivesynopsis location="mpm_common"><name>PidFile</name>
0222f4c188bbd414e293e0b78a8e350e3054322anilgun</directivesynopsis>
0222f4c188bbd414e293e0b78a8e350e3054322anilgun<directivesynopsis location="mpm_common"><name>ScoreBoardFile</name>
7bd130b92562a79fa13eb163ce47d8a708c70425rbowen</directivesynopsis>
7bd130b92562a79fa13eb163ce47d8a708c70425rbowen<directivesynopsis location="mpm_common"><name>ServerLimit</name>
7bd130b92562a79fa13eb163ce47d8a708c70425rbowen</directivesynopsis>
7bd130b92562a79fa13eb163ce47d8a708c70425rbowen<directivesynopsis location="mpm_common"><name>StartServers</name>
88f76f668542dcd72fc9d71577997967c6bf123bslive</directivesynopsis>
88f76f668542dcd72fc9d71577997967c6bf123bslive<directivesynopsis location="mpm_common"><name>ThreadLimit</name>
0dd298aa254f43fc223b1cc41e79d4a1fec308bcnd</directivesynopsis>
0dd298aa254f43fc223b1cc41e79d4a1fec308bcnd<directivesynopsis location="mpm_common"><name>ThreadsPerChild</name>
0dd298aa254f43fc223b1cc41e79d4a1fec308bcnd</directivesynopsis>
88f76f668542dcd72fc9d71577997967c6bf123bslive<directivesynopsis location="mpm_common"><name>ThreadStackSize</name>
0dd298aa254f43fc223b1cc41e79d4a1fec308bcnd</directivesynopsis>
88f76f668542dcd72fc9d71577997967c6bf123bslive<directivesynopsis location="mpm_unixd"><name>User</name>
88f76f668542dcd72fc9d71577997967c6bf123bslive</directivesynopsis>
0287d5784a0533920978a7eb8f3cdeace17b467arbowen<directivesynopsis>
52ebee778263c25c1b366f5e296d3f973fcb7aband<description>Limit concurrent connections per process</description>
0287d5784a0533920978a7eb8f3cdeace17b467arbowen<syntax>AsyncRequestWorkerFactor <var>factor</var></syntax>
0287d5784a0533920978a7eb8f3cdeace17b467arbowen<contextlist><context>server config</context> </contextlist>
2348633f2de9e8a3228db792f189d8b6ffdfdafand<compatibility>Available in version 2.3.13 and later</compatibility>
ca908c21f63a71c5efa7d32bd2cfafe9a42ba1fbrbowen <p>The event MPM handles some connections in an asynchronous way, where
2348633f2de9e8a3228db792f189d8b6ffdfdafand request worker threads are only allocated for short periods of time as
0287d5784a0533920978a7eb8f3cdeace17b467arbowen needed, and other (mostly SSL) connections with one request worker thread
0287d5784a0533920978a7eb8f3cdeace17b467arbowen reserved per connection. This can lead to situations where all workers are
0287d5784a0533920978a7eb8f3cdeace17b467arbowen tied up and no worker thread is available to handle new work on established
88f76f668542dcd72fc9d71577997967c6bf123bslive async connetions.</p>
88f76f668542dcd72fc9d71577997967c6bf123bslive <p>To mitigate this problem, the event MPM does two things: Firstly, it
88f76f668542dcd72fc9d71577997967c6bf123bslive limits the number of connections accepted per process, depending on the
88f76f668542dcd72fc9d71577997967c6bf123bslive number of idle request workers. Secondly, if all workers are busy, it will
0222f4c188bbd414e293e0b78a8e350e3054322anilgun close connections in keep-alive state even if the keep-alive timeout has
88f76f668542dcd72fc9d71577997967c6bf123bslive not expired. This allows the respective clients to reconnect to a
67a715b4352c3e25bff32fccad48350180393f5end different process which may still have worker threads available.</p>
88f76f668542dcd72fc9d71577997967c6bf123bslive <p>This directive can be used to fine-tune the per-process connection
88f76f668542dcd72fc9d71577997967c6bf123bslive limit. A process will only accept new connections if the current number of
88f76f668542dcd72fc9d71577997967c6bf123bslive connections is lower than:</p>
0222f4c188bbd414e293e0b78a8e350e3054322anilgun <directive module="mpm_common">ThreadsPerChild</directive> +
88f76f668542dcd72fc9d71577997967c6bf123bslive <p>This means the absolute maximum numbers of concurrent connections is:</p>
67a715b4352c3e25bff32fccad48350180393f5end <directive module="mpm_common">MaxRequestWorkers</directive>
aa997d6b651a6ac262d708b7f807a080d57c3844slive <p><directive module="mpm_common">MaxRequestWorkers</directive> was called
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier <directive>MaxClients</directive> prior to version 2.3.13. The above value
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier shows that the old name did not accurately describe its meaning for the event MPM.</p>
aa997d6b651a6ac262d708b7f807a080d57c3844slive <p><directive>AsyncRequestWorkerFactor</directive> can take non-integer
aa997d6b651a6ac262d708b7f807a080d57c3844slive</directivesynopsis>
c700b3b19086d0d0d52e74fd51e54864e3a11bbbpoirier</modulesynopsis>