Hi Apache Devs!
I started an email thread some days ago on the dev mailing list to gather
information about mod_event, getting tons of interesting things to read. I
attached to this email a draft of how the new page should look like in my
opinion, please let me know your thoughts!
Notes about the changes:
- clear statement that event shares all the configuration directives with
worker, together with the fact that the number of threads is regulated by
processes multiplied by threads per child.
- explanation of the new async connections fields in mod_status.
- tried to add all the information about keep alives, writing and closing
connections that I've gathered so far. I added a disclaimer for the writing
ones and a big section called "limitations", but I have probably failed to
describe all the closing ones (not only lingering closes I suppose, but I
wasn't sure).
- clear logic connection between how it works and the
"AsyncRequestWorkerFactor" directive section (I am referring to the
sentence "The event MPM handles some connections in an asynchronous way").
Apologies for technical inaccuracies and/or typos!
Luca
Index: manual/mod/event.xml
===================================================================
--- manual/mod/event.xml (revision 1728162)
+++ manual/mod/event.xml (working copy)
@@ -31,12 +31,8 @@
<summary>
<p>The <module>event</module> Multi-Processing Module (MPM) is
designed to allow more requests to be served simultaneously by
- passing off some processing work to supporting threads, freeing up
- the main threads to work on new requests. It is based on the
- <module>worker</module> MPM, which implements a hybrid
- multi-process multi-threaded server. Run-time configuration
- directives are identical to those provided by
- <module>worker</module>.</p>
+ passing off some processing work to the listeners threads, freeing up
+ the worker threads to serve new requests.</p>
<p>To use the <module>event</module> MPM, add
<code>--with-mpm=event</code> to the <program>configure</program>
@@ -46,20 +42,63 @@
<seealso><a href="worker.html">The worker MPM</a></seealso>
+<section id="event-worker-relationship"><title>Relationship with the Worker
MPM</title>
+<p><module>event</module> is based on the <module>worker</module> MPM, which
implements a hybrid
+multi-process multi-threaded server. A single control process (the parent) is
responsible for launching
+child processes. Each child process creates a fixed number of server
+threads as specified in the <directive
module="mpm_common">ThreadsPerChild</directive> directive, as well
+as a listener thread which listens for connections and passes them to a worker
thread for processing when they arrive.</p>
+
+<p>Run-time configuration directives are identical to those provided by
<module>worker</module>, with the only addition
+of the <directive>AsyncRequestWorkerFactor</directive>.</p>
+
+</section>
+
<section id="how-it-works"><title>How it Works</title>
<p>This MPM tries to fix the 'keep alive problem' in HTTP. After a client
- completes the first request, the client can keep the connection
- open, and send further requests using the same socket. This can
- save significant overhead in creating TCP connections. However,
- Apache HTTP Server traditionally keeps an entire child process/thread
waiting
- for data from the client, which brings its own disadvantages. To
- solve this problem, this MPM uses a dedicated thread to handle both
- the Listening sockets, all sockets that are in a Keep Alive state,
- and sockets where the handler and protocol filters have done their work
- and the only remaining thing to do is send the data to the client. The
- status page of <module>mod_status</module> shows how many connections are
- in the mentioned states.</p>
+ completes the first request, it can keep the connection
+ open, sending further requests using the same socket and saving
+ significant overhead in creating TCP connections. However,
+ Apache HTTP Server traditionally keeps an entire child
+ process/thread waiting for data from the client, which brings its own
disadvantages.
+ To solve this problem, this MPM uses a dedicated listener thread for each
process
+ to handle both the Listening sockets, all sockets that are in a Keep Alive
state,
+ sockets where the handler and protocol filters have done their work
+ and the ones where the only remaining thing to do is send the data to the
client.
+ </p>
+ <p>The total amount of connections that a single process/threads block can
handle is regulated
+ by the <directive>AsyncRequestWorkerFactor</directive> directive.</p>
+
+<section id="async-connections"><title>Async connections</title>
+ Async connections would need a fixed dedicated worker thread with the
previous MPMs but not with event.
+ The status page of <module>mod_status</module> shows new columns under the
+ Async connections section:
+ <ul>
+ <dt>Writing</dt>
+ <dd>While sending the response to the client, it might happen that the
TCP write buffer fills up because the connection is too slow. Usually in this
case a <code>write()</code> to the socket returns <code>EWOULDBLOCK</code> or
<code>EAGAIN</code>, to become writable again after an idle time. The worker
holding the socket might be able to offload the waiting task to the listener
thread, that in turn will re-assign it to the first idle worker thread
available once an event will be raised for the socket (for example, "the socket
is now writable"). Please check the Limitations section for more information.
+ </dd>
+
+ <dt>Keep-alive</dt>
+ <dd>Keep Alive handling is the most basic improvement from the worker
MPM.
+ Once a worker thread finishes to flush the response to the client, it
can offload the
+ socket handling to the listener thread, that in turns will wait for
any event from the
+ OS, like "the socket is readable". If any new request comes from the
client, then the
+ listener will forward it to the first worker thread available.
Conversely, if the
+ <directive module="core">KeepAliveTimeout</directive> occurs then the
socket will be
+ closed by the listener. In this way the worker threads are not
responsible for idle
+ sockets and they can be re-used to serve other requests.</dd>
+
+ <dt>Closing</dt>
+ <dd>Sometimes the MPM needs to perform a lingering close, namely
sending back an early error to the client while it is still
+ transmitting data to httpd. Sending the response and then closing the
connection immediately is not the correct thing to do since the client (still
trying to send the rest of the request) would get a connection reset and could
not read the httpd's response. So in such cases, httpd tries to read the rest
of the request to allow the client to consume the response after the complete
delivery of the request. The lingering close it time bounded but it can take
relatively long time, so a worker thread can offload this work to the
listener.</dd>
+ </ul>
+
+ <p>These improvements are valid for both HTTP/HTTPS connections.</p>
+
+</section>
+
+<section id="limitations"><title>Limitations</title>
<p>The improved connection handling may not work for certain connection
filters that have declared themselves as incompatible with event. In these
cases, this MPM will fall back to the behaviour of the
@@ -72,8 +111,37 @@
connection to the client blocks while the filter is processing the
data, and the amount of data produced by the filter is too big to be
buffered in memory, the thread used for the request is not freed while
- httpd waits until the pending data is sent to the client.</p>
+ httpd waits until the pending data is sent to the client. Please note that
+ this limitation is only a corner case, it does not mean that the event MPM
+ defaults to worker in presence of TLS/SSL connections and/or
compression.</p>
+
+ <p>To illustrate this point we can think about the following two
situations:
+ serving a static asset (like a CSS file) versus serving content retrieved
from
+ FCGI/CGI or a proxied server. The former is predictable, namely the event
MPM
+ has full visibility on the end of the content and it can use events: the
worker
+ thread serving the response content can flush the first bytes until
<code>EWOULDBLOCK</code>
+ or <code>EAGAIN</code> is returned, delegating the rest to the listener.
This one in turn
+ waits for an event on the socket, and delegates the work to flush the rest
of the content
+ to the first idle worker thread. Meanwhile in the latter example
(FCGI/CGI/proxed content)
+ the MPM can't predict the end of the response and a worker thread has to
finish its work
+ before returning the control to the listener. The only alternative would
be to buffer the
+ response in memory, but it is not of course the safe option for the sake
of the
+ server's stability and memory footprint.
+ </p>
+</section>
+
+<section id="background"><title>Background material</title>
+ <p>The event model was made possible by the introduction of new APIs into
the supported operating systems:
+ <ul>
+ <li>epoll (Linux) </li>
+ <li>kqueue (BSD) </li>
+ <li>event ports (Solaris) </li>
+ </ul>
+ Before these new APIs where made available, the traditional
<code>select</code> and <code>poll</code> APIs had to be used.
+ Those APIs get slow if used to handle many connections or if the set of
connections rate of change is high.
+ The new APIs allow to monitor much more connections and they perform way
better when the set of connections to monitor changes frequently. So these APIs
made it possible to write the event MPM, that scales much better with the
typical HTTP pattern of many idle connections.</p>
+
<p>The MPM assumes that the underlying <code>apr_pollset</code>
implementation is reasonably threadsafe. This enables the MPM to
avoid excessive high level locking, or having to wake up the listener
@@ -81,6 +149,9 @@
only compatible with KQueue and EPoll.</p>
</section>
+
+</section>
+
<section id="requirements"><title>Requirements</title>
<p>This MPM depends on <glossary>APR</glossary>'s atomic
compare-and-swap operations for thread synchronization. If you are
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscr...@httpd.apache.org
For additional commands, e-mail: docs-h...@httpd.apache.org
