Repository navigation
Closed
Milestone
Description
Tracking issue for free-threaded Python (Py_GIL_DISABLED) support. Companion to the umbrella 3.14 tracker #2610.
Why FT is different from a normal GIL build
PyObject_HEADis 16 bytes larger; the refcount is split acrossob_ref_local+ob_ref_sharedand must be read viaPy_REFCNT(a real exported symbol on 3.14+).- Build detection:
sys._is_gil_enabled()(added in 3.13) returnsFalseon FT. - The GIL has been silently serialising every pythonnet static cache, lock-free counter, finalizer-thread interaction, and
Reflection.Emituse site. All of those need explicit synchronisation under FT.
Hazards in pythonnet (resolved by PR #2721)
| Area | What broke | How it was fixed |
|---|---|---|
| Refcount / ABI | Single-offset read | Py_REFCNT P/Invoke + ObjectHeadOffset = 16 for FT |
| Type-creation race | Duplicate cache.Add; partial-type visibility |
Two-cache (cache + _inProgressCache) under _cacheCreateLock |
GCHandle in tp_clear/tp_dealloc |
Double-free under main-thread + finalizer-thread race | Interlocked.Exchange on the slot |
Reflection.Emit |
Concurrent DefineType corrupts IL / throws "Duplicate type name" |
Lock both CreateDerivedType and DelegateManager.GetDispatcher |
| Static collections | Plain Dictionary/HashSet/List thread-safety issues |
ConcurrentDictionary where possible; Interlocked/Volatile for single-cell state; locks for nested mutation and ordered list semantics |
Finalizer-thread / Py_Finalize interaction |
Stale ob_ref_local reads after teardown crash the process |
Runtime._Py_IsFinalizing() guards on all decref-from-finalizer paths |
Chained ClassDerived.Finalize IL |
Nested Python-derived classes with __namespace__ chained through emitted Finalize methods, queuing the same __pyobj__ twice → PyObject_GC_Del on freed memory |
Skip the base-Finalize chain when the base is itself pythonnet-emitted (IPythonDerivedType) |
See PR #2721 for the per-file detail.
References
- PR: Python 3.14 free-threaded support #2721
- Umbrella 3.14 tracker: Add support for Python 3.14 #2610
- CPython PEP 703: https://peps.python.org/pep-0703/
- CPython 3.14 free-threading docs: https://docs.python.org/3.14/howto/free-threading-extensions.html
Metadata
Metadata
Assignees
Labels
No labels
Activity
Initialise pythonnet on free-threaded Python (pythonnet#2720)
Initialise pythonnet on free-threaded Python (pythonnet#2720)
Huaian666 commentedon Jun 5, 2026
idk who designed the api but they clearly actually use their own product. everything is where you'd expect it to be. refreshing.
Initialise pythonnet on free-threaded Python (pythonnet#2720)
Python 3.14 free-threaded support (#2721)