From d194f3df5b5941251a36e0e7d535eaf0d633dd1b Mon Sep 17 00:00:00 2001 From: flibustenet Date: Sun, 18 May 2014 11:26:48 +0200 Subject: Draw attention that tweens instances are unique and shared between threads Forgetting that tween instance are not instantiated for each request leads to threads issues difficult to detect --- docs/narr/hooks.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 94be31bbc..91392ce7a 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -1017,7 +1017,8 @@ 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: +method (the instance will be unique, be aware that it will be shared +between threads): .. code-block:: python :linenos: -- cgit v1.2.3 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(-) (limited to 'docs') 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