@@ -2396,12 +2396,20 @@ per-object locks for :term:`free-threaded <free threading>` CPython. They are
23962396intended to replace reliance on the :term:`global interpreter lock`, and are
23972397no-ops in versions of Python with the global interpreter lock.
23982398
2399+ Critical sections are intended to be used for custom types implemented
2400+ in C-API extensions. They should generally not be used with built-in types like
2401+ :class:`list` and :class:`dict` because their public C-APIs
2402+ already use critical sections internally, with the notable
2403+ exception of :c:func:`PyDict_Next`, which requires critical section
2404+ to be acquired externally.
2405+
23992406Critical sections avoid deadlocks by implicitly suspending active critical
2400- sections and releasing the locks during calls to :c:func:`PyEval_SaveThread`.
2401- When :c:func:`PyEval_RestoreThread` is called, the most recent critical section
2402- is resumed, and its locks reacquired. This means the critical section API
2403- provides weaker guarantees than traditional locks -- they are useful because
2404- their behavior is similar to the :term:`GIL`.
2407+ sections, hence, they do not provide exclusive access such as provided by
2408+ traditional locks like :c:type:`PyMutex`. When a critical section is started,
2409+ the per-object lock for the object is acquired. If the code executed inside the
2410+ critical section calls C-API functions then it can suspend the critical section thereby
2411+ releasing the per-object lock, so other threads can acquire the per-object lock
2412+ for the same object.
24052413
24062414The functions and structs used by the macros are exposed for cases
24072415where C macros are not available. They should only be used as in the
![pydoc-zh-tw[bot]](https://avatars.githubusercontent.com/in/137018?v=4&size=40){kind=avatar}
0 commit comments