[Python-checkins] [3.10] gh-96727: Document restrictions on Handler.emit() with respect to locking. (GH-96948) (GH-96951)
vsajip
webhook-mailer at python.org
Tue Sep 20 04:54:36 EDT 2022
https://github.com/python/cpython/commit/7a8ac38b2b7dbe14195d2496b20673d612ab978a
commit: 7a8ac38b2b7dbe14195d2496b20673d612ab978a
branch: 3.10
author: Vinay Sajip <vinay_sajip at yahoo.co.uk>
committer: vsajip <vinay_sajip at yahoo.co.uk>
date: 2022-09-20T09:54:31+01:00
summary:
[3.10] gh-96727: Document restrictions on Handler.emit() with respect to locking. (GH-96948) (GH-96951)
(cherry picked from commit 6ad47b41a650a13b4a9214309c10239726331eb8)
files:
M Doc/library/logging.rst
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index 6e83df8adb5c..13683c0766a3 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -522,6 +522,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:
More information about the Python-checkins
mailing list