Atomic GCHandle ownership and finalizer-thread shutdown guards

Two related sets of races that the GIL hid but free-threaded Python exposes reliably. ClassDerivedObject.tp_dealloc and ManagedType.TryFreeGCHandle both read the GCHandle slot, then mutated it. Under FT, subtype_clear (on the main thread) and the .NET finalizer thread can race for the same slot; a non-atomic read-then-zero lets both threads observe the same handle and double-free it. Both paths now use Interlocked.Exchange to atomically claim ownership of the slot - only the thread that observes a non-zero handle frees it. ClassDerived's strong-to-weak swap follows the same pattern. CreateDerivedType emits IL via Reflection.Emit, whose ModuleBuilder and TypeBuilder operations are documented as not thread-safe. Concurrent dynamic subclass creation under FT corrupts the IL stream and segfaults. Serialise the entire emit-and-bake sequence on the existing _buildersLock (the lock that already guarded the assembly / module builder cache). The .NET finalizer thread can dispatch Py_DecRef calls concurrently with Py_Finalize, and a stale read of ob_ref_local after teardown crashes the process. Three guards: - Finalizer.ThrottledCollect and PyObject's finalizer short-circuit when Runtime._Py_IsFinalizing(); PyObject drops the raw pointer instead of enqueueing a decref so process exit reclaims the memory. - Finalizer.AddFinalizedObject's Refcount > 0 Debug.Assert is kept on GIL builds and skipped on FT; a stale ob_ref_local read from the finalizer thread can crash the process even when the assertion would succeed under the GIL. - Runtime.XDecref's matching Refcount > 0 Debug.Assert gets the same FT-only skip for the same reason.
filmor · Sep 14, 2026 · May 9, 2026 · May 9, 2026 · May 9, 2026 · May 9, 2026
commit 585916ef447e809b19847fc8f111479c388113ac
diff --git a/src/runtime/Finalizer.cs b/src/runtime/Finalizer.cs
@@ -115,6 +115,10 @@ internal void ThrottledCollect()
 
             _throttled = unchecked(this._throttled + 1);
             if (!started || !Enable || _throttled < Threshold) return;
+            // Skip the drain while Python is finalizing: the .NET-side queue may
+            // contain references that became stale during teardown, and calling
+            // Py_DecRef on torn-down state segfaults under free-threaded Python.
+            if (Runtime._Py_IsFinalizing() == true) return;
             _throttled = 0;
             this.Collect();
         }
@@ -136,7 +140,13 @@ internal void AddFinalizedObject(ref IntPtr obj, int run
                 return;
             }
 
-            Debug.Assert(Runtime.Refcount(new BorrowedReference(obj)) > 0);
+            // Skip the Refcount sanity check under free-threaded Python: the .NET
+            // finalizer thread can race with Py_Finalize and a stale read of
+            // ob_ref_local will crash the process.  Keep the check on GIL builds.
+            if (!Native.ABI.IsFreeThreaded)
+            {
+                Debug.Assert(Runtime.Refcount(new BorrowedReference(obj)) > 0);
+            }
 
 #if FINALIZER_CHECK
             lock (_queueLock)

diff --git a/src/runtime/PythonTypes/PyObject.cs b/src/runtime/PythonTypes/PyObject.cs
@@ -110,13 +110,24 @@ internal PyObject(in StolenReference reference)
                 CheckRun();
 #endif
 
-                Interlocked.Increment(ref Runtime._collected);
+                // If Python is finalizing we cannot safely enqueue a decref:
+                // the .NET finalizer thread runs concurrently with Py_Finalize
+                // and any later Py_DecRef would touch torn-down state.  Drop
+                // the reference and let process exit reclaim the memory.
+                if (Runtime._Py_IsFinalizing() == true)
+                {
+                    rawPtr = IntPtr.Zero;
+                }
+                else
+                {
+                    Interlocked.Increment(ref Runtime._collected);
 
-                Finalizer.Instance.AddFinalizedObject(ref rawPtr, run
+                    Finalizer.Instance.AddFinalizedObject(ref rawPtr, run
 #if TRACE_ALLOC
-                    , Traceback
+                        , Traceback
 #endif
-                );
+                    );
+                }
             }
 
             Dispose(false);

diff --git a/src/runtime/Runtime.cs b/src/runtime/Runtime.cs
@@ -607,7 +607,10 @@ internal static unsafe void XIncref(BorrowedReference op)
         internal static unsafe void XDecref(StolenReference op)
         {
 #if DEBUG
-            Debug.Assert(op == null || Refcount(new BorrowedReference(op.Pointer)) > 0);
+            // The Refcount > 0 check is racy under free-threaded Python: the .NET
+            // finalizer thread can dispatch decrefs concurrently with Py_Finalize,
+            // and a stale read of ob_ref_local can crash the process.  Skip on FT.
+            Debug.Assert(op == null || Native.ABI.IsFreeThreaded || Refcount(new BorrowedReference(op.Pointer)) > 0);
             Debug.Assert(_isInitialized || Py_IsInitialized() != 0 || _Py_IsFinalizing() != false);
 #endif
             if (op == null) return;

diff --git a/src/runtime/Types/ClassDerived.cs b/src/runtime/Types/ClassDerived.cs
@@ -74,7 +74,7 @@ protected override void SetTypeNewSlot(BorrowedReference pyType, SlotsHolder slo
             // Python derived types rely on base tp_new and overridden __init__
         }
 
-        public new static void tp_dealloc(NewReference ob)
+        public new static unsafe void tp_dealloc(NewReference ob)
         {
             var self = (CLRObject?)GetManagedObject(ob.Borrow());
 
@@ -84,14 +84,26 @@ protected override void SetTypeNewSlot(BorrowedReference pyType, SlotsHolder slo
             // self may be null after Shutdown begun
             if (self is not null)
             {
-                // The python should now have a ref count of 0, but we don't actually want to
-                // deallocate the object until the C# object that references it is destroyed.
-                // So we don't call PyObject_GC_Del here and instead we set the python
-                // reference to a weak reference so that the C# object can be collected.
-                GCHandle oldHandle = GetGCHandle(ob.Borrow());
-                GCHandle gc = GCHandle.Alloc(self, GCHandleType.Weak);
-                SetGCHandle(ob.Borrow(), gc);
-                oldHandle.Free();
+                // Replace the strong handle with a weak one so the C# wrapper can be
+                // collected, but the Python object survives until it does.
+                //
+                // Under free-threaded Python a concurrent tp_dealloc/tp_clear path
+                // could race with us; do the swap atomically and only free the old
+                // handle if we were the thread that observed it.
+                GCHandle weak = GCHandle.Alloc(self, GCHandleType.Weak);
+                BorrowedReference borrow = ob.Borrow();
+                int offset = Util.ReadInt32(Runtime.PyObject_TYPE(borrow), Offsets.tp_clr_inst_offset);
+                IntPtr* slot = (IntPtr*)(borrow.DangerousGetAddress() + offset);
+                IntPtr oldRaw = System.Threading.Interlocked.Exchange(ref *slot, (IntPtr)weak);
+                if (oldRaw != IntPtr.Zero)
+                {
+                    ((GCHandle)oldRaw).Free();
+                }
+                else
+                {
+                    // Lost the race; another thread already cleared the slot.
+                    weak.Free();
+                }
             }
         }
 
@@ -166,6 +178,23 @@ internal static Type CreateDerivedType(string name,
                 assemblyName = "Python.Runtime.Dynamic";
             }
 
+            // Reflection.Emit's ModuleBuilder/TypeBuilder operations are not
+            // thread-safe; concurrent DefineType calls on the same module
+            // corrupt the IL stream and segfault under free-threaded Python.
+            // Serialise the entire emit-and-bake sequence on _buildersLock.
+            lock (_buildersLock)
+            {
+                return CreateDerivedTypeImpl(name, baseType, typeInterfaces, py_dict, assemblyName, moduleName);
+            }
+        }
+
+        private static Type CreateDerivedTypeImpl(string name,
+            Type baseType,
+            IList<Type> typeInterfaces,
+            BorrowedReference py_dict,
+            string assemblyName,
+            string moduleName)
+        {
             ModuleBuilder moduleBuilder = GetModuleBuilder(assemblyName, moduleName);
 
             Type baseClass = baseType;

diff --git a/src/runtime/Types/ManagedType.cs b/src/runtime/Types/ManagedType.cs
@@ -230,7 +230,7 @@ internal static void SetGCHandle(BorrowedReference reflectedClrObject, GCHandle
         internal static bool TryFreeGCHandle(BorrowedReference reflectedClrObject)
             => TryFreeGCHandle(reflectedClrObject, Runtime.PyObject_TYPE(reflectedClrObject));
 
-        internal static bool TryFreeGCHandle(BorrowedReference reflectedClrObject, BorrowedReference type)
+        internal static unsafe bool TryFreeGCHandle(BorrowedReference reflectedClrObject, BorrowedReference type)
         {
             Debug.Assert(type != null);
             Debug.Assert(reflectedClrObject != null);
@@ -240,13 +240,15 @@ internal static bool TryFreeGCHandle(BorrowedReference reflectedClrObject, Borro
             int offset = Util.ReadInt32(type, Offsets.tp_clr_inst_offset);
             Debug.Assert(offset > 0);
 
-            IntPtr raw = Util.ReadIntPtr(reflectedClrObject, offset);
+            // Atomic claim of the GCHandle: under free-threaded Python tp_clear
+            // and tp_dealloc can race against each other (e.g. main thread vs
+            // .NET finalizer thread).  A non-atomic read-then-zero would let
+            // both threads see the same handle and double-free it.
+            IntPtr* slot = (IntPtr*)(reflectedClrObject.DangerousGetAddress() + offset);
+            IntPtr raw = System.Threading.Interlocked.Exchange(ref *slot, IntPtr.Zero);
             if (raw == IntPtr.Zero) return false;
 
-            var handle = (GCHandle)raw;
-            handle.Free();
-
-            Util.WriteIntPtr(reflectedClrObject, offset, IntPtr.Zero);
+            ((GCHandle)raw).Free();
             return true;
         }