diff --git a/docs/images/providers/providers_class_diagram.png b/docs/images/providers/providers_class_diagram.png index d932ad83..c4a0cb72 100644 Binary files a/docs/images/providers/providers_class_diagram.png and b/docs/images/providers/providers_class_diagram.png differ diff --git a/docs/main/changelog.rst b/docs/main/changelog.rst index 1f9686de..b16ad369 100644 --- a/docs/main/changelog.rst +++ b/docs/main/changelog.rst @@ -9,7 +9,8 @@ follows `Semantic versioning`_ Development version ------------------- -- No features. +- Add ``ThreadLocalSingleton`` and ``DelegatedThreadLocalSingleton`` providers. +- Add documentation section about singleton providers and multi-threading. 2.0.0 ------ diff --git a/docs/providers/singleton.rst b/docs/providers/singleton.rst index 292ec093..6e0a88a6 100644 --- a/docs/providers/singleton.rst +++ b/docs/providers/singleton.rst @@ -77,3 +77,22 @@ declaring its subclasses. Specialization of :py:class:`Singleton` providers is the same as :py:class:`Factory` providers specialization, please follow :ref:`factory_providers_specialization` section for examples. + +Singleton providers and multi-threading +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:py:class:`Singleton` provider is thread-safe and could be used in +multi-threading applications without any negative impact. Race condition on +singleton's initialization is escaped by using a global reentrant mutex - +:py:obj:`dependency_injector.utils.GLOBAL_LOCK`. + +Also there could be a need to use thread-scoped singletons and there is a +special provider for such case - :py:class:`ThreadLocalSingleton`. +:py:class:`ThreadLocalSingleton` provider creates instance once for each +thread and returns it on every call. + +Example: + +.. literalinclude:: ../../examples/providers/singleton_thread_locals.py + :language: python + :linenos: