From: Neil Schemenauer <nas-github@arctrix.com>
Date: Sat, 1 Aug 2026 10:01:26 +0000 (-0700)
Subject: Add comments about _Py_LOCK_DONT_DETACH usage. (#153817)
X-Git-Url: http://git.ipfire.org/gitweb/?a=commitdiff_plain;h=534b6b062e53f70587840eac9b432442f66c16c6;p=thirdparty%2FPython%2Fcpython.git

Add comments about _Py_LOCK_DONT_DETACH usage. (#153817)
---

diff --git a/Include/internal/pycore_lock.h b/Include/internal/pycore_lock.h
index e31d8b4e5c68..13224a057293 100644
--- a/Include/internal/pycore_lock.h
+++ b/Include/internal/pycore_lock.h
@@ -34,6 +34,11 @@ _PyMutex_at_fork_reinit(PyMutex *m)
 
 typedef enum _PyLockFlags {
     // Do not detach/release the GIL when waiting on the lock.
+    //
+    // Note that code executed while holding a mutex with this flag must
+    // not detach, reach a safepoint or initiate a stop-the-world pause.
+    // Otherwise, a non-detaching waiter may remain waiting for this mutex and
+    // prevent the pause from completing.
     _Py_LOCK_DONT_DETACH = 0,
 
     // Detach/release the GIL while waiting on the lock.
diff --git a/Objects/unicodeobject.c b/Objects/unicodeobject.c
index eec02f662e79..4b4f7178ec9f 100644
--- a/Objects/unicodeobject.c
+++ b/Objects/unicodeobject.c
@@ -14726,6 +14726,15 @@ intern_common(PyInterpreterState *interp, PyObject *s /* stolen */,
     }
 #endif
 
+    // Why _Py_LOCK_DONT_DETACH is used here: waiting for the interned mutex
+    // must not detach the thread state. Extension code is expected to
+    // detach before blocking on opaque external synchronization. However,
+    // the lock used for C++ static initialization is hidden, making
+    // that difficult, and it is common for C++ extensions to call
+    // PyUnicode_InternFromString() from static initializers. Detaching here
+    // can therefore deadlock: a stop-the-world pause may prevent the lock
+    // owner from reattaching while the pause waits for another attached
+    // thread blocked on the hidden lock.
     FT_MUTEX_LOCK_FLAGS(INTERN_MUTEX, _Py_LOCK_DONT_DETACH);
     PyObject *t;
     {