Add Wiki documentation explaining maximum-requests daemon-restarting behavior

[GoogleCodeExporter]

People are occasionally bitten by the behavior of maximum-requests with regards 
to dropping requests that take more than 5 seconds to finish once the limit is 
reached. The behavior makes sense, but it seems like the wiki documentation on 
maximum-requests could benefit from a short blurb explaining the behavior so 
that it doesn't come as a surprise.

An example:
maximum-requests=nnn

Defines a limit on the number of requests a daemon process should process 
before it is shutdown and restarted. Setting this to a non zero value has the 
benefit of limiting the amount of memory that a process can consume by 
(accidental) memory leakage. Be aware however, that when the limit is reached 
and the process is restarted, any requests that take more than shutdown-timeout 
(default of 5 seconds) will be killed, potentially resulting in dropped 
requests.

If this option is not defined, or is defined to be 0, then the daemon process 
will be persistent and will continue to service requests until Apache itself is 
restarted or shutdown.

Original issue reported on code.google.com by w...@policystat.com on 17 Dec 2010 at 9:07

[GoogleCodeExporter]

I'd like to encourage the proposed change, perhaps with even stronger wording.
We had issues with corrupt Mercurial clones at CPython's hg.python.org, which I 
initially wrongly attributed to multithreading. It turns out that they were due 
to the maximum-requests directive, which apparently terminates any pending 
request after the shutdown timeout.
The problem was probably witnessed much more often in a multithreaded setup 
because the shutdown timeout would affect many requests at once compared to a 
multiprocess single-thread-per-process setup.

That the ConfigurationGuidelines page actually recommends setting 
maximum-requests, without any warning, is clearly misleading.

See http://mercurial.selenic.com/bts/issue2595 for details and issue history.

Original comment by antoine.pitrou on 23 Dec 2011 at 11:13

[GoogleCodeExporter]

In mod_wsgi 4.0 there will be a new graceful-timeout option which can be 
applied on top which gives a slightly more tolerant way of doing a restart 
prior to a forced shutdown. During the graceful timeout option after maximum 
requests is reached, it will still accept new requests but if the process 
becomes idle and have no running requests it will immediately restart. If it 
still reaches end of graceful timeout, then existing forced shutdown timeout 
applies where no new requests will be accepted.

The short of it though is that maximum-requests should never be used in 
production systems unless you have an absolute need to because you haven't been 
able to fix a memory leak in your program. I didn't realise the documentation 
was so strong in saying otherwise.

Note to self. Change wording of:

"""As a general recommendation it would probably be a good idea to use the
maximum requests option when running large installations of packages such
as Trac and !MoinMoin. Any large web site based on frameworks such as
Django, !TurboGears and Pylons or applications which use a database backend
may also benefit."""

in configuration guidelines document.

Original comment by Graham.Dumpleton@gmail.com on 23 Dec 2011 at 9:45

[GoogleCodeExporter]

Closing out documentation issues. Will pick up another time on github side when 
get enough momentum to work on documentation again.

Original comment by Graham.Dumpleton@gmail.com on 12 Nov 2014 at 10:14

• Changed state: WontFix