45632c3574ce843b9e85b9f73efe75b7b809f789slive<?xml version="1.0"?>

29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

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

29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd

6df89e6e4adeb986b41b7ec6b7593a887e031ce7nd

6df89e6e4adeb986b41b7ec6b7593a887e031ce7nd<modulesynopsis metafile="event.xml.meta">

3b3b7fc78d1f5bfc2769903375050048ff41ff26nd<name>event</name>

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

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

7add1372edb1ee95a2c4d1314df4c7567bda7c62jim<status>MPM</status>

7add1372edb1ee95a2c4d1314df4c7567bda7c62jim<sourcefile>event.c</sourcefile>

7add1372edb1ee95a2c4d1314df4c7567bda7c62jim<identifier>mpm_event_module</identifier>

7f5b59ccc63c0c0e3e678a168f09ee6a2f51f9d0nd

7f5b59ccc63c0c0e3e678a168f09ee6a2f51f9d0nd<summary>

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

63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end designed to allow more requests to be served simultaneously by

3b3b7fc78d1f5bfc2769903375050048ff41ff26nd passing off some processing work to supporting threads, freeing up

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

29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd <module>worker</module> MPM, which implements a hybrid

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

52fff662005b1866a3ff09bb6c902800c5cc6dedjerenkrantz directives are identical to those provided by

35b1112eadc3479a2d81ea1b836aa87f21505ee9jerenkrantz <module>worker</module>.</p>

52fff662005b1866a3ff09bb6c902800c5cc6dedjerenkrantz

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

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

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

29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd

29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd</summary>

29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd

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

29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd

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

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

29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd completes the first request, the client can keep the connection

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

63581ee088272ef76aa8d053609dc1705c222deesf save signifigant overhead in creating TCP connections. However,

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

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

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

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

29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd and sockets where the handler and protocol filters have done their work

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

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

4af55bbfdbff2cae0cd3195876c93ea991523d1fcolm in the mentioned states.</p>

29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd

29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd <p>The improved connection handling does not yet work for certain

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

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

29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd reserve one worker thread per connection.</p>

29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd

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

29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd implementation is reasonably threadsafe. This enables the MPM to

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

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

38819b9bf8b10d6db4842fb5a4ede7828b409819rbowen only compatible with KQueue and EPoll.</p>

29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd

29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd</section>

29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd<section id="requirements"><title>Requirements</title>

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

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

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

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

29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd pre-UltraSPARC chips, add

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

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

29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd APR to implement atomic operations using efficient opcodes not

29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd available in older CPUs.</p>

29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd

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

29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd threading, but the requirement for EPoll or KQueue makes this

29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd moot.</p>

29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd

c5ac4f57bfd156a62495b9c6a049f05bbcb69acarbowen <ul>

29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd

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

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

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

29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd

29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd <li>For NetBSD, at least version 2.0 is recommended.</li>

3b3b7fc78d1f5bfc2769903375050048ff41ff26nd

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

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

7add1372edb1ee95a2c4d1314df4c7567bda7c62jim with support for EPoll.</li>

7add1372edb1ee95a2c4d1314df4c7567bda7c62jim

7add1372edb1ee95a2c4d1314df4c7567bda7c62jim </ul>

7f5b59ccc63c0c0e3e678a168f09ee6a2f51f9d0nd</section>

7f5b59ccc63c0c0e3e678a168f09ee6a2f51f9d0nd

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

63f06dce77bb2d9b1c5aa5deeb47a1069987fd1end</directivesynopsis>

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

9c1260efa52c82c2a58e5b5f20cd6902563d95f5rbowen</directivesynopsis>

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

29fb68cf24dbdb4985cbb4734cb6074ea4bbab26nd</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 connetions.</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 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>