Skip to content

Commit 6ad47b4

Browse files
authored
gh-96727: Document restrictions on Handler.emit() with respect to locking. (GH-96948)
1 parent 34de67c commit 6ad47b4

File tree

1 file changed

+16
-0
lines changed

1 file changed

+16
-0
lines changed

Doc/library/logging.rst

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -534,6 +534,22 @@ subclasses. However, the :meth:`__init__` method in subclasses needs to call
534534
is intended to be implemented by subclasses and so raises a
535535
:exc:`NotImplementedError`.
536536

537+
.. warning:: This method is called after a handler-level lock is acquired, which
538+
is released after this method returns. When you override this method, note
539+
that you should be careful when calling anything that invokes other parts of
540+
the logging API which might do locking, because that might result in a
541+
deadlock. Specifically:
542+
543+
* Logging configuration APIs acquire the module-level lock, and then
544+
individual handler-level locks as those handlers are configured.
545+
546+
* Many logging APIs lock the module-level lock. If such an API is called
547+
from this method, it could cause a deadlock if a configuration call is
548+
made on another thread, because that thread will try to acquire the
549+
module-level lock *before* the handler-level lock, whereas this thread
550+
tries to acquire the module-level lock *after* the handler-level lock
551+
(because in this method, the handler-level lock has already been acquired).
552+
537553
For a list of handlers included as standard, see :mod:`logging.handlers`.
538554

539555
.. _formatter-objects:

0 commit comments

Comments
 (0)