diff options
author | Jenkins <jenkins@review.openstack.org> | 2014-06-25 14:26:51 +0000 |
---|---|---|
committer | Gerrit Code Review <review@openstack.org> | 2014-06-25 14:26:51 +0000 |
commit | 6c7a8b3ee9658c4bb2a2d72f241720861d1da56f (patch) | |
tree | 2a8b21e558f7b37d84ad4684648b7e7b04529000 /docs | |
parent | 43f2f2599c43a48742f48d826a0ceb9efc852eb5 (diff) | |
parent | e93b929edf9cdbec6711e5672029981cb303fff3 (diff) | |
download | pecan-6c7a8b3ee9658c4bb2a2d72f241720861d1da56f.tar.gz |
Merge "Add support for Pecan *without* thread local request/response objects"
Diffstat (limited to 'docs')
-rw-r--r-- | docs/source/contextlocals.rst | 55 | ||||
-rw-r--r-- | docs/source/index.rst | 1 | ||||
-rw-r--r-- | docs/source/routing.rst | 10 |
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 ac74ba8..be8e987 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): |