Skip to content

gh-146536: docs: Clarify that PyMutex is not re-entrant #146543

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dagangtj wants to merge 1 commit into
base: main
Choose a base branch
from
Open

gh-146536: docs: Clarify that PyMutex is not re-entrant #146543

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 17 additions & 2 deletions Doc/c-api/synchronization.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Comment on lines +27 to +33
Copy link
Copy Markdown
Member

@encukou encukou Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we need the note both here and on PyMutex_Lock.

Suggested change
.. 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)
Expand All @@ -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 <attached 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.
Comment on lines +45 to +46
Copy link
Copy Markdown
Member

@encukou encukou Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is redundant.

Suggested change
:c:type:`!PyMutex` is not re-entrant. For re-entrant locking, use
:c:func:`Py_BEGIN_CRITICAL_SECTION` instead.
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.
Comment on lines +53 to +55
Copy link
Copy Markdown
Member

@encukou encukou Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it a guaranteed fatal error, or undefined behaviour? It can't be both at once.


.. versionadded:: 3.13

Expand Down
Loading