a78048ccbdb6256da15e6b0e7e95355e480c2301nd<?xml version="1.0"?>

a78048ccbdb6256da15e6b0e7e95355e480c2301nd<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

a78048ccbdb6256da15e6b0e7e95355e480c2301nd<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

a78048ccbdb6256da15e6b0e7e95355e480c2301nd

b05ab3ff5ab54aa22610b13d56eaba6ddfc3db60nd

e23d878014f00a27b043a25e59f809c7af497e5ctakashi<modulesynopsis metafile="event.xml.meta">

e23d878014f00a27b043a25e59f809c7af497e5ctakashi<name>event</name>

a78048ccbdb6256da15e6b0e7e95355e480c2301nd<description>A variant of the <module>worker</module> MPM with the goal

9bcfc3697a91b5215893a7d0206865b13fc72148ndof consuming threads only for connections with active processing</description>

9bcfc3697a91b5215893a7d0206865b13fc72148nd<status>MPM</status>

a78048ccbdb6256da15e6b0e7e95355e480c2301nd<sourcefile>event.c</sourcefile>

a78048ccbdb6256da15e6b0e7e95355e480c2301nd<identifier>mpm_event_module</identifier>

a78048ccbdb6256da15e6b0e7e95355e480c2301nd

a78048ccbdb6256da15e6b0e7e95355e480c2301nd<summary>

a78048ccbdb6256da15e6b0e7e95355e480c2301nd <p>The <module>event</module> Multi-Processing Module (MPM) is

a78048ccbdb6256da15e6b0e7e95355e480c2301nd designed to allow more requests to be served simultaneously by

a78048ccbdb6256da15e6b0e7e95355e480c2301nd passing off some processing work to supporting threads, freeing up

a78048ccbdb6256da15e6b0e7e95355e480c2301nd the main threads to work on new requests. It is based on the

a78048ccbdb6256da15e6b0e7e95355e480c2301nd <module>worker</module> MPM, which implements a hybrid

a78048ccbdb6256da15e6b0e7e95355e480c2301nd multi-process multi-threaded server. Run-time configuration

a78048ccbdb6256da15e6b0e7e95355e480c2301nd directives are identical to those provided by

a78048ccbdb6256da15e6b0e7e95355e480c2301nd <module>worker</module>.</p>

a78048ccbdb6256da15e6b0e7e95355e480c2301nd

a78048ccbdb6256da15e6b0e7e95355e480c2301nd <p>To use the <module>event</module> MPM, add

a78048ccbdb6256da15e6b0e7e95355e480c2301nd <code>--with-mpm=event</code> to the <program>configure</program>

a78048ccbdb6256da15e6b0e7e95355e480c2301nd script's arguments when building the <program>httpd</program>.</p>

a78048ccbdb6256da15e6b0e7e95355e480c2301nd

a78048ccbdb6256da15e6b0e7e95355e480c2301nd</summary>

a78048ccbdb6256da15e6b0e7e95355e480c2301nd

a78048ccbdb6256da15e6b0e7e95355e480c2301nd<seealso><a href="worker.html">The worker MPM</a></seealso>

a78048ccbdb6256da15e6b0e7e95355e480c2301nd

a78048ccbdb6256da15e6b0e7e95355e480c2301nd<section id="how-it-works"><title>How it Works</title>

a78048ccbdb6256da15e6b0e7e95355e480c2301nd <p>This MPM tries to fix the 'keep alive problem' in HTTP. After a client

a78048ccbdb6256da15e6b0e7e95355e480c2301nd completes the first request, the client can keep the connection

a78048ccbdb6256da15e6b0e7e95355e480c2301nd open, and send further requests using the same socket. This can

a78048ccbdb6256da15e6b0e7e95355e480c2301nd save significant overhead in creating TCP connections. However,

a78048ccbdb6256da15e6b0e7e95355e480c2301nd Apache HTTP Server traditionally keeps an entire child process/thread waiting

a78048ccbdb6256da15e6b0e7e95355e480c2301nd for data from the client, which brings its own disadvantages. To

a78048ccbdb6256da15e6b0e7e95355e480c2301nd solve this problem, this MPM uses a dedicated thread to handle both

a78048ccbdb6256da15e6b0e7e95355e480c2301nd the Listening sockets, all sockets that are in a Keep Alive state,

a78048ccbdb6256da15e6b0e7e95355e480c2301nd and sockets where the handler and protocol filters have done their work

a78048ccbdb6256da15e6b0e7e95355e480c2301nd and the only remaining thing to do is send the data to the client. The

a78048ccbdb6256da15e6b0e7e95355e480c2301nd status page of <module>mod_status</module> shows how many connections are

8bb7126c063c34d63966733988411f72dfcb2294maczniak in the mentioned states.</p>

8bb7126c063c34d63966733988411f72dfcb2294maczniak

8bb7126c063c34d63966733988411f72dfcb2294maczniak <p>The improved connection handling does not yet work for certain

a78048ccbdb6256da15e6b0e7e95355e480c2301nd connection filters, in particular SSL. For SSL connections, this MPM will

a78048ccbdb6256da15e6b0e7e95355e480c2301nd fall back to the behaviour of the <module>worker</module> MPM and

a78048ccbdb6256da15e6b0e7e95355e480c2301nd reserve one worker thread per connection.</p>

a78048ccbdb6256da15e6b0e7e95355e480c2301nd

a78048ccbdb6256da15e6b0e7e95355e480c2301nd <p>The MPM assumes that the underlying <code>apr_pollset</code>

a78048ccbdb6256da15e6b0e7e95355e480c2301nd implementation is reasonably threadsafe. This enables the MPM to

a78048ccbdb6256da15e6b0e7e95355e480c2301nd avoid excessive high level locking, or having to wake up the listener

a78048ccbdb6256da15e6b0e7e95355e480c2301nd thread in order to send it a keep-alive socket. This is currently

a78048ccbdb6256da15e6b0e7e95355e480c2301nd only compatible with KQueue and EPoll.</p>

a78048ccbdb6256da15e6b0e7e95355e480c2301nd

a78048ccbdb6256da15e6b0e7e95355e480c2301nd</section>

a78048ccbdb6256da15e6b0e7e95355e480c2301nd<section id="requirements"><title>Requirements</title>

a78048ccbdb6256da15e6b0e7e95355e480c2301nd <p>This MPM depends on <glossary>APR</glossary>'s atomic

a78048ccbdb6256da15e6b0e7e95355e480c2301nd compare-and-swap operations for thread synchronization. If you are

a78048ccbdb6256da15e6b0e7e95355e480c2301nd compiling for an x86 target and you don't need to support 386s, or

a78048ccbdb6256da15e6b0e7e95355e480c2301nd you are compiling for a SPARC and you don't need to run on

a78048ccbdb6256da15e6b0e7e95355e480c2301nd pre-UltraSPARC chips, add

a78048ccbdb6256da15e6b0e7e95355e480c2301nd <code>--enable-nonportable-atomics=yes</code> to the

a78048ccbdb6256da15e6b0e7e95355e480c2301nd <program>configure</program> script's arguments. This will cause

a78048ccbdb6256da15e6b0e7e95355e480c2301nd APR to implement atomic operations using efficient opcodes not

a78048ccbdb6256da15e6b0e7e95355e480c2301nd available in older CPUs.</p>

a78048ccbdb6256da15e6b0e7e95355e480c2301nd

a78048ccbdb6256da15e6b0e7e95355e480c2301nd <p>This MPM does not perform well on older platforms which lack good

a78048ccbdb6256da15e6b0e7e95355e480c2301nd threading, but the requirement for EPoll or KQueue makes this

a78048ccbdb6256da15e6b0e7e95355e480c2301nd moot.</p>

a78048ccbdb6256da15e6b0e7e95355e480c2301nd

a78048ccbdb6256da15e6b0e7e95355e480c2301nd <ul>

a78048ccbdb6256da15e6b0e7e95355e480c2301nd

b05ab3ff5ab54aa22610b13d56eaba6ddfc3db60nd <li>To use this MPM on FreeBSD, FreeBSD 5.3 or higher is recommended.

e23d878014f00a27b043a25e59f809c7af497e5ctakashi However, it is possible to run this MPM on FreeBSD 5.2.1, if you

e23d878014f00a27b043a25e59f809c7af497e5ctakashi use <code>libkse</code> (see <code>man libmap.conf</code>).</li>

a78048ccbdb6256da15e6b0e7e95355e480c2301nd

6eed902e5b4d3e016e220bfbf8769a87c4cb242enoodl <li>For NetBSD, at least version 2.0 is recommended.</li>

a78048ccbdb6256da15e6b0e7e95355e480c2301nd

a78048ccbdb6256da15e6b0e7e95355e480c2301nd <li>For Linux, a 2.6 kernel is recommended. It is also necessary to

ensure that your version of <code>glibc</code> has been compiled

with support for EPoll.</li>

</ul>

</section>

<directivesynopsis location="mpm_common"><name>CoreDumpDirectory</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>EnableExceptionHook</name>

</directivesynopsis>

<directivesynopsis location="mod_unixd"><name>Group</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>Listen</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>ListenBacklog</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>SendBufferSize</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>MaxRequestWorkers</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>MaxMemFree</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>MaxConnectionsPerChild</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>MaxSpareThreads</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>MinSpareThreads</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>PidFile</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>ScoreBoardFile</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>ServerLimit</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>StartServers</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>ThreadLimit</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>ThreadsPerChild</name>

</directivesynopsis>

<directivesynopsis location="mpm_common"><name>ThreadStackSize</name>

</directivesynopsis>

<directivesynopsis location="mod_unixd"><name>User</name>

</directivesynopsis>

<directivesynopsis>

<name>AsyncRequestWorkerFactor</name>

<description>Limit concurrent connections per process</description>

<syntax>AsyncRequestWorkerFactor <var>factor</var></syntax>

<default>2</default>

<contextlist><context>server config</context> </contextlist>

<compatibility>Available in version 2.3.13 and later</compatibility>

<usage>

<p>The event MPM handles some connections in an asynchronous way, where

request worker threads are only allocated for short periods of time as

needed, and other (mostly SSL) connections with one request worker thread

reserved per connection. This can lead to situations where all workers are

tied up and no worker thread is available to handle new work on established

async connections.</p>

<p>To mitigate this problem, the event MPM does two things: Firstly, it

limits the number of connections accepted per process, depending on the

number of idle request workers. Secondly, if all workers are busy, it will

close connections in keep-alive state even if the keep-alive timeout has

not expired. This allows the respective clients to reconnect to a

different process which may still have worker threads available.</p>

<p>This directive can be used to fine-tune the per-process connection

limit. A process will only accept new connections if the current number of

connections (not counting connections in the "closing" state) is lower

than:</p>

<p class="indent"><strong>

<directive module="mpm_common">ThreadsPerChild</directive> +

(<directive>AsyncRequestWorkerFactor</directive> *

<var>number of idle workers</var>)

</strong></p>

<p>This means the absolute maximum numbers of concurrent connections is:</p>

<p class="indent"><strong>

(<directive>AsyncRequestWorkerFactor</directive> + 1) *

<directive module="mpm_common">MaxRequestWorkers</directive>

</strong></p>

<p><directive module="mpm_common">MaxRequestWorkers</directive> was called

<directive>MaxClients</directive> prior to version 2.3.13. The above value

shows that the old name did not accurately describe its meaning for the event MPM.</p>

<p><directive>AsyncRequestWorkerFactor</directive> can take non-integer

arguments, e.g "1.5".</p>

</usage>

</directivesynopsis>

</modulesynopsis>