mpm-event's documentation rebuild

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1772358 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 51 insertions, 1 deletions

diff --git a/docs/manual/mod/event.html.en b/docs/manual/mod/event.html.en
index b3eddc52e7..7f61dd4b0d 100644
--- a/docs/manual/mod/event.html.en
+++ b/docs/manual/mod/event.html.en
@@ -142,10 +142,60 @@ of the <code class="directive">AsyncRequestWorkerFactor</code>.</p>
 
     
 
+    <h3><a name="graceful-close" id="graceful-close">Graceful process termination and Scoreboard usage</a></h3>
+        <p>This mpm showed some scalability bottlenecks in the past leading to the following
+        error: "<strong>scoreboard is full, not at MaxRequestWorkers</strong>".
+        <code class="directive"><a href="../mod/mpm_common.html#maxrequestworkers">MaxRequestWorkers</a></code>
+        limits the number of simultaneous requests that will be served at any given time
+        and also the number of allowed processes
+        (<code class="directive"><a href="../mod/mpm_common.html#maxrequestworkers">MaxRequestWorkers</a></code> 
+        / <code class="directive"><a href="../mod/mpm_common.html#threadsperchild">ThreadsPerChild</a></code>), meanwhile
+        the Scoreboad is a representation of all the running processes and
+        the status of their worker threads. If the scoreboard is full (so all the
+        threads have a state that is not idle) but the number of active requests
+        served is not <code class="directive"><a href="../mod/mpm_common.html#maxrequestworkers">MaxRequestWorkers</a></code>,
+        it means that some of them are blocking new requests that could be served
+        but that are queued instead (up to the limit imposed by
+        <code class="directive"><a href="../mod/mpm_common.html#listenbacklog">ListenBacklog</a></code>). Most of the times
+        the threads are stuck in the Graceful state, namely they are waiting to
+        finish their work with a TCP connection to terminate and free a
+        scoreboard slot (for example handling long running requests, slow clients
+        or a connection with keep-alive enabled). Two scenarios are very common:</p>
+        <ul>
+            <li>Httpd graceful restart.</li>
+            <li>When the server load goes down in a way that causes httpd to
+            stop some processes (for example due to
+            <code class="directive"><a href="../mod/mpm_common.html#maxsparethreads">MaxSpareThreads</a></code>).
+            This is particularly problematic because when the load increases again,
+            httpd will try to start more processes.
+            If the pattern repeats, the number of processes can rise quite a bit.
+            </li>
+        </ul>
+        <p>From 2.4.24 onward, mpm-event is smarter and it is able to handle
+        graceful terminations in a much better way. Some of the improvements are:</p>
+        <ul>
+            <li>Allow the use of all the scoreboard slots up to
+            <code class="directive"><a href="../mod/mpm_common.html#serverlimit">ServerLimit</a></code>.</li>
+            <li>Force gracefully finishing processes to close their
+            connections in keep-alive state.</li>
+            <li>During graceful shutdown, if there are more running worker threads
+            than open connections for a given process, terminate these threads to
+            free resources faster (which may be needed for new processes).</li>
+            <li>If the scoreboard is full, prevent more processes to finish
+            gracefully due to reduced load until old processes have terminated
+            (otherwise the situation would get worse once the load increases again).</li>
+        </ul>
+        <p>The behavior described in the last point is completely observable via
+        <code class="module"><a href="../mod/mod_status.html">mod_status</a></code> in the connection summary table through two new
+        columns: "Slot" and "Stopping". The former indicates the PID and
+        the latter if the process is stopping or not; the extra state "Yes (old gen)"
+        indicates a process still running after a graceful restart.</p>
+    
+
     <h3><a name="limitations" id="limitations">Limitations</a></h3>
         <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
+        cases, this MPM will fall back to the behavior of the
         <code class="module"><a href="../mod/worker.html">worker</a></code> MPM and reserve one worker thread per connection.
         All modules shipped with the server are compatible with the event MPM.</p>