Merge branch 'pull.1349'

1 files changed, 6 insertions, 1 deletions

diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index 94be31bbc..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