Return-Path: 
 <docs-return-7121-apmail-httpd-docs-archive=httpd.apache.org@httpd.apache.org>
Delivered-To: apmail-httpd-docs-archive@www.apache.org
Received: (qmail 95769 invoked from network); 5 Dec 2005 16:23:48 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199)
  by minotaur.apache.org with SMTP; 5 Dec 2005 16:23:48 -0000
Received: (qmail 7828 invoked by uid 500); 5 Dec 2005 16:23:40 -0000
Delivered-To: apmail-httpd-docs-archive@httpd.apache.org
Received: (qmail 7660 invoked by uid 500); 5 Dec 2005 16:23:39 -0000
Mailing-List: contact docs-help@httpd.apache.org; run by ezmlm
Precedence: bulk
list-help: <mailto:docs-help@httpd.apache.org>
list-unsubscribe: <mailto:docs-unsubscribe@httpd.apache.org>
List-Post: <mailto:docs@httpd.apache.org>
Reply-To: docs@httpd.apache.org
List-Id: <docs.httpd.apache.org>
Delivered-To: mailing list docs@httpd.apache.org
Received: (qmail 7610 invoked by uid 99); 5 Dec 2005 16:23:39 -0000
Received: from asf.osuosl.org (HELO asf.osuosl.org) (140.211.166.49)
    by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 05 Dec 2005 08:23:39 -0800
X-ASF-Spam-Status: No, hits=0.0 required=10.0
	tests=
X-Spam-Check-By: apache.org
Received-SPF: pass (asf.osuosl.org: local policy)
Received: from [82.195.155.60] (HELO dochas.stdlib.net) (82.195.155.60)
    by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 05 Dec 2005 08:23:34 -0800
Received: from firebird by dochas.stdlib.net with local (Exim 4.50)
	id 1EjJ7Z-0005pg-6C
	for docs@httpd.apache.org; Mon, 05 Dec 2005 16:23:21 +0000
Date: Mon, 5 Dec 2005 16:23:21 +0000
From: Noirin Plunkett <firebird@nerdchic.net>
To: docs@httpd.apache.org
Subject: event MPM documented, worker & leader tidied a little
Message-ID: <20051205162321.GA22352@dochas.stdlib.net>
Reply-To: firebird@nerdchic.net
Mime-Version: 1.0
Content-Type: multipart/mixed; boundary="Kj7319i9nmIyA2yE"
Content-Disposition: inline
User-Agent: Mutt/1.5.9i
X-Virus-Checked: Checked by ClamAV on apache.org
X-Spam-Rating: minotaur.apache.org 1.6.2 0/1000/N

--Kj7319i9nmIyA2yE
Content-Type: text/plain; charset=iso-8859-15
Content-Disposition: inline

I've taken the comments from the source code in order to flesh out the
documentation for the event MPM a little - it was looking almost
painfully bare, and there was some hopefully useful information in the
code.

I've also made a few minor/cosmetic changes to the leader & worker MPM
pages, to tidy up a little.

Patch for all three is attached.

Noirin

--Kj7319i9nmIyA2yE
Content-Type: text/plain; charset=iso-8859-15
Content-Disposition: attachment; filename="mpm.patch"

Index: event.xml
===================================================================
--- event.xml	(revision 354034)
+++ event.xml	(working copy)
@@ -33,11 +33,40 @@
       <p>This MPM is experimental, so it may or may not work
       as expected.</p>
     </note>
+
+    <p>The <module>event</module> Multi-Processing Module (MPM) is based on the
+    <module>worker</module> MPM, which implements a hybrid multi-process
+    multi-threaded server. By using threads to serve requests, it is able to
+    serve a large number of requests with fewer system resources than a
+    process-based server. However, it retains much of the stability of a
+    process-based server by keeping multiple processes available, each with
+    many threads.</p>
     
     <p>To use the <module>event</module> MPM, add
       <code>--with-mpm=event</code> to the <program>configure</program>
       script's arguments when building the <program>httpd</program>.</p>
-  
+</summary>
+
+<seealso><a href="worker.html">The worker MPM</a></seealso>
+
+<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 signifigant overhead in creating TCP connections. However,
+    Apache 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, and all sockets that are in a Keep Alive
+    state.</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
+    thread in order to send it a keep-alive socket. This is currently
+    only compatible with KQueue and EPoll.</p>
+</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
     compiling for an x86 target and you don't need to support 386s, or
@@ -46,9 +75,33 @@
     <code>--enable-nonportable-atomics=yes</code> to the
     <program>configure</program> script's arguments. This will cause
     APR to implement atomic operations using efficient opcodes not
-    available in older CPUs.</p> 
-</summary>
+    available in older CPUs.</p>
 
+    <p>This MPM does not perform well on older platforms which lack good
+    threading, but the requirement for EPoll or KQueue makes this
+    moot.</p>
+
+    <ul>
+    
+      <li>To use this MPM on FreeBSD, FreeBSD 5.3 or higher is recommended.
+      However, it is possible to run this MPM on FreeBSD 5.2.1, if you
+      use <code>libkse</code> (see <code>man libmap.conf</code>).</li>
+
+      <li>For NetBSD, at least version 2.0 is recommended.</li>
+
+      <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>
+
+<section id="issues"><title>Issues</title>
+    <p>At present, this MPM is incompatible with <module>mod_ssl</module>, and
+    other input filters.</p>
+</section>
+
+
 <directivesynopsis location="mpm_common"><name>AcceptMutex</name>
 </directivesynopsis>
 <directivesynopsis location="mpm_common"><name>CoreDumpDirectory</name>
Index: leader.xml
===================================================================
--- leader.xml	(revision 354034)
+++ leader.xml	(working copy)
@@ -43,7 +43,9 @@
     <p>To use the <module>leader</module> MPM, add
       <code>--with-mpm=leader</code> to the <program>configure</program>
       script's arguments when building the <program>httpd</program>.</p>
-  
+
+</summary>
+<section id="requirements"><title>Requirements</title>
     <p>This MPM depends on APR's atomic compare-and-swap operations for
     thread synchronization. If you are compiling for an x86 target
     and you don't need to support 386s, or you are compiling for a
@@ -52,8 +54,10 @@
     <program>configure</program> script's arguments. This will cause
     APR to implement atomic operations
     using efficient opcodes not available in older CPUs.</p>
-</summary>
+</section>
 
+<seealso><a href="worker.html">The worker MPM</a></seealso>
+
 <directivesynopsis location="mpm_common"><name>AcceptMutex</name>
 </directivesynopsis>
 <directivesynopsis location="mpm_common"><name>CoreDumpDirectory</name>
Index: worker.xml
===================================================================
--- worker.xml	(revision 354034)
+++ worker.xml	(working copy)
@@ -30,9 +30,9 @@
 
 <summary>
     <p>This Multi-Processing Module (MPM) implements a hybrid
-    multi-process multi-threaded server.  By using threads to serve
+    multi-process multi-threaded server. By using threads to serve
     requests, it is able to serve a large number of requests with
-    less system resources than a process-based server.  Yet it
+    fewer system resources than a process-based server. However, it
     retains much of the stability of a process-based server by
     keeping multiple processes available, each with many threads.</p>
 
@@ -60,7 +60,7 @@
     threads or processes to be created before their requests can be
     served. The number of processes that will initially launched is
     set by the <directive module="mpm_common">StartServers</directive>
-    directive. Then during operation, Apache assesses the total number
+    directive. During operation, Apache assesses the total number
     of idle threads in all processes, and forks or kills processes to
     keep this number within the boundaries specified by <directive
     module="mpm_common">MinSpareThreads</directive> and <directive
@@ -91,14 +91,14 @@
     non-default values are specified for these directives, they 
     should appear before other <module>worker</module> directives.</p>
 
-    <p>In addition to a the set of active child processes, there may 
-    be additional child processes which are terminating but where at
+    <p>In addition to the set of active child processes, there may 
+    be additional child processes which are terminating, but where at
     least one server thread is still handling an existing client
     connection.  Up to <directive 
     module="mpm_common">MaxClients</directive> terminating processes 
     may be present, though the actual number can be expected to be 
     much smaller.  This behavior can be avoided by disabling the 
-    termination of individual child processes, which is achieved by 
+    termination of individual child processes, which is achieved using
     the following:</p>
 
     <ul>


--Kj7319i9nmIyA2yE
Content-Type: text/plain; charset=us-ascii

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
--Kj7319i9nmIyA2yE--