From 0e9a484f2a45a97aa1f8cedf7bf18f8c5259cd64 Mon Sep 17 00:00:00 2001
From: Luca Toscano <elukey@apache.org>
Date: Thu, 15 Dec 2016 17:41:43 +0000
Subject: [PATCH] documentation rebuild

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1774501 13f79535-47bb-0310-9956-ffa450edef68
---
 docs/manual/mod/event.html.en | 69 ++++++++++++++++++++++++++++++++++-
 1 file changed, 68 insertions(+), 1 deletion(-)

diff --git a/docs/manual/mod/event.html.en b/docs/manual/mod/event.html.en
index a8af7208d8..0883cb1eec 100644
--- a/docs/manual/mod/event.html.en
+++ b/docs/manual/mod/event.html.en
@@ -139,10 +139,77 @@ 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 Scoreboard 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 safely terminate and free up a
+        scoreboard slot (for example handling long running requests, slow clients
+        or connections with keep-alive enabled). Two scenarios are very common:</p>
+        <ul>
+            <li>During a <a href="../stopping.html#graceful">graceful restart</a>.
+            The parent process signals all its children to complete
+            their work and terminate, while it reloads the config and forks new
+            processes. If the old children keep running for a while before stopping,
+            the scoreboard will be partially occupied until their slots are freed.
+            </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 new processes.
+            If the pattern repeats, the number of processes can rise quite a bit,
+            ending up in a mixture of old processes trying to stop and new ones
+            trying to do some work.
+            </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>.
+            <code class="directive"><a href="../mod/mpm_common.html#maxrequestworkers">MaxRequestWorkers</a></code> and
+            <code class="directive"><a href="../mod/mpm_common.html#threadsperchild">ThreadsPerChild</a></code> are used
+            to limit the amount of active processes, meanwhile
+            <code class="directive"><a href="../mod/mpm_common.html#serverlimit">ServerLimit</a></code> 
+            takes also into account the ones doing a graceful
+            close to allow extra slots when needed. The idea is to use
+            <code class="directive"><a href="../mod/mpm_common.html#serverlimit">ServerLimit</a></code> to instruct httpd
+            about how many overall processes are tolerated before impacting
+            the system resources.
+            </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>
 
-- 
2.40.0