Feature or enhancement

Overview

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

The APIs to be included in the public header are:

typedefstructPyMutex {uint8_tv;}PyMutex;staticinlinevoidPyMutex_Lock(PyMutex*m) { ... }staticinlinevoidPyMutex_Unlock(PyMutex*m) { ... }// (private) slow path for locking the mutexPyAPI_FUNC(void)_PyMutex_LockSlow(PyMutex*m);// (private) slow path for unlocking the mutexPyAPI_FUNC(void)_PyMutex_UnlockSlow(PyMutex*m);

Motivation

• With the free-threaded build, C API extensions are more likely to require locking for thread-safety
• ThePyMutex API is easier to use correctly than the existingPyThread_type_lock. ThePyMutex APIs release the GIL before blocking, whereas with thePyThread_type_lock APIs you often want to use atwo step approach to locking to release the GIL before blocking.
• ThePyMutex 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

• MakePyMutex 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