Merge branch 'release/4.6.0'

Author: GrahamDumpleton

README.rst

@@ -12,7 +12,7 @@ The first way of installing mod_wsgi is the traditional way that has been
 used by many software packages. This is where it is installed as a module
 directly into your Apache installation using the commands ``configure``,
 ``make`` and ``make install``, a method sometimes referred to by the
-acyronym CMMI. This method works with most UNIX type systems. It cannot
+acronym CMMI. This method works with most UNIX type systems. It cannot
 be used on Windows.
 
 The second way of installing mod_wsgi is to install it as a Python package
@@ -49,7 +49,7 @@ they never fixed those problems either. This time there is no easy
 workaround as they no longer supply certain tools which are required to
 perform the installation.
 
-The ``pip install`` method along with manual configuration of Apache
+The ``pip install`` method along with the manual configuration of Apache
 is also the method you need to use on Windows.
 
 System Requirements
@@ -59,7 +59,7 @@ With either installation method for mod_wsgi, you must have Apache
 installed. This must be a complete Apache installation. It is not enough to
 have only the runtime packages for Apache installed. You must have the
 corresponding development package for Apache installed, which contains the
-Apache header files, as these are required to be able compile and install
+Apache header files, as these are required to be able to compile and install
 third party Apache modules.
 
 Similarly with Python, you must have a complete Python installation which
@@ -156,7 +156,7 @@ Note that nothing will be copied into your Apache installation at this
 point. As a result, you do not need to run this as the root user unless
 installing it into a site wide Python installation rather than a Python
 virtual environment. It is recommended you always use Python virtual
-environments and never install any Python package direct into the system
+environments and never install any Python package directly into the system
 Python installation.
 
 On a UNIX type system, to verify that the installation was successful, run
@@ -233,7 +233,7 @@ additional steps.
 
 The first thing you must do is supply the ``--user`` and ``--group``
 options to say what user and group your Python web application should run
-as. Most Linux distributions will pre define a special user for Apache to
+as. Most Linux distributions will predefine a special user for Apache to
 run as, so you can use that. Alternatively you can use any other special
 user account you have created for running the Python web application::
 
@@ -344,7 +344,7 @@ use the ``--setup-only`` option to the ``runmodwsgi`` management command.
         --user www-data --group www-data \
         --server-root=/etc/mod_wsgi-express-80
  
-This will setup all the required files and you can use ``apachectl`` to
+This will set up all the required files and you can use ``apachectl`` to
 start and stop the Apache instance as explained previously.
 
 Connecting into Apache installation

configure.ac

@@ -1,6 +1,6 @@
 dnl  vim: set sw=4 expandtab :
 dnl
-dnl  Copyright 2007-2017 GRAHAM DUMPLETON
+dnl  Copyright 2007-2018 GRAHAM DUMPLETON
 dnl 
 dnl  Licensed under the Apache License, Version 2.0 (the "License");
 dnl  you may not use this file except in compliance with the License.

docs/conf.py

@@ -41,7 +41,7 @@
 
 # General information about the project.
 project = u'mod_wsgi'
-copyright = u'2007-2017, Graham Dumpleton'
+copyright = u'2007-2018, Graham Dumpleton'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

docs/configuration-directives/WSGIApplicationGroup.rst

@@ -17,6 +17,17 @@ to. All WSGI applications within the same application group will execute
 within the context of the same Python sub interpreter of the process
 handling the request.
 
+Setting ``WSGIApplicationGroup`` doesn't control what processes a request
+is handled by, that is what the ``WSGIProcessGroup`` directive does. In
+other words, the ``WSGIProcessGroup`` directive operates distinct from the
+``WSGIApplicationGroup`` directive, with ``WSGIProcessGroup`` dictating
+what named group of processes a request is handled by, and
+``WSGIApplicationGroup`` dictating which named Python sub interpreter
+context (application group) of those processes is used. In each distinct
+process of a named group of processes, there will be a separate sub
+interpreter instance of same name, for handling the requests accepted by
+that process.
+
 The argument to the ``WSGIApplicationGroup`` can be either one of four
 special expanding variables or an explicit name of your own choosing.
 The meaning of the special variables are:
@@ -27,11 +38,12 @@ The meaning of the special variables are:
 
     Any WSGI applications in the global application group will always be
     executed within the context of the first interpreter created by Python
-    when it is initialised. Forcing a WSGI application to run within the
-    first interpreter can be necessary when a third party C extension
-    module for Python has used the simplified threading API for
-    manipulation of the Python GIL and thus will not run correctly within
-    any additional sub interpreters created by Python.
+    when it is initialised, of the process handling the request. Forcing a
+    WSGI application to run within the first interpreter can be necessary
+    when a third party C extension module for Python has used the
+    simplified threading API for manipulation of the Python GIL and thus
+    will not run correctly within any additional sub interpreters created
+    by Python.
 
 **%{SERVER}**
 

docs/configuration-directives/WSGIDaemonProcess.rst

@@ -59,6 +59,20 @@ Options which can be supplied to the ``WSGIDaemonProcess`` directive are:
     where your code is I/O bound. If you code is CPU bound, you are better
     of using at most 3 to 5 threads per process and using more processes.
 
+    If you set the number of threads to 0 you will enable a special mode
+    intended for using a daemon process to run a managed set of processes.
+    You will need to use ``WSGIImportScript`` to pre-load a Python script
+    into the main application group specified by ``%{GLOBAL}`` where the
+    script runs a never ending task, or does an exec to run an external
+    program. If the script or external program exits, the process is
+    shutdown and replaced with a new one. For the case of using a Python
+    script to run a never ending task, a ``SystemExit`` exception will be
+    injected when a signal is received to shutdown the process. You can
+    use ``signal.signal()`` to register a signal handler for ``SIGTERM``
+    if needing to run special actions before then exiting the process using
+    ``sys.exit()``, or to signal your own threads to exit any processing
+    so you can shutdown in an orderly manner.
+
 **display-name=value**
     Defines a different name to show for the daemon process when using the
     ``ps`` command to list processes. If the value is ``%{GROUP}`` then the
@@ -598,6 +612,37 @@ host, the following could be used::
   ...
   </VirtualHost>
 
+For historical reasons and the inability to change existing behaviour when
+adding or changing features, many of the options to ``WSGIDaemonProcess``,
+especially those related to timeouts are not enabled by default. It is
+strongly recommended you explicitly set these options yourself as this will
+give you a system which is better able to recover from backlogging due to
+overloading when you have too many long running requests or hanging
+requests. As a starting point you can see what ``mod_wsgi-express`` uses as
+defaults, adjusting them as necessary to suit your specific application
+after you research what each option does. For example, consider starting
+out with:
+
+* ``display-name='%{GROUP}'``
+
+* ``lang='en_US.UTF-8'``
+* ``locale='en_US.UTF-8'``
+
+* ``threads=5``
+
+* ``queue-timeout=45``
+* ``socket-timeout=60``
+* ``connect-timeout=15``
+* ``request-timeout=60``
+* ``inactivity-timeout=0``
+* ``startup-timeout=15``
+* ``deadlock-timeout=60``
+* ``graceful-timeout=15``
+* ``eviction-timeout=0``
+* ``restart-interval=0``
+* ``shutdown-timeout=5``
+* ``maximum-requests=0``
+
 Note that the ``WSGIDaemonProcess`` directive and corresponding features are
 not available on Windows.
 

docs/configuration-directives/WSGIScriptAlias.rst

@@ -86,12 +86,12 @@ Options which can be supplied to the ``WSGIScriptAlias`` directive are:
     If the name is set to be ``%{GLOBAL}`` the application group will be
     set to the empty string. Any WSGI applications in the global
     application group will always be executed within the context of the
-    first interpreter created by Python when it is initialised. Forcing
-    a WSGI application to run within the first interpreter can be
-    necessary when a third party C extension module for Python has used
-    the simplified threading API for manipulation of the Python GIL and
-    thus will not run correctly within any additional sub interpreters
-    created by Python.
+    first interpreter created by Python when it is initialised, of the
+    process handling the request. Forcing a WSGI application to run within
+    the first interpreter can be necessary when a third party C extension
+    module for Python has used the simplified threading API for
+    manipulation of the Python GIL and thus will not run correctly within
+    any additional sub interpreters created by Python.
 
 If both ``process-group`` and ``application-group`` options are set, the
 WSGI script file will be pre-loaded when the process it is to run in is

docs/configuration-directives/WSGIScriptAliasMatch.rst

@@ -59,13 +59,15 @@ Options which can be supplied to the ``WSGIScriptAlias`` directive are:
     If the name is set to be ``%{GLOBAL}`` the application group will be
     set to the empty string. Any WSGI applications in the global
     application group will always be executed within the context of the
-    first interpreter created by Python when it is initialised. Forcing
-    a WSGI application to run within the first interpreter can be
-    necessary when a third party C extension module for Python has used
-    the simplified threading API for manipulation of the Python GIL and
-    thus will not run correctly within any additional sub interpreters
-    created by Python.
+    first interpreter created by Python when it is initialised, of the
+    process handling the request. Forcing a WSGI application to run within
+    the first interpreter can be necessary when a third party C extension
+    module for Python has used the simplified threading API for
+    manipulation of the Python GIL and thus will not run correctly within
+    any additional sub interpreters created by Python.
 
-If both ``process-group`` and ``application-group`` options are set, the
-WSGI script file will be pre-loaded when the process it is to run in is
-started, rather than being lazily loaded on the first request.
+If both ``process-group`` and ``application-group`` options are set, and
+the WSGI script file doesn't include substiutions values to be supplied
+from the matched URL pattern, the WSGI script file will be pre-loaded when
+the process it is to run in is started, rather than being lazily loaded on
+the first request.

docs/release-notes.rst

@@ -5,6 +5,8 @@ Release Notes
 .. toctree::
    :maxdepth: 2
 
+   release-notes/version-4.6.0
+
    release-notes/version-4.5.24
    release-notes/version-4.5.23
    release-notes/version-4.5.22