scoped_session adjustments

* fix typo, change to a note the async scoped session note
* more dragons re: threading.local()

Change-Id: I76266507510e4014456d992656f4aadf6d03ba4a
(cherry picked from commit 912bdcc8075c640a4f3d9e0194f57b5bdcfc6f2b)

diff --git a/doc/build/orm/contextual.rst b/doc/build/orm/contextual.rst
index fd55846220a32a130d7914327730aeb757e501ad..58799659fd4874de58753e1a50249ac46601f850 100644 (file)
--- a/doc/build/orm/contextual.rst
+++ b/doc/build/orm/contextual.rst
@@ -19,6 +19,21 @@ The object is the :class:`.scoped_session` object, and it represents a
 registry pattern, a good introduction can be found in `Patterns of Enterprise
 Architecture <http://martinfowler.com/eaaCatalog/registry.html>`_.
 
+.. warning::
+
+    The :class:`.scoped_session` registry by default uses a Python
+    `threading.local() <https://docs.python.org/3/library/threading.html#thread-local-data>`_
+    in order to track :class:`_orm.Session` instances.   **This is not
+    necessarily compatible with all application servers**, particularly those
+    which make use of greenlets or other alternative forms of concurrency
+    control, which may lead to race conditions (e.g. randomly occurring
+    failures) when used in moderate to high concurrency scenarios.
+    Please read :ref:`unitofwork_contextual_threadlocal` and
+    :ref:`session_lifespan` below to more fully understand the implications
+    of using ``threading.local()`` to track :class:`_orm.Session` objects
+    and consider more explicit means of scoping when using application servers
+    which are not based on traditional threads.
+
 .. note::
 
    The :class:`.scoped_session` object is a very popular and useful object
@@ -103,6 +118,8 @@ underlying :class:`.Session` being maintained by the registry::
 The above code accomplishes the same task as that of acquiring the current
 :class:`.Session` by calling upon the registry, then using that :class:`.Session`.
 
+.. _unitofwork_contextual_threadlocal:
+
 Thread-Local Scope
 ------------------