From a5679f67baa91ca7f788edad7a3821cdb3b97574 Mon Sep 17 00:00:00 2001 From: dagangtj Date: Sat, 28 Mar 2026 10:46:14 +0800 Subject: [PATCH] docs: Clarify that PyMutex is not re-entrant Add explicit documentation that PyMutex is not re-entrant (recursive): - Add note to PyMutex type explaining it will deadlock on re-entry - Add warning to PyMutex_Lock about deadlock if already held - Clarify PyMutex_Unlock must be called by the locking thread Fixes python/cpython#146536 --- Doc/c-api/synchronization.rst | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/synchronization.rst b/Doc/c-api/synchronization.rst index 53c9faeae35464..c3395be9909642 100644 --- a/Doc/c-api/synchronization.rst +++ b/Doc/c-api/synchronization.rst @@ -24,6 +24,13 @@ The C-API provides a basic mutual exclusion lock. considered unstable. The size may change in future Python releases without a deprecation period. + .. note:: + + A :c:type:`!PyMutex` is **not** re-entrant (recursive). If a thread + that already holds the lock attempts to acquire it again, the thread + will deadlock. Use :c:func:`Py_BEGIN_CRITICAL_SECTION` instead if + re-entrancy is required. + .. versionadded:: 3.13 .. c:function:: void PyMutex_Lock(PyMutex *m) @@ -32,12 +39,20 @@ The C-API provides a basic mutual exclusion lock. thread will block until the mutex is unlocked. While blocked, the thread will temporarily detach the :term:`thread state ` if one exists. + .. warning:: + + This function will deadlock if the calling thread already holds the lock. + :c:type:`!PyMutex` is not re-entrant. For re-entrant locking, use + :c:func:`Py_BEGIN_CRITICAL_SECTION` instead. + .. versionadded:: 3.13 .. c:function:: void PyMutex_Unlock(PyMutex *m) - Unlock mutex *m*. The mutex must be locked --- otherwise, the function will - issue a fatal error. + Unlock mutex *m*. The mutex must be locked by the calling thread --- + otherwise, the function will issue a fatal error. Unlocking a mutex from + a different thread than the one that locked it results in undefined + behavior. .. versionadded:: 3.13