From 6ad47b41a650a13b4a9214309c10239726331eb8 Mon Sep 17 00:00:00 2001 From: Vinay Sajip Date: Tue, 20 Sep 2022 09:40:06 +0100 Subject: gh-96727: Document restrictions on Handler.emit() with respect to locking. (GH-96948) --- Doc/library/logging.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index 8793627..34e98fc 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -534,6 +534,22 @@ subclasses. However, the :meth:`__init__` method in subclasses needs to call is intended to be implemented by subclasses and so raises a :exc:`NotImplementedError`. + .. warning:: This method is called after a handler-level lock is acquired, which + is released after this method returns. When you override this method, note + that you should be careful when calling anything that invokes other parts of + the logging API which might do locking, because that might result in a + deadlock. Specifically: + + * Logging configuration APIs acquire the module-level lock, and then + individual handler-level locks as those handlers are configured. + + * Many logging APIs lock the module-level lock. If such an API is called + from this method, it could cause a deadlock if a configuration call is + made on another thread, because that thread will try to acquire the + module-level lock *before* the handler-level lock, whereas this thread + tries to acquire the module-level lock *after* the handler-level lock + (because in this method, the handler-level lock has already been acquired). + For a list of handlers included as standard, see :mod:`logging.handlers`. .. _formatter-objects: -- cgit v0.12