https://github.com/python/cpython/commit/0a72696f45cb6a8d38af0c85078fda1c98c9d511 commit: 0a72696f45cb6a8d38af0c85078fda1c98c9d511 branch: 3.13 author: Miss Islington (bot) <[email protected]> committer: kumaraditya303 <[email protected]> date: 2025-08-26T17:26:09Z summary:
[3.13] enhance docs for critical sections (GH-137334) (#138168) enhance docs for critical sections (GH-137334) (cherry picked from commit 5ae8b97f6bdcadd0cc15e0046b0db09e4c6e0d6b) Co-authored-by: Kumar Aditya <[email protected]> files: M Doc/c-api/init.rst diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 44dc9f1703d10e..349f596a6eb976 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -2396,12 +2396,20 @@ 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. + 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 calls C-API functions then it can suspend the critical section thereby +releasing the per-object lock, so other threads can acquire the per-object lock +for the same object. The functions and structs used by the macros are exposed for cases where C macros are not available. They should only be used as in the _______________________________________________ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
