pythongh-117511: Make PyMutex public in the non-limited API

Doc/c-api/init.rst

@@ -53,6 +53,11 @@ The following functions can be safely called before Python is initialized:
   * :c:func:`PyMem_RawCalloc`
   * :c:func:`PyMem_RawFree`
 
+* Synchronization
+
+  * :c:func:`PyMutex_Lock`
+  * :c:func:`PyMutex_Unlock`
+
 .. note::
 
    The following functions **should not be called** before
@@ -1942,3 +1947,31 @@ be used in new code.
 .. c:function:: void PyThread_delete_key_value(int key)
 .. c:function:: void PyThread_ReInitTLS()
 
+Synchronization Primitives
+==========================
+
+The C-API provides a basic mutual exclusion lock.
+
+.. c:type:: PyMutex
+
+   A mutual exclusion lock.  The ``PyMutex`` should be initialized to zero to
+   represent the unlocked state.  For example::
+
+      PyMutex mutex = {0};
+
+   .. versionadded:: 3.13
+
+.. c:function:: void PyMutex_Lock(PyMutex *m)
+
+   Lock the mutex.  If another thread has already locked it, the calling
+   thread will block until the mutex is unlocked.  While blocked, the thread
+   will temporarily release the :term:`GIL` if it is held.
+
+   .. versionadded:: 3.13
+
+.. c:function:: void PyMutex_Unlock(PyMutex *m)
+
+   Unlock the mutex. The mutex must be locked --- otherwise, the function will
+   issue a fatal error.
+
+   .. versionadded:: 3.13

Doc/whatsnew/3.13.rst

@@ -1813,6 +1813,11 @@ New Features
 * Add :c:func:`PyType_GetModuleByDef` to the limited C API
   (Contributed by Victor Stinner in :gh:`116936`.)
 
+* Add :c:type:`PyMutex` API, a lightweight mutex that occupies a single byte.
+  The :c:func:`PyMutex_Lock` function will release the GIL (if currently held)
+  if the operation needs to block.
+  (Contributed by Sam Gross in :gh:`108724`.)
+
 
 Porting to Python 3.13
 ----------------------

Include/Python.h

@@ -55,6 +55,7 @@
 #include "pybuffer.h"
 #include "pystats.h"
 #include "pyatomic.h"
+#include "lock.h"
 #include "object.h"
 #include "objimpl.h"
 #include "typeslots.h"

Include/cpython/lock.h

@@ -0,0 +1,59 @@
+#ifndef Py_CPYTHON_LOCK_H
+#  error "this header file must not be included directly"
+#endif
+
+#define _Py_UNLOCKED    0
+#define _Py_LOCKED      1
+
+// A mutex that occupies one byte. The lock can be zero initialized.
+//
+// Only the two least significant bits are used. The remaining bits should be
+// zero:
+// 0b00: unlocked
+// 0b01: locked
+// 0b10: unlocked and has parked threads
+// 0b11: locked and has parked threads
+//
+// Typical initialization:
+//   PyMutex m = (PyMutex){0};
+//
+// Or initialize as global variables:
+//   static PyMutex m;
+//
+// Typical usage:
+//   PyMutex_Lock(&m);
+//   ...
+//   PyMutex_Unlock(&m);
+typedef struct _PyMutex {
+    uint8_t v;
+} PyMutex;
+
+// (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);
+
+// Locks the mutex.
+//
+// If the mutex is currently locked, the calling thread will be parked until
+// the mutex is unlocked. If the current thread holds the GIL, then the GIL
+// will be released while the thread is parked.
+static inline void
+PyMutex_Lock(PyMutex *m)
+{
+    uint8_t expected = _Py_UNLOCKED;
+    if (!_Py_atomic_compare_exchange_uint8(&m->v, &expected, _Py_LOCKED)) {
+        _PyMutex_LockSlow(m);
+    }
+}
+
+// Unlocks the mutex.
+static inline void
+PyMutex_Unlock(PyMutex *m)
+{
+    uint8_t expected = _Py_LOCKED;
+    if (!_Py_atomic_compare_exchange_uint8(&m->v, &expected, _Py_UNLOCKED)) {
+        _PyMutex_UnlockSlow(m);
+    }
+}

Include/internal/pycore_lock.h

@@ -13,79 +13,17 @@ extern "C" {
 #  error "this header requires Py_BUILD_CORE define"
 #endif
 
-
-// A mutex that occupies one byte. The lock can be zero initialized.
-//
-// Only the two least significant bits are used. The remaining bits should be
-// zero:
-// 0b00: unlocked
-// 0b01: locked
-// 0b10: unlocked and has parked threads
-// 0b11: locked and has parked threads
-//
-// Typical initialization:
-//   PyMutex m = (PyMutex){0};
-//
-// Or initialize as global variables:
-//   static PyMutex m;
-//
-// Typical usage:
-//   PyMutex_Lock(&m);
-//   ...
-//   PyMutex_Unlock(&m);
-
-// NOTE: In Py_GIL_DISABLED builds, `struct _PyMutex` is defined in Include/object.h.
-// The Py_GIL_DISABLED builds need the definition in Include/object.h for the
-// `ob_mutex` field in PyObject. For the default (non-free-threaded) build,
-// we define the struct here to avoid exposing it in the public API.
-#ifndef Py_GIL_DISABLED
-struct _PyMutex { uint8_t v; };
-#endif
-
-typedef struct _PyMutex PyMutex;
-
-#define _Py_UNLOCKED    0
-#define _Py_LOCKED      1
+//_Py_UNLOCKED is defined as 0 and _Py_LOCKED as 1 in Include/cpython/lock.h
 #define _Py_HAS_PARKED  2
 #define _Py_ONCE_INITIALIZED 4
 
-// (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);
-
 static inline int
 PyMutex_LockFast(uint8_t *lock_bits)
 {
     uint8_t expected = _Py_UNLOCKED;
     return _Py_atomic_compare_exchange_uint8(lock_bits, &expected, _Py_LOCKED);
 }
 
-// Locks the mutex.
-//
-// If the mutex is currently locked, the calling thread will be parked until
-// the mutex is unlocked. If the current thread holds the GIL, then the GIL
-// will be released while the thread is parked.
-static inline void
-PyMutex_Lock(PyMutex *m)
-{
-    uint8_t expected = _Py_UNLOCKED;
-    if (!_Py_atomic_compare_exchange_uint8(&m->v, &expected, _Py_LOCKED)) {
-        _PyMutex_LockSlow(m);
-    }
-}
-
-// Unlocks the mutex.
-static inline void
-PyMutex_Unlock(PyMutex *m)
-{
-    uint8_t expected = _Py_LOCKED;
-    if (!_Py_atomic_compare_exchange_uint8(&m->v, &expected, _Py_UNLOCKED)) {
-        _PyMutex_UnlockSlow(m);
-    }
-}
-
 // Checks if the mutex is currently locked.
 static inline int
 PyMutex_IsLocked(PyMutex *m)

Include/lock.h

@@ -0,0 +1,16 @@
+#ifndef Py_LOCK_H
+#define Py_LOCK_H
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifndef Py_LIMITED_API
+#  define Py_CPYTHON_LOCK_H
+#  include "cpython/lock.h"
+#  undef Py_CPYTHON_LOCK_H
+#endif
+
+#ifdef __cplusplus
+}
+#endif
+#endif /* !Py_LOCK_H */

Include/object.h

@@ -207,10 +207,6 @@ struct _object {
 // Create a shared field from a refcnt and desired flags
 #define _Py_REF_SHARED(refcnt, flags) (((refcnt) << _Py_REF_SHARED_SHIFT) + (flags))
 
-// NOTE: In non-free-threaded builds, `struct _PyMutex` is defined in
-// pycore_lock.h. See pycore_lock.h for more details.
-struct _PyMutex { uint8_t v; };
-
 struct _object {
     // ob_tid stores the thread id (or zero). It is also used by the GC and the
     // trashcan mechanism as a linked list pointer and by the GC to store the

Makefile.pre.in

@@ -1013,6 +1013,7 @@ PYTHON_HEADERS= \
 		$(srcdir)/Include/intrcheck.h \
 		$(srcdir)/Include/iterobject.h \
 		$(srcdir)/Include/listobject.h \
+		$(srcdir)/Include/lock.h \
 		$(srcdir)/Include/longobject.h \
 		$(srcdir)/Include/marshal.h \
 		$(srcdir)/Include/memoryobject.h \
@@ -1084,6 +1085,7 @@ PYTHON_HEADERS= \
 		$(srcdir)/Include/cpython/import.h \
 		$(srcdir)/Include/cpython/initconfig.h \
 		$(srcdir)/Include/cpython/listobject.h \
+		$(srcdir)/Include/cpython/lock.h \
 		$(srcdir)/Include/cpython/longintrepr.h \
 		$(srcdir)/Include/cpython/longobject.h \
 		$(srcdir)/Include/cpython/memoryobject.h \

PCbuild/pythoncore.vcxproj

@@ -155,6 +155,7 @@
     <ClInclude Include="..\Include\cpython\import.h" />
     <ClInclude Include="..\Include\cpython\initconfig.h" />
     <ClInclude Include="..\Include\cpython\listobject.h" />
+    <ClInclude Include="..\Include\cpython\lock.h" />
     <ClInclude Include="..\Include\cpython\longintrepr.h" />
     <ClInclude Include="..\Include\cpython\longobject.h" />
     <ClInclude Include="..\Include\cpython\memoryobject.h" />
@@ -308,6 +309,7 @@
     <ClInclude Include="..\Include\intrcheck.h" />
     <ClInclude Include="..\Include\iterobject.h" />
     <ClInclude Include="..\Include\listobject.h" />
+    <ClInclude Include="..\Include\lock.h" />
     <ClInclude Include="..\Include\longobject.h" />
     <ClInclude Include="..\Include\marshal.h" />
     <ClInclude Include="..\Include\memoryobject.h" />

PCbuild/pythoncore.vcxproj.filters

@@ -114,6 +114,9 @@
     <ClInclude Include="..\Include\listobject.h">
       <Filter>Include</Filter>
     </ClInclude>
+    <ClInclude Include="..\Include\lock.h">
+      <Filter>Include</Filter>
+    </ClInclude>
     <ClInclude Include="..\Include\longobject.h">
       <Filter>Include</Filter>
     </ClInclude>
@@ -393,6 +396,9 @@
     <ClInclude Include="..\Include\cpython\listobject.h">
       <Filter>Include\cpython</Filter>
     </ClInclude>
+    <ClInclude Include="..\Include\cpython\lock.h">
+      <Filter>Include</Filter>
+    </ClInclude>
     <ClInclude Include="..\Include\cpython\longintrepr.h">
       <Filter>Include</Filter>
     </ClInclude>