Add support for Pecan *without* thread local request/response objects

Change-Id: I5a5a05e1f57ef2d8ad64e925c7ffa6907b914273

3 files changed, 61 insertions, 5 deletions

diff --git a/docs/source/contextlocals.rst b/docs/source/contextlocals.rst
new file mode 100644
index 0000000..d97ef7e
--- /dev/null
+++ b/docs/source/contextlocals.rst
@@ -0,0 +1,55 @@
+.. _contextlocals:
+
+
+Context/Thread-Locals vs. Explicit Argument Passing
+===================================================
+In any pecan application, the module-level ``pecan.request`` and
+``pecan.response`` are proxy objects that always refer to the request and
+response being handled in the current thread.
+
+This `thread locality` ensures that you can safely access a global reference to
+the current request and response in a multi-threaded environment without
+constantly having to pass object references around in your code; it's a feature
+of pecan that makes writing traditional web applications easier and less
+verbose.
+
+Some people feel thread-locals are too implicit or magical, and that explicit
+reference passing is much clearer and more maintainable in the long run.
+Additionally, the default implementation provided by pecan uses
+:func:`threading.local` to associate these context-local proxy objects with the
+`thread identifier` of the current server thread.  In asynchronous server
+models - where lots of tasks run for short amounts of time on
+a `single` shared thread - supporting this mechanism involves monkeypatching
+:func:`threading.local` to behave in a greenlet-local manner.
+
+Disabling Thread-Local Proxies
+------------------------------
+
+If you're certain that you `do not` want to utilize context/thread-locals in
+your project, you can do so by passing the argument
+``use_context_locals=False`` in your application's configuration file::
+
+    app = {
+        'root': 'project.controllers.root.RootController',
+        'modules': ['project'],
+        'static_root': '%(confdir)s/public',
+        'template_path': '%(confdir)s/project/templates',
+        'debug': True,
+        'use_context_locals': False
+    }
+
+Additionally, you'll need to update **all** of your pecan controllers to accept
+positional arguments for the current request and response::
+
+    class RootController(object):
+
+        @pecan.expose('json')
+        def index(self, req, resp):
+            return dict(method=req.method) # path: /
+
+        @pecan.expose()
+        def greet(self, req, resp, name):
+            return name  # path: /greet/joe
+
+It is *imperative* that the request and response arguments come **after**
+``self`` and before any positional form arguments.
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 8a4ef37..520d0f7 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -38,6 +38,7 @@ Narrative Documentation
    secure_controller.rst
    hooks.rst
    jsonify.rst
+   contextlocals.rst
    commands.rst
    development.rst
    deployment.rst
diff --git a/docs/source/routing.rst b/docs/source/routing.rst
index ec79305..28df5d6 100644
--- a/docs/source/routing.rst
+++ b/docs/source/routing.rst
@@ -270,11 +270,11 @@ a :func:`_route` method will enable you to have total control.
 Interacting with the Request and Response Object
 ------------------------------------------------
 
-For every HTTP request, Pecan maintains a thread-local reference to the request
-and response object, ``pecan.request`` and ``pecan.response``.  These are
-instances of :class:`webob.request.BaseRequest` and
-:class:`webob.response.Response`, respectively, and can be interacted with from
-within Pecan controller code::
+For every HTTP request, Pecan maintains a :ref:`thread-local reference
+<contextlocals>` to the request and response object, ``pecan.request`` and
+``pecan.response``.  These are instances of :class:`webob.request.BaseRequest`
+and :class:`webob.response.Response`, respectively, and can be interacted with
+from within Pecan controller code::
 
     @pecan.expose()
     def login(self):