@@ -55,6 +55,11 @@ The following functions can be safely called before Python is initialized:
5555 * :c:func: `PyMem_RawCalloc `
5656 * :c:func: `PyMem_RawFree `
5757
58+ * Synchronization:
59+
60+ * :c:func: `PyMutex_Lock `
61+ * :c:func: `PyMutex_Unlock `
62+
5863.. note ::
5964
6065 The following functions **should not be called ** before
@@ -391,9 +396,16 @@ Initializing and finalizing the interpreter
391396 :c:func: `Py_NewInterpreter ` below) that were created and not yet destroyed since
392397 the last call to :c:func:`Py_Initialize`. Ideally, this frees all memory
393398 allocated by the Python interpreter. This is a no-op when called for a second
394- time (without calling :c:func: `Py_Initialize ` again first). Normally the
395- return value is ``0``. If there were errors during finalization
396- (flushing buffered data), ``-1`` is returned.
399+ time (without calling :c:func: `Py_Initialize ` again first).
400+
401+ Since this is the reverse of :c:func:`Py_Initialize`, it should be called
402+ in the same thread with the same interpreter active. That means
403+ the main thread and the main interpreter.
404+ This should never be called while :c:func:`Py_RunMain` is running.
405+
406+ Normally the return value is ``0``.
407+ If there were errors during finalization (flushing buffered data),
408+ ``-1`` is returned.
397409
398410 This function is provided for a number of reasons. An embedding application
399411 might want to restart Python without having to restart the application itself.
@@ -2152,3 +2164,145 @@ be used in new code.
21522164.. c:function:: void PyThread_delete_key_value(int key)
21532165.. c:function:: void PyThread_ReInitTLS()
21542166
2167+ Synchronization Primitives
2168+ ==========================
2169+
2170+ The C-API provides a basic mutual exclusion lock.
2171+
2172+ .. c:type:: PyMutex
2173+
2174+ A mutual exclusion lock. The :c:type:`!PyMutex` should be initialized to
2175+ zero to represent the unlocked state. For example::
2176+
2177+ PyMutex mutex = {0};
2178+
2179+ Instances of :c:type:`!PyMutex` should not be copied or moved. Both the
2180+ contents and address of a :c:type:`!PyMutex` are meaningful, and it must
2181+ remain at a fixed, writable location in memory.
2182+
2183+ .. note::
2184+
2185+ A :c:type:`!PyMutex` currently occupies one byte, but the size should be
2186+ considered unstable. The size may change in future Python releases
2187+ without a deprecation period.
2188+
2189+ .. versionadded:: 3.13
2190+
2191+ .. c:function:: void PyMutex_Lock(PyMutex *m)
2192+
2193+ Lock mutex *m*. If another thread has already locked it, the calling
2194+ thread will block until the mutex is unlocked. While blocked, the thread
2195+ will temporarily release the :term:`GIL` if it is held.
2196+
2197+ .. versionadded:: 3.13
2198+
2199+ .. c:function:: void PyMutex_Unlock(PyMutex *m)
2200+
2201+ Unlock mutex *m*. The mutex must be locked --- otherwise, the function will
2202+ issue a fatal error.
2203+
2204+ .. versionadded:: 3.13
2205+
2206+ .. _python-critical-section-api:
2207+
2208+ Python Critical Section API
2209+ ---------------------------
2210+
2211+ The critical section API provides a deadlock avoidance layer on top of
2212+ per-object locks for :term:`free-threaded <free threading>` CPython. They are
2213+ intended to replace reliance on the :term:`global interpreter lock`, and are
2214+ no-ops in versions of Python with the global interpreter lock.
2215+
2216+ Critical sections avoid deadlocks by implicitly suspending active critical
2217+ sections and releasing the locks during calls to :c:func:`PyEval_SaveThread`.
2218+ When :c:func:`PyEval_RestoreThread` is called, the most recent critical section
2219+ is resumed, and its locks reacquired. This means the critical section API
2220+ provides weaker guarantees than traditional locks -- they are useful because
2221+ their behavior is similar to the :term:`GIL`.
2222+
2223+ The functions and structs used by the macros are exposed for cases
2224+ where C macros are not available. They should only be used as in the
2225+ given macro expansions. Note that the sizes and contents of the structures may
2226+ change in future Python versions.
2227+
2228+ .. note::
2229+
2230+ Operations that need to lock two objects at once must use
2231+ :c:macro:`Py_BEGIN_CRITICAL_SECTION2`. You *cannot* use nested critical
2232+ sections to lock more than one object at once, because the inner critical
2233+ section may suspend the outer critical sections. This API does not provide
2234+ a way to lock more than two objects at once.
2235+
2236+ Example usage::
2237+
2238+ static PyObject *
2239+ set_field(MyObject *self, PyObject *value)
2240+ {
2241+ Py_BEGIN_CRITICAL_SECTION(self);
2242+ Py_SETREF(self->field, Py_XNewRef(value));
2243+ Py_END_CRITICAL_SECTION();
2244+ Py_RETURN_NONE;
2245+ }
2246+
2247+ In the above example, :c:macro:`Py_SETREF` calls :c:macro:`Py_DECREF`, which
2248+ can call arbitrary code through an object's deallocation function. The critical
2249+ section API avoids potentital deadlocks due to reentrancy and lock ordering
2250+ by allowing the runtime to temporarily suspend the critical section if the
2251+ code triggered by the finalizer blocks and calls :c:func:`PyEval_SaveThread`.
2252+
2253+ .. c:macro:: Py_BEGIN_CRITICAL_SECTION(op)
2254+
2255+ Acquires the per-object lock for the object *op* and begins a
2256+ critical section.
2257+
2258+ In the free-threaded build, this macro expands to::
2259+
2260+ {
2261+ PyCriticalSection _py_cs;
2262+ PyCriticalSection_Begin(&_py_cs, (PyObject*)(op))
2263+
2264+ In the default build, this macro expands to ``{``.
2265+
2266+ .. versionadded:: 3.13
2267+
2268+ .. c:macro:: Py_END_CRITICAL_SECTION()
2269+
2270+ Ends the critical section and releases the per-object lock.
2271+
2272+ In the free-threaded build, this macro expands to::
2273+
2274+ PyCriticalSection_End(&_py_cs);
2275+ }
2276+
2277+ In the default build, this macro expands to ``}``.
2278+
2279+ .. versionadded:: 3.13
2280+
2281+ .. c:macro:: Py_BEGIN_CRITICAL_SECTION2(a, b)
2282+
2283+ Acquires the per-objects locks for the objects *a* and *b* and begins a
2284+ critical section. The locks are acquired in a consistent order (lowest
2285+ address first) to avoid lock ordering deadlocks.
2286+
2287+ In the free-threaded build, this macro expands to::
2288+
2289+ {
2290+ PyCriticalSection2 _py_cs2;
2291+ PyCriticalSection_Begin2(&_py_cs2, (PyObject*)(a), (PyObject*)(b))
2292+
2293+ In the default build, this macro expands to ``{``.
2294+
2295+ .. versionadded:: 3.13
2296+
2297+ .. c:macro:: Py_END_CRITICAL_SECTION2()
2298+
2299+ Ends the critical section and releases the per-object locks.
2300+
2301+ In the free-threaded build, this macro expands to::
2302+
2303+ PyCriticalSection_End2(&_py_cs2);
2304+ }
2305+
2306+ In the default build, this macro expands to ``}``.
2307+
2308+ .. versionadded:: 3.13
0 commit comments