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

[robsdedude]

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/

[xBZZZZ]

surprising behavior

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

[ZeroIntensity]

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

[ZeroIntensity]

1. This isn't limited to re-entrant locks.
2. "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.

[robsdedude]

1. You are right, I shall fix.
2. 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.

[xBZZZZ]

This isn't limited to re-entrant locks.

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

[ZeroIntensity]

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:

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

[robsdedude]

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.

[ZeroIntensity]

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.

[robsdedude]

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?"

[ZeroIntensity]

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.

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[ZeroIntensity]

Thanks, LGTM.

[miss-islington-app]

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

[bedevere-app]

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

[bedevere-app]

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