diff --git a/doc/examples/index.rst b/doc/examples/index.rst index e32f68c27..e18a790f7 100644 --- a/doc/examples/index.rst +++ b/doc/examples/index.rst @@ -23,4 +23,5 @@ MongoDB, you can start it like so: gevent gridfs high_availability - requests + mod_wsgi + requests \ No newline at end of file diff --git a/doc/examples/mod_wsgi.rst b/doc/examples/mod_wsgi.rst new file mode 100644 index 000000000..0549d6653 --- /dev/null +++ b/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 `_ 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:: + + + WSGIDaemonProcess my_process + WSGIScriptAlias /my_app /path/to/app.wsgi + WSGIProcessGroup my_process + WSGIApplicationGroup %{GLOBAL} + + +If you have multiple applications that use PyMongo, put each in a separate +daemon, still in the global application group:: + + + WSGIDaemonProcess my_process + WSGIScriptAlias /my_app /path/to/app.wsgi + + WSGIProcessGroup my_process + + + WSGIDaemonProcess my_other_process + WSGIScriptAlias /my_other_app /path/to/other_app.wsgi + + WSGIProcessGroup my_other_process + + + WSGIApplicationGroup %{GLOBAL} + + +Background: Python C extensions in general have issues running in multiple +Python sub interpreters. These difficulties are explained in the documentation for +`Py_NewInterpreter `_ +and in the `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. \ No newline at end of file diff --git a/doc/faq.rst b/doc/faq.rst index 43defb5f9..10afa8f0c 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -260,30 +260,7 @@ MongoDB backends for Django sessions and authentication (bypassing Does PyMongo work with **mod_wsgi**? ------------------------------------ -`mod_wsgi `_ is a popular Apache -module used for hosting Python applications conforming to the `wsgi -`_ 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 -`_, 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 ` (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? ----------------------------------------------------------------------------------------