event.xml revision 35e26fe7e0920b607afc63a645c846633f0e6889
530eba85dbd41b8a0fa5255d3648d1440199a661slive<!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.
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<description>A variant of the <module>worker</module> MPM with the goal
80c4526970a11f37c0f8e3b82afdf03902dac3f3sliveof consuming threads only for connections with active processing</description>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <p>The <module>event</module> Multi-Processing Module (MPM) is
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna designed to allow more requests to be served simultaneously by
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna passing off some processing work to supporting threads, freeing up
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna the main threads to work on new requests. It is based on the
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <module>worker</module> MPM, which implements a hybrid
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna multi-process multi-threaded server. Run-time configuration
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna directives are identical to those provided by
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <code>--with-mpm=event</code> to the <program>configure</program>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna script's arguments when building the <program>httpd</program>.</p>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna<seealso><a href="worker.html">The worker MPM</a></seealso>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna<section id="how-it-works"><title>How it Works</title>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <p>This MPM tries to fix the 'keep alive problem' in HTTP. After a client
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna completes the first request, the client can keep the connection
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna open, and send further requests using the same socket. This can
90efa9f1730742d874edb5a7803adce11c9f08eanoodl save significant overhead in creating TCP connections. However,
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna Apache HTTP Server traditionally keeps an entire child process/thread waiting
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna for data from the client, which brings its own disadvantages. To
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna solve this problem, this MPM uses a dedicated thread to handle both
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna the Listening sockets, all sockets that are in a Keep Alive state,
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna and sockets where the handler and protocol filters have done their work
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna and the only remaining thing to do is send the data to the client. The
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna status page of <module>mod_status</module> shows how many connections are
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna in the mentioned states.</p>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <p>The improved connection handling may not work for certain connection
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna filters that have declared themselves as incompatible with event. In these
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna cases, this MPM will fall back to the behaviour of the
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <module>worker</module> MPM and reserve one worker thread per connection.
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna All modules shipped with the server are compatible with the event MPM.</p>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <p>The MPM assumes that the underlying <code>apr_pollset</code>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna implementation is reasonably threadsafe. This enables the MPM to
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna avoid excessive high level locking, or having to wake up the listener
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna thread in order to send it a keep-alive socket. This is currently
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna only compatible with KQueue and EPoll.</p>
3139522a1418fa699dfd78dcf8dde54253f2c55cnoirin<section id="requirements"><title>Requirements</title>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <p>This MPM depends on <glossary>APR</glossary>'s atomic
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna compare-and-swap operations for thread synchronization. If you are
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna compiling for an x86 target and you don't need to support 386s, or
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna you are compiling for a SPARC and you don't need to run on
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive pre-UltraSPARC chips, add
313bb560bc5c323cfd40c9cad7335b4b8e060aedkess <program>configure</program> script's arguments. This will cause
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive APR to implement atomic operations using efficient opcodes not
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive available in older CPUs.</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>This MPM does not perform well on older platforms which lack good
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive threading, but the requirement for EPoll or KQueue makes this
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <li>To use this MPM on FreeBSD, FreeBSD 5.3 or higher is recommended.
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive However, it is possible to run this MPM on FreeBSD 5.2.1, if you
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive use <code>libkse</code> (see <code>man libmap.conf</code>).</li>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <li>For NetBSD, at least version 2.0 is recommended.</li>
fb77c505254b6e9c925e23e734463e87574f8f40kess <li>For Linux, a 2.6 kernel is recommended. It is also necessary to
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive ensure that your version of <code>glibc</code> has been compiled
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive with support for EPoll.</li>
fb77c505254b6e9c925e23e734463e87574f8f40kess<directivesynopsis location="mpm_common"><name>CoreDumpDirectory</name>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</directivesynopsis>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<directivesynopsis location="mpm_common"><name>EnableExceptionHook</name>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</directivesynopsis>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<directivesynopsis location="mod_unixd"><name>Group</name>
fb77c505254b6e9c925e23e734463e87574f8f40kess</directivesynopsis>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<directivesynopsis location="mpm_common"><name>Listen</name>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</directivesynopsis>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<directivesynopsis location="mpm_common"><name>ListenBacklog</name>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</directivesynopsis>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<directivesynopsis location="mpm_common"><name>SendBufferSize</name>
fb77c505254b6e9c925e23e734463e87574f8f40kess</directivesynopsis>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<directivesynopsis location="mpm_common"><name>MaxRequestWorkers</name>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</directivesynopsis>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<directivesynopsis location="mpm_common"><name>MaxMemFree</name>
fb77c505254b6e9c925e23e734463e87574f8f40kess</directivesynopsis>
fb77c505254b6e9c925e23e734463e87574f8f40kess<directivesynopsis location="mpm_common"><name>MaxConnectionsPerChild</name>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</directivesynopsis>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<directivesynopsis location="mpm_common"><name>MaxSpareThreads</name>
fb77c505254b6e9c925e23e734463e87574f8f40kess</directivesynopsis>
6b64034fa2a644ba291c484c0c01c7df5b8d982ckess<directivesynopsis location="mpm_common"><name>MinSpareThreads</name>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</directivesynopsis>
bc4b55ec8f31569d606d5680d50189a355bcd7a6rbowen<directivesynopsis location="mpm_common"><name>PidFile</name>
fb77c505254b6e9c925e23e734463e87574f8f40kess</directivesynopsis>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<directivesynopsis location="mpm_common"><name>ScoreBoardFile</name>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</directivesynopsis>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<directivesynopsis location="mpm_common"><name>ServerLimit</name>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</directivesynopsis>
fb77c505254b6e9c925e23e734463e87574f8f40kess<directivesynopsis location="mpm_common"><name>StartServers</name>
fb77c505254b6e9c925e23e734463e87574f8f40kess</directivesynopsis>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<directivesynopsis location="mpm_common"><name>ThreadLimit</name>
fb77c505254b6e9c925e23e734463e87574f8f40kess</directivesynopsis>
fb77c505254b6e9c925e23e734463e87574f8f40kess<directivesynopsis location="mpm_common"><name>ThreadsPerChild</name>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</directivesynopsis>
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd<directivesynopsis location="mpm_common"><name>ThreadStackSize</name>
130d299c4b2b15be45532a176604c71fdc7bea5bnd</directivesynopsis>
130d299c4b2b15be45532a176604c71fdc7bea5bnd</directivesynopsis>
130d299c4b2b15be45532a176604c71fdc7bea5bnd<directivesynopsis>
130d299c4b2b15be45532a176604c71fdc7bea5bnd<description>Limit concurrent connections per process</description>
130d299c4b2b15be45532a176604c71fdc7bea5bnd<syntax>AsyncRequestWorkerFactor <var>factor</var></syntax>
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd<contextlist><context>server config</context> </contextlist>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<compatibility>Available in version 2.3.13 and later</compatibility>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>The event MPM handles some connections in an asynchronous way, where
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive request worker threads are only allocated for short periods of time as
003f0c9fda6664daf5092a0e42f65ede20098153slive needed, and other connections with one request worker thread reserved per
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd connection. This can lead to situations where all workers are tied up and
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive no worker thread is available to handle new work on established async
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive connections.</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>To mitigate this problem, the event MPM does two things: Firstly, it
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive limits the number of connections accepted per process, depending on the
313bb560bc5c323cfd40c9cad7335b4b8e060aedkess number of idle request workers. Secondly, if all workers are busy, it will
003f0c9fda6664daf5092a0e42f65ede20098153slive close connections in keep-alive state even if the keep-alive timeout has
003f0c9fda6664daf5092a0e42f65ede20098153slive not expired. This allows the respective clients to reconnect to a
6b64034fa2a644ba291c484c0c01c7df5b8d982ckess different process which may still have worker threads available.</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>This directive can be used to fine-tune the per-process connection
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd limit. A process will only accept new connections if the current number of
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd connections (not counting connections in the "closing" state) is lower
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <directive module="mpm_common">ThreadsPerChild</directive> +
130d299c4b2b15be45532a176604c71fdc7bea5bnd <p>This means the absolute maximum numbers of concurrent connections is:</p>
130d299c4b2b15be45532a176604c71fdc7bea5bnd <directive module="mpm_common">MaxRequestWorkers</directive>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p><directive module="mpm_common">MaxRequestWorkers</directive> was called
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <directive>MaxClients</directive> prior to version 2.3.13. The above value
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive shows that the old name did not accurately describe its meaning for the event MPM.</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p><directive>AsyncRequestWorkerFactor</directive> can take non-integer
684f2a9a422185adda0692a1203c5ad6687fc5c5nd</directivesynopsis>
530eba85dbd41b8a0fa5255d3648d1440199a661slive</modulesynopsis>