clarify tween thread-safety

1 files 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: