_thread module docs: update yet another bullet point in the *caveats* list

[zuo]

Documentation

[Note: This issue is, in a way, a continuation of gh-125025.]

Near the end of the documentation of the _thread module there is a list of caveats. One of them – the third one – seems no longer accurate:

It is not possible to interrupt the acquire() method on a lock — the KeyboardInterrupt exception will happen after the lock has been acquired.

– whereas it appears that (since Python 3.2) lock acquisitions can be interrupted by signals, at least on platforms using Pthreads.

Linked PRs

• gh-125058: update _thread docs regarding interruptibility of lock.acquire() #125141
• [3.13] gh-125058: update _thread docs regarding interruptibility of lock.acquire() (GH-125141) #125306
• [3.12] gh-125058: update _thread docs regarding interruptibility of lock.acquire() (GH-125141) #125307

[zuo]

The question is whether nowadays the possibility to interrupt a blocking acquisition of a lock is possible only on POSIX systems (I can observe that on my Linux system), or maybe also on others? (i.e., Windows?)

Unfortunately I am not sure what is the right answer, therefore a Python threading expert needs to speak up.

According to the Experts Index the right persons are you, @gpshead and @pitrou. I hope, this is the right way to ask you for help?

Thank you in advance! :)

[zuo]

PS I'd happy to provide a PR with an appropriate docs patch – when I'm sure what is the state of affairs when it comes the possibility to interrupt a lock acquisition on platforms with a non-Pthreads-based threads implementation.

[gpshead]

Yes POSIXish platforms should happily allow interrupting threading.Lock.acquire() with ^C at this point. @zooba or @eryksun wear Windows hats and can answer for that platform.

[zooba]

Looks like Windows is using EnterNonRecursiveMutex() for this, which is not going to be interruptible (based on a quick look - trust Eryk's opinion over mine here).

In order to be interruptible, it needs to be a WaitForMultipleObjects including the _PyOS_SigintEvent handle. I don't think it's trivial to convert, at least not without a performance loss, and likely with subtle behaviour changes from what it currently does.

[zuo]

@gpshead @zooba Thank you for your feedback! I presume that something along the lines of the following would be appropriate:

It is platform-dependent whether the acquire() method on a lock can be interrupted (so that the KeyboardInterrupt exception will happen immediately, rather than only after the lock has been acquired or the operation has timed out).

[zuo]

PS Perhaps adding that

It can on POSIX platforms.

[pitrou]

In order to be interruptible, it needs to be a WaitForMultipleObjects including the _PyOS_SigintEvent handle.

I think this used to be the case, but it got replaced by the faster native mutex for performance.

[colesbury]

@kumaraditya303 has a PR to use PyMutex for _thread.lock, which blocks using an alertable (interruptible?) WaitForSingleObjectEx call:

• gh-117721: use PyMutex in _thread.lock #125110

[colesbury]

My previous comment was incorrect. PyMutex calls WaitForSingleObjectEx with bAlertable=FALSE:

cpython/Python/parking_lot.c

Line 114 in e99f159

wait = WaitForSingleObjectEx(sema->platform_sem, millis, FALSE);

[zuo]

OK, so it remains platform-dependent whether acquire() is interruptible, doesn't it?

[pitrou]

Yes. But concretely, it's interruptible on POSIX, not on Windows.

[pitrou]

My previous comment was incorrect. PyMutex calls WaitForSingleObjectEx with bAlertable=FALSE:

Regardless, it seems the bAlertable flag has nothing to do with being interruptible with Ctrl-C:
https://learn.microsoft.com/en-us/windows/win32/api/synchapi/nf-synchapi-waitforsingleobjectex

If this parameter is TRUE and the thread is in the waiting state, the function returns when the system queues an I/O completion routine or APC, and the thread runs the routine or function. Otherwise, the function does not return, and the completion routine or APC function is not executed.

[zuo]

PR is ready :)