gh-144706: docs note about combining RLock and signal handlers by robsdedude · Pull Request #144736 · python/cpython · GitHub

Document potentially surprising interplay or threading.RLock and signal as discussed in #144706 (comment).

Issue: recussiveness of _thread.RLock doesn't work if lock acquired inside signal handler inside lock.acquire #144706

📚 Documentation preview 📚: https://cpython-previews--144736.org.readthedocs.build/

surprising behavior

any other surprise that is not main thread waiting forever for itself to release RLock?

I think the note should go at the top of the file as a general warning about concurrency and signal handlers.

This isn't limited to re-entrant locks.
"generally not recommended" is not strong enough -- I can't think of a case where it's thread-safe to use locks in signal handlers.

You are right, I shall fix.
sharing a synchronization primitive between the signal handler and some thread other than the main thread should work just fine, shouldn't it? Anyway, with regards to the main thread only, I can't think of a case either.

This isn't limited to re-entrant locks.

what is surprising about normal locks (like returned by _thread.allocate_lock())?

sharing a synchronization primitive between the signal handler and some thread other than the main thread should work just fine, shouldn't it?

I think you're missing the point. It might work right now, but using locks in signal handlers is not something we want to encourage or claim to support. We may want to change how we handle signals or what they affect someday.

what is surprising about normal locks (like returned by _thread.allocate_lock())?

By acquiring a lock in a signal handler, the lock is subject to deadlocks for any signal handled by the main thread. For example:

Main thread acquires a lock.
User sends signal.
The signal handler is invoked, which tries to acquire that lock.
Deadlock!

I think you're missing the point. It might work right now, but using locks in signal handlers is not something we want to encourage or claim to support. We may want to change how we handle signals or what they affect someday.

Alright. In such case, I think this warning belongs into the signal module instead.

I don't think we need to be specific:

Suggested change

      
               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.
          
               Synchronization primitives such as :class:`threading.Lock` should not be used
          
               within signal handlers.  Doing so can lead to deadlocks.

Thanks for the suggestion. I think if I were to read this for the first time I wouldn't understand the issue. And understanding something makes it easier to remember, too. I'd probably be thinking something like "well yeah, using synchronization primitives in general can lead to deadlocks. So what's different here?"

Let's say "unexpected deadlocks" then. The situation in the issue is one of many problems that come up when using synchronization primitives in signal handlers, so it's misleading to say that interruptibility is the only concern.

All commit authors signed the Contributor License Agreement.

Thanks, LGTM.

Thanks @robsdedude for the PR, and @ZeroIntensity for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

… signal handlers (pythonGH-144736) (cherry picked from commit 945bf8c) Co-authored-by: Robsdedude <dev@rouvenbauer.de>

GH-144767 is a backport of this pull request to the 3.14 branch.

GH-144768 is a backport of this pull request to the 3.13 branch.

…n signal handlers (GH-144736) (GH-144767) gh-144706: Warn against using synchronization primitives within signal handlers (GH-144736) (cherry picked from commit 945bf8c) Co-authored-by: Robsdedude <dev@rouvenbauer.de>

…n signal handlers (GH-144736) (GH-144768) gh-144706: Warn against using synchronization primitives within signal handlers (GH-144736) (cherry picked from commit 945bf8c) Co-authored-by: Robsdedude <dev@rouvenbauer.de>

… signal handlers (pythonGH-144736)

Docs: note about combining RLock and signal handlers

fe1db59

bedevere-app Bot added docs Documentation in the Doc dir skip news labels Feb 12, 2026

bedevere-app Bot mentioned this pull request Feb 12, 2026

recussiveness of _thread.RLock doesn't work if lock acquired inside signal handler inside lock.acquire #144706

Closed

github-project-automation Bot added this to Docs PRs Feb 12, 2026

github-project-automation Bot moved this to Todo in Docs PRs Feb 12, 2026

robsdedude marked this pull request as ready for review February 12, 2026 10:48

bedevere-app Bot added the awaiting review label Feb 12, 2026

ZeroIntensity self-requested a review February 12, 2026 12:16

xBZZZZ reviewed Feb 12, 2026

View reviewed changes

ZeroIntensity reviewed Feb 12, 2026

View reviewed changes

robsdedude added 4 commits February 12, 2026 13:35

Review feedback

57ce53f

Move warning to signal module and rephrase

21cc735

Fix typo

3684c03

Wording

e318c30

robsdedude requested a review from ZeroIntensity February 12, 2026 13:03

ZeroIntensity reviewed Feb 12, 2026

View reviewed changes

Review feedback

052972a

robsdedude requested a review from ZeroIntensity February 12, 2026 18:00

ZeroIntensity approved these changes Feb 12, 2026

View reviewed changes

bedevere-app Bot added awaiting merge and removed awaiting review labels Feb 12, 2026

ZeroIntensity added needs backport to 3.13 only security fixes needs backport to 3.14 bugs and security fixes labels Feb 12, 2026

ZeroIntensity merged commit 945bf8c into python:main Feb 12, 2026
37 checks passed

github-project-automation Bot moved this from Todo to Done in Docs PRs Feb 12, 2026

bedevere-app Bot removed the awaiting merge label Feb 12, 2026

bedevere-app Bot removed the needs backport to 3.14 bugs and security fixes label Feb 12, 2026

bedevere-app Bot removed the needs backport to 3.13 only security fixes label Feb 12, 2026

robsdedude deleted the docs/rlock-signal-note branch February 12, 2026 23:30

thunder-coding pushed a commit to thunder-coding/cpython that referenced this pull request Feb 15, 2026

pythongh-144706 : Warn against using synchronization primitives within…

07c3145

… signal handlers (pythonGH-144736)

brijkapadia pushed a commit to brijkapadia/cpython that referenced this pull request Feb 28, 2026

pythongh-144706 : Warn against using synchronization primitives within…

13d9e3c

… signal handlers (pythonGH-144736)

ljfp pushed a commit to ljfp/cpython that referenced this pull request Apr 25, 2026

pythongh-144706 : Warn against using synchronization primitives within…

1c70a5b

… signal handlers (pythonGH-144736)

+                 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.

gh-144706: docs note about combining RLock and signal handlers by robsdedude · Pull Request #144736 · python/cpython · GitHub

Repository navigation

gh-144706: docs note about combining RLock and signal handlers - #144736

gh-144706: docs note about combining RLock and signal handlers#144736ZeroIntensity merged 6 commits intopython:mainpython/cpython:mainfrom robsdedude:docs/rlock-signal-noterobsdedude/cpython:docs/rlock-signal-noteCopy head branch name to clipboard

Conversation

robsdedude commented Feb 12, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ZeroIntensity left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

robsdedude Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

python-cla-bot Bot commented Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ZeroIntensity left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

miss-islington-app Bot commented Feb 12, 2026

Uh oh!

bedevere-app Bot commented Feb 12, 2026

Uh oh!

bedevere-app Bot commented Feb 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

gh-144706: docs note about combining RLock and signal handlers#144736
ZeroIntensity merged 6 commits into
python:mainfrom
robsdedude:docs/rlock-signal-note

robsdedude commented Feb 12, 2026 •
edited by github-actions Bot
Loading

robsdedude Feb 12, 2026 •
edited
Loading

python-cla-bot Bot commented Feb 12, 2026 •
edited
Loading