Improved mod_wsgi docs. PYTHON-567

doc/examples/index.rst

@@ -23,4 +23,5 @@ MongoDB, you can start it like so:
    gevent
    gridfs
    high_availability
-   requests
+   mod_wsgi
+   requests

doc/examples/mod_wsgi.rst

@@ -0,0 +1,59 @@
+.. _pymongo-and-mod_wsgi:
+
+PyMongo and mod_wsgi
+====================
+
+If you run your application under
+`mod_wsgi <http://code.google.com/p/modwsgi/>`_ and you use PyMongo with its C
+extensions enabled, follow these guidelines for best performance:
+
+* Run ``mod_wsgi`` in daemon mode with the ``WSGIDaemon`` directive.
+* Assign each application to a separate daemon with ``WSGIProcessGroup``.
+* Use ``WSGIApplicationGroup %{GLOBAL}`` to ensure your application is running
+  in the daemon's main Python interpreter, not a sub interpreter.
+
+For example, this ``mod_wsgi`` configuration ensures an application runs in the
+main interpreter::
+
+    <VirtualHost *>
+        WSGIDaemonProcess my_process
+        WSGIScriptAlias /my_app /path/to/app.wsgi
+        WSGIProcessGroup my_process
+        WSGIApplicationGroup %{GLOBAL}
+    </VirtualHost>
+
+If you have multiple applications that use PyMongo, put each in a separate
+daemon, still in the global application group::
+
+    <VirtualHost *>
+        WSGIDaemonProcess my_process
+        WSGIScriptAlias /my_app /path/to/app.wsgi
+        <Location /my_app>
+            WSGIProcessGroup my_process
+        </Location>
+
+        WSGIDaemonProcess my_other_process
+        WSGIScriptAlias /my_other_app /path/to/other_app.wsgi
+        <Location /my_other_app>
+            WSGIProcessGroup my_other_process
+        </Location>
+
+        WSGIApplicationGroup %{GLOBAL}
+    </VirtualHost>
+
+Background: Python C extensions in general have issues running in multiple
+Python sub interpreters. These difficulties are explained in the documentation for
+`Py_NewInterpreter <http://docs.python.org/2/c-api/init.html#Py_NewInterpreter>`_
+and in the `Multiple Python Sub Interpreters
+<https://code.google.com/p/modwsgi/wiki/ApplicationIssues#Multiple_Python_Sub_Interpreters>`_
+section of the ``mod_wsgi`` documentation.
+
+Beginning with PyMongo 2.7, the C extension for BSON detects when it is running
+in a sub interpreter and activates a workaround, which adds a small cost to
+BSON decoding. To avoid this cost, use ``WSGIApplicationGroup %{GLOBAL}`` to
+ensure your application runs in the main interpreter.
+
+Since your program runs in the main interpreter it should not share its
+process with any other applications, lest they interfere with each other's
+state. Each application should have its own daemon process, as shown in the
+example above.

doc/faq.rst

@@ -260,30 +260,7 @@ MongoDB backends for Django sessions and authentication (bypassing
 
 Does PyMongo work with **mod_wsgi**?
 ------------------------------------
-`mod_wsgi <http://code.google.com/p/modwsgi/>`_ is a popular Apache
-module used for hosting Python applications conforming to the `wsgi
-<http://www.wsgi.org/>`_ specification. There is a potential issue
-when deploying PyMongo applications with mod_wsgi involving PyMongo's
-C extension and mod_wsgi's multiple sub interpreters.
-
-One tricky issue that we've seen when deploying PyMongo applications
-with mod_wsgi is documented `here
-<http://code.google.com/p/modwsgi/wiki/ApplicationIssues>`_, in the
-**Multiple Python Sub Interpreters** section. When running PyMongo
-with the C extension enabled it is possible to see strange failures
-when encoding due to the way mod_wsgi handles module reloading with
-multiple sub interpreters. There are several possible ways to work
-around this issue:
-
-1. Run mod_wsgi in daemon mode with each WSGI application assigned to its
-   own daemon process.
-
-2. Force all WSGI applications to run in the same application group.
-
-3. Install PyMongo :ref:`without the C extension <install-no-c>` (this will
-   carry a performance penalty, but is the most immediate solution to this
-   problem).
-
+Yes. See the configuration guide for :ref:`pymongo-and-mod_wsgi`.
 
 How can I use something like Python's :mod:`json` module to encode my documents to JSON?
 ----------------------------------------------------------------------------------------