Problem: Free-threaded (nogil) Python with native C/C++ extensions that lack upstream nogil safety or assume GIL synchronization, causing race conditions, state corruption, or crashes.
Constraints: Need true thread-level concurrency; avoid heavy memory copies, IPC overhead, or upstream extension rewrites.
Question: What practical architectures or synchronization patterns handle nogil-unsafe C/C++ extensions safely under concurrent load without prohibitive copy/IPC cost?
Verified facts, CPython 3.13-3.15 (2026-11).
GIL fallback
- Extension without Py_mod_gil=Py_MOD_GIL_NOT_USED (multi-phase) or PyUnstable_Module_SetGIL(m, Py_MOD_GIL_NOT_USED) (single-phase, #ifdef Py_GIL_DISABLED) -> import re-enables the GIL process-wide + RuntimeWarning.
- PYTHON_GIL=0 / -X gil=0 keeps it off; safety is then yours. Check: sys._is_gil_enabled().
No changes to the extension
1. One threading.Lock around every call into the unsafe library; all other code stays parallel. Library throughput = 1 call at a time.
2. One library instance per thread (threading.local / contextvars) if state is per-object, not global.
3. Owner thread + queue.Queue: only that thread touches the extension; same address space, pass references, no copies.
4. Share inputs read-only (bytes, tuple, read-only memoryview). NumPy: per-thread arrays or read-only sharing; no guarantee for concurrent mutation (resize during read can crash). RNG: one Generator per thread from SeedSequence(...).spawn(n).
5. concurrent.interpreters / InterpreterPoolExecutor (3.14) only if the module declares Py_MOD_PER_INTERPRETER_GIL_SUPPORTED. Omitted slot = Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED (shared GIL only); single-phase modules cannot declare it. Zero-copy between interpreters: memoryview, Queue; None/bool/bytes/str/int/float/tuple shared or cheaply copied; everything else pickled.
6. Last resort: processes + multiprocessing.shared_memory (buffer not copied, control still IPC).
Small C patches (no rewrite)
- Global static state / non-reentrant library: one global PyMutex (PyMutex_Lock/Unlock, 3.13) around every library call. Per-instance state: PyMutex in the instance struct.
- PyMutex detaches the thread state while blocking (safe with stop-the-world GC). A std::mutex held while calling into Python can deadlock.
- Own types: Py_BEGIN_CRITICAL_SECTION(o) / Py_BEGIN_CRITICAL_SECTION2(a,b) (3.13); _MUTEX variants taking PyMutex* (3.14). Suspended when the thread blocks/detaches, so weaker than a held mutex. Do not nest two single sections; use the 2-form.
- Builtin list/dict/set C-API calls lock internally (e.g. PyList_Append); PyDict_Next does not: wrap the loop in Py_BEGIN_CRITICAL_SECTION(dict). Each call locks separately, so multi-call read-modify-write is not atomic.
- Borrowed -> strong refs: PyList_GetItemRef, PyDict_GetItemRef, PyDict_GetItemStringRef, PyDict_SetDefaultRef, PyWeakref_GetRef, PyImport_AddModuleRef, PyCell_Get. Older Pythons: pythoncapi-compat.
- Keep Py_BEGIN_ALLOW_THREADS around long blocking calls (still required on free-threaded builds).
- Raw buffers: PyMem_Malloc, not PyObject_Malloc.
- Declare GIL-free only after audit: Cython 3.1 "# cython: freethreading_compatible=True" (+ cython.critical_section, cython.pymutex); pybind11 2.13 py::mod_gil_not_used() (3.0: py::scoped_critical_section); nanobind 2.2 FREE_THREADED (nb::ft_mutex, nb::lock_self()); PyO3 0.28 defaults to thread-safe, unaudited modules need #[pymodule(gil_used = true)]; f2py --freethreading-compatible.
Testing / build
- configure --disable-gil --with-thread-sanitizer; suppressions: Tools/tsan/suppressions_free_threading.txt; pytest-run-parallel, pytest-freethreaded.
- Separate cp313t/cp314t wheels; no Limited API/abi3 on free-threaded 3.13/3.14; 3.15: abi3t (PEP 803, Py_TARGET_ABI3T).
Sources: docs.python.org/3.14/howto/free-threading-extensions.html, docs.python.org/3.15/c-api/synchronization.html, docs.python.org/3.14/library/concurrent.interpreters.html, py-free-threading.github.io/porting-extensions/, numpy.org/doc/stable/reference/thread_safety.html