Expose `PyMutex_IsLocked` in the public C API

[hawkinsp]

Feature or enhancement

Proposal:

In my C extension, I wanted to write:

assert(PyMutex_IsLocked(&mutex));

to verify that my own code is maintaining its own locking invariants.

PyMutex_IsLocked exists, but is private:

cpython/Include/internal/pycore_lock.h

Line 30 in 0afbd4e

PyMutex_IsLocked(PyMutex *m)

Could we make it public and document it, please?

Has this already been discussed elsewhere?

This is a minor feature, which does not need previous discussion elsewhere

Links to previous discussion of this feature:

No response

Linked PRs

• gh-134009: Expose PyMutex_IsLocked in the public C API #134365

[ngoldbaum]

I ran into this when I was writing PyMutex bindings for PyO3 - it was very difficult to test the bindings because the PyMutex API is so limited.

[ZeroIntensity]

Ideally, we should document that it's for use in assertions only. We need to make sure we're not enabling people to write thread-unsafe code like this:

if (PyMutex_IsLocked(lock)) {
    PyMutex_Unlock(lock);
}

[makslevental]

Ideally, we should document that it's for use in assertions only

maybe something like

#define ASSERT_PY_MUTEX_IS_LOCKED(mutex, msg) assert(PyMutex_IsLocked(mutex) && msg)

?

but not sure if this y'all's style (i came here from mlir...)

[hawkinsp]

It's important to expose an API like PyMutex_IsLocked even if you expose some sort of assertion helper, because people want to use their own debugging/printing/logging libraries to handle this sort of failure.

[colesbury]

Yeah, I just want to echo @hawkinsp comment. I think we should expose PyMutex_IsLocked() and document its intended purposes. I don't think we need to be overly concerned about people misusing it.

[colesbury]

We should also open a corresponding issue in the C API working group