Feature or enhancement

Overview

The PyMutex APIs are currently internal-only in pycore_lock.h. This proposes making the type and two functions public in as part of the general, non-limited API in Include/cpython/lock.h.

The APIs to be included in the public header are:

typedef struct PyMutex {
    uint8_t v;
} PyMutex;

static inline void PyMutex_Lock(PyMutex *m) { ... }
static inline void PyMutex_Unlock(PyMutex *m) { ... }

// (private) slow path for locking the mutex
PyAPI_FUNC(void) _PyMutex_LockSlow(PyMutex *m);

// (private) slow path for unlocking the mutex
PyAPI_FUNC(void) _PyMutex_UnlockSlow(PyMutex *m);

Motivation

• With the free-threaded build, C API extensions are more likely to require locking for thread-safety
• The PyMutex API is easier to use correctly than the existing PyThread_type_lock. The PyMutex APIs release the GIL before blocking, whereas with the PyThread_type_lock APIs you often want to use a two step approach to locking to release the GIL before blocking.
• The PyMutex API enables a more efficient implementation: it's faster to acquire when the lock is not contended and does not require allocation.

C-API WG issue

• Make PyMutex public in the non-limited API capi-workgroup/decisions#22

cc @ngoldbaum

Linked PRs

• gh-117511: Make PyMutex public in the non-limited API #117731
• [3.13] gh-117511: Make PyMutex public in the non-limited API (GH-117731) #120800