From: Mike Bayer Date: Tue, 30 Nov 2021 14:06:29 +0000 (-0500) Subject: scoped_session adjustments X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=57f324deaf261400d67b07eda114ebc744d47763;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git 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 fd55846220..58799659fd 100644 --- 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 `_. +.. warning:: + + The :class:`.scoped_session` registry by default uses a Python + `threading.local() `_ + 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 ------------------