From bf669af7f10ec81280fd8dbee43e414fa75457c5 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Wed, 21 May 2014 11:03:13 -0500 Subject: clarify tween thread-safety --- docs/narr/hooks.rst | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 91392ce7a..fe7749cac 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -985,7 +985,7 @@ Creating a Tween To create a tween, you must write a "tween factory". A tween factory must be a globally importable callable which accepts two arguments: -``handler`` and ``registry``. ``handler`` will be the either the main +``handler`` and ``registry``. ``handler`` will be either the main Pyramid request handling function or another tween. ``registry`` will be the Pyramid :term:`application registry` represented by this Configurator. A tween factory must return the tween (a callable object) when it is called. @@ -995,6 +995,11 @@ A tween is called with a single argument, ``request``, which is the A tween should return a :term:`response`, usually the one generated by the downstream Pyramid application. +The tween factory will be shared between requests and is used to create one +tween per-request. Shared mutable state on the factory itself needs to be +carefully handled, and should be avoided unless you are willing to handle +the race conditions that may arise. + You can write the tween factory as a simple closure-returning function: .. code-block:: python @@ -1017,8 +1022,7 @@ You can write the tween factory as a simple closure-returning function: return simple_tween Alternatively, the tween factory can be a class with the ``__call__`` magic -method (the instance will be unique, be aware that it will be shared -between threads): +method: .. code-block:: python :linenos: -- cgit v1.2.3