[DOC] Added section `Process model` to talk a bit about the recently merged longpolling feature.

bzr revid: vmt@openerp.com-20130219110027-8kld9li7i5g0dtjo

2 files changed, 53 insertions, 9 deletions

diff --git a/doc/02_architecture.rst b/doc/02_architecture.rst
index 815a498d5bd..203a1bceba9 100644
--- a/doc/02_architecture.rst
+++ b/doc/02_architecture.rst
@@ -1,6 +1,6 @@
-========================================
+============
 Architecture
-========================================
+============
 
 OpenERP as a multitenant three-tiers architecture
 =================================================
@@ -180,6 +180,7 @@ OpenERP follows the MVC semantic with
 
 Network communications and WSGI
 ===============================
+
 OpenERP is an HTTP web server and may also be deployed as an WSGI-compliant
 application.
 
@@ -207,3 +208,45 @@ As such, it can be run as a stand-alone HTTP server or embedded inside OpenERP.
 The HTTP namespaces /openerp/ /object/ /common/ are reserved for the XML-RPC
 layer, every module restrict it's HTTP namespace to /<name_of_the_module>/
 
+Process model
+=============
+
+In the past, the OpenERP server was using threads to handle HTTP requests
+concurrently or to process cron jobs. Using threads is still the default
+behavior when running the ``openerp-server`` script but not the recommended
+one: it is in fact recommended to use the ``--workers`` option.
+
+By using the ``--workers`` option, the OpenERP server will spawn a fixed number
+of processes instead of spawning a new thread for each incoming request.
+
+This has a number of advantages:
+
+ - Processes do not suffer from CPython's Global Interpreter Lock.
+ - Processes can be gracefully recycled while requests are still handled by the
+   server.
+ - Resources such as CPU time and memory made available to a process can be
+   monitored on a per-process basis.
+
+When using the ``--workers`` options, two types of processes may be spawned:
+web process, and cron process.
+
+.. versionadded:: 7.1
+
+.. _longpolling-worker:
+
+When using the ``--workers`` options, three types of processes may be spawned:
+web process, and cron process, just as previsouly, but also an evented (using
+gevent) web process is started. It is used for long-polling as needed by the
+upcoming Instant Messaging feature. As for now, that process is listening on a
+different port than the main web processes. A reverse proxy (e.g. Nginx) to
+listen on a unique port, mapping all requests to the normal port, but mapping
+the ``/longpolling`` route to the evented process is necessary (the web
+interface cannot issue requests to different ports).
+
+(It is possible to make the threaded server evented by passing the ``--gevent``
+flag.)
+
+The goal is to drop support for the threaded model, and also make all web
+processes evented; there would be no more distinction between "normal" and
+"longpolling" processes. For this to happen, further testing is needed.
+
diff --git a/doc/changelog.rst b/doc/changelog.rst
index 84a3cdcb12e..a80e8dc6c8d 100644
--- a/doc/changelog.rst
+++ b/doc/changelog.rst
@@ -6,13 +6,14 @@ Changelog
 `trunk`
 -------
 
+- Added the :ref:`Long polling <longpolling-worker>` worker type.
 - Added :ref:`orm-workflows` to the ORM.
 - Added :ref:`routing-decorators` to the RPC and WSGI stack.
-- Removed support for `__terp__.py` descriptor files.
-- Removed support for `<terp>` root element in XML files.
-- Removed support for the non-openerp namespace (e.g. importing `tools` instead
-  of `openerp.tools` in an addons).
+- Removed support for ``__terp__.py`` descriptor files.
+- Removed support for ``<terp>`` root element in XML files.
+- Removed support for the non-openerp namespace (e.g. importing ``tools``
+  instead of ``openerp.tools`` in an addons).
 - Add a new type of exception that allows redirections:
-  openerp.exceptions.RedirectWarning.
-- Give a pair of new methods to res.config.settings and a helper to make them
-  easier to use: get_config_warning()
+  ``openerp.exceptions.RedirectWarning``.
+- Give a pair of new methods to ``res.config.settings`` and a helper to make
+  them easier to use: ``get_config_warning()``.