From fe1db59480e9b7e3b393a8a3159c8d8925105a5b Mon Sep 17 00:00:00 2001 From: Robsdedude Date: Thu, 12 Feb 2026 11:35:24 +0100 Subject: [PATCH 1/6] Docs: note about combining RLock and signal handlers --- Doc/library/threading.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst index 19cc4f191dff8d..890d2eca957e17 100644 --- a/Doc/library/threading.rst +++ b/Doc/library/threading.rst @@ -840,6 +840,12 @@ the lock to an unlocked state and allows another thread blocked in must have a release in the thread that has acquired the lock. Failing to call release as many times the lock has been acquired can lead to deadlock. +.. tip:: + + Because lock acquisition can be interrupted by signals, sharing reentrant + locks between :mod:`signal` handlers and the main thread can lead to + surprising behavior. Therefore, this is generally not recommended. + .. class:: RLock() From 57ce53f79d7b5b676d910a4b4b7dbfb1417bae0a Mon Sep 17 00:00:00 2001 From: Robsdedude Date: Thu, 12 Feb 2026 13:35:54 +0100 Subject: [PATCH 2/6] Review feedback --- Doc/library/threading.rst | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst index 890d2eca957e17..73da347544ed2f 100644 --- a/Doc/library/threading.rst +++ b/Doc/library/threading.rst @@ -13,6 +13,14 @@ level :mod:`_thread` module. .. include:: ../includes/wasm-notavail.rst +.. warning:: + + Syncrhonization primitives must not be shared between between :mod:`signal` + handlers and the main thread. + Because blocking syncrhonizations calls can be interrupted by signals, + such sharing can lead to surprising dead locks. + + Introduction ------------ @@ -840,12 +848,6 @@ the lock to an unlocked state and allows another thread blocked in must have a release in the thread that has acquired the lock. Failing to call release as many times the lock has been acquired can lead to deadlock. -.. tip:: - - Because lock acquisition can be interrupted by signals, sharing reentrant - locks between :mod:`signal` handlers and the main thread can lead to - surprising behavior. Therefore, this is generally not recommended. - .. class:: RLock() From 21cc73559815ae63e97d11b0c6378df489c62301 Mon Sep 17 00:00:00 2001 From: Robsdedude Date: Thu, 12 Feb 2026 13:44:56 +0100 Subject: [PATCH 3/6] Move warning to signal module and rephrase --- Doc/library/signal.rst | 7 +++++++ Doc/library/threading.rst | 8 -------- 2 files changed, 7 insertions(+), 8 deletions(-) diff --git a/Doc/library/signal.rst b/Doc/library/signal.rst index d85d7138911016..71766343feb874 100644 --- a/Doc/library/signal.rst +++ b/Doc/library/signal.rst @@ -68,6 +68,13 @@ the synchronization primitives from the :mod:`threading` module instead. Besides, only the main thread of the main interpreter is allowed to set a new signal handler. +.. warning:: + + Synchronization primitives such as :class:`threading.Lock` must not be shared + between between signal handlers and other threads. + Because blocking synchronization calls can be interrupted by signals, + such sharing can lead to surprising dead locks. + Module contents --------------- diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst index 73da347544ed2f..19cc4f191dff8d 100644 --- a/Doc/library/threading.rst +++ b/Doc/library/threading.rst @@ -13,14 +13,6 @@ level :mod:`_thread` module. .. include:: ../includes/wasm-notavail.rst -.. warning:: - - Syncrhonization primitives must not be shared between between :mod:`signal` - handlers and the main thread. - Because blocking syncrhonizations calls can be interrupted by signals, - such sharing can lead to surprising dead locks. - - Introduction ------------ From 3684c032a77c8e11009556fb3885dd6e4d53b180 Mon Sep 17 00:00:00 2001 From: Robsdedude Date: Thu, 12 Feb 2026 13:53:43 +0100 Subject: [PATCH 4/6] Fix typo --- Doc/library/signal.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/signal.rst b/Doc/library/signal.rst index 71766343feb874..4165405615f1c6 100644 --- a/Doc/library/signal.rst +++ b/Doc/library/signal.rst @@ -71,7 +71,7 @@ Besides, only the main thread of the main interpreter is allowed to set a new si .. warning:: Synchronization primitives such as :class:`threading.Lock` must not be shared - between between signal handlers and other threads. + between signal handlers and other threads. Because blocking synchronization calls can be interrupted by signals, such sharing can lead to surprising dead locks. From e318c3055e59f6b20ce5881efbb017ff270a8fd3 Mon Sep 17 00:00:00 2001 From: Robsdedude Date: Thu, 12 Feb 2026 13:56:17 +0100 Subject: [PATCH 5/6] Wording --- Doc/library/signal.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/Doc/library/signal.rst b/Doc/library/signal.rst index 4165405615f1c6..8ae56683263f9c 100644 --- a/Doc/library/signal.rst +++ b/Doc/library/signal.rst @@ -70,10 +70,9 @@ Besides, only the main thread of the main interpreter is allowed to set a new si .. warning:: - Synchronization primitives such as :class:`threading.Lock` must not be shared - between signal handlers and other threads. - Because blocking synchronization calls can be interrupted by signals, - such sharing can lead to surprising dead locks. + Synchronization primitives such as :class:`threading.Lock` should not be used + within signal handlers. Because blocking synchronization calls can be + interrupted by signals, such usage can lead to surprising dead locks. Module contents From 052972ad6213168a0efedc705f5b7dc19fd86153 Mon Sep 17 00:00:00 2001 From: Robsdedude Date: Thu, 12 Feb 2026 18:48:11 +0100 Subject: [PATCH 6/6] Review feedback --- Doc/library/signal.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/library/signal.rst b/Doc/library/signal.rst index 8ae56683263f9c..c3fe9943ba9d76 100644 --- a/Doc/library/signal.rst +++ b/Doc/library/signal.rst @@ -71,8 +71,7 @@ Besides, only the main thread of the main interpreter is allowed to set a new si .. warning:: Synchronization primitives such as :class:`threading.Lock` should not be used - within signal handlers. Because blocking synchronization calls can be - interrupted by signals, such usage can lead to surprising dead locks. + within signal handlers. Doing so can lead to unexpected deadlocks. Module contents