Skip to content

enhance docs for critical sections #137334

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
wants to merge 1 commit into
base: main
Choose a base branch
from
+26 −5
Open

enhance docs for critical sections #137334

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
31 changes: 26 additions & 5 deletions Doc/c-api/init.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2299,12 +2299,33 @@ per-object locks for :term:`free-threaded <free threading>` CPython. They are
intended to replace reliance on the :term:`global interpreter lock`, and are
no-ops in versions of Python with the global interpreter lock.

Critical sections are intended to be used for custom types implemented
in C-API extensions. They should generally not be used with built-in types like
:class:`list` and :class:`dict` because their public C-APIs
already use critical sections internally, with the notable
exception of :c:func:`PyDict_Next`, which requires critical section
to be acquired externally.
Copy link
Contributor

@ngoldbaum ngoldbaum Aug 4, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

I'm not sure if I agree here. Unless I've done something wrong in NumPy. I handled this for lists using the PySequence API. I take a critical section on a list, convert to a sequence using PySequence_Fast, and then operate on the sequence under a critical section. The sequence APIs also bypass the internal critical sections and they're documented not to be thread-safe, so I think this is actually the only safe way to use PySequence_Fast correctly on the free-threaded build.


Critical sections avoid deadlocks by implicitly suspending active critical
sections and releasing the locks during calls to :c:func:`PyEval_SaveThread`.
When :c:func:`PyEval_RestoreThread` is called, the most recent critical section
is resumed, and its locks reacquired. This means the critical section API
provides weaker guarantees than traditional locks -- they are useful because
their behavior is similar to the :term:`GIL`.
sections, hence, they do not provide exclusive access such as provided by
traditional locks like :c:type:`PyMutex`. When a critical section is started,
the per-object lock for the object is acquired. If the code executed inside the
critical section suspends the critical section, the per-object lock is released,
so other threads can acquire the per-object lock for the same object.

The critical sections can be suspended in the following situations:

* Calling back into Python code, such as calling a Python function or method.

* Calling any C API function which internally uses critical sections
such as :c:func:`PyList_Append` and :c:func:`PyDict_SetItem`.

* Locking of :c:type:`PyMutex` by :c:func:`PyMutex_Lock`.

* Calling :c:func:`PyEval_SaveThread` to detach the current thread.

* Recursively entering the critical section for the same object.
Copy link
Contributor

Choose a reason for hiding this comment

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

In 3.14, don't recursive critical sections not get suspended?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

it isn't exactly recursive, there is one more condition which is that the critical section should be the topmost held critical section otherwise it can still get suspended


Copy link
Contributor

Choose a reason for hiding this comment

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

It may be worth mentioning that these are exactly the same guarantees provided by the GIL.


Variants that accept :c:type:`PyMutex` pointers rather than Python objects are also
available. Use these variants to start a critical section in a situation where
Expand Down
Loading