Mark unique tuple freeing as non-escaping

python · Fidget-Spinner · Mar 22, 2026 · Jan 28, 2026 · Jan 28, 2026 · Jan 28, 2026
commit 89dc467e4d0f8f8a25edd7e7fb7113807b4310c4
diff --git a/Include/internal/pycore_tuple.h b/Include/internal/pycore_tuple.h
@@ -21,7 +21,7 @@ extern PyStatus _PyTuple_InitGlobalObjects(PyInterpreterState *);
 
 /* other API */
 
-PyAPI_FUNC(void) _PyTuple_Free(PyObject *self);
+PyAPI_FUNC(void) _PyStolenTuple_Free(PyObject *self);
 
 #define _PyTuple_ITEMS(op) _Py_RVALUE(_PyTuple_CAST(op)->ob_item)
 

diff --git a/Include/internal/pycore_uop_ids.h b/Include/internal/pycore_uop_ids.h
diff --git a/Include/internal/pycore_uop_metadata.h b/Include/internal/pycore_uop_metadata.h
diff --git a/Objects/tupleobject.c b/Objects/tupleobject.c
@@ -234,16 +234,20 @@ _PyTuple_FromPairSteal(PyObject *first, PyObject *second)
 
 /* Methods */
 
+/*
+ Free of a tuple where all contents have been stolen and
+ is now untracked by GC. This operation is thus non-escaping.
+ */
 void
-_PyTuple_Free(PyObject *obj)
+_PyStolenTuple_Free(PyObject *obj)
 {
     assert(PyTuple_CheckExact(obj));
     PyTupleObject *op = _PyTuple_CAST(obj);
     assert(Py_SIZE(op) != 0);
-
+    assert(!_PyObject_GC_IS_TRACKED(obj));
     // This will abort on the empty singleton (if there is one).
     if (!maybe_freelist_push(op)) {
-        Py_TYPE(op)->tp_free((PyObject *)op);
+        PyTuple_Type.tp_free((PyObject *)op);
     }
 }
 

@@ -33,7 +33,7 @@
 #include "pycore_sliceobject.h"   // _PyBuildSlice_ConsumeRefs
 #include "pycore_stackref.h"
 #include "pycore_template.h"      // _PyTemplate_Build()
-#include "pycore_tuple.h"         // _PyTuple_Free(), _PyTuple_ITEMS()
+#include "pycore_tuple.h"         // _PyStolenTuple_Free(), _PyTuple_ITEMS()
 #include "pycore_typeobject.h"    // _PySuper_Lookup()
 
 #include "pycore_dict.h"
@@ -1745,7 +1745,7 @@ dummy_func(
             val0 = PyStackRef_FromPyObjectSteal(PyTuple_GET_ITEM(seq_o, 0));
             val1 = PyStackRef_FromPyObjectSteal(PyTuple_GET_ITEM(seq_o, 1));
             PyObject_GC_UnTrack(seq_o);
-            _PyTuple_Free(seq_o);
+            _PyStolenTuple_Free(seq_o);
         }
 
         op(_UNPACK_SEQUENCE_UNIQUE_THREE_TUPLE, (seq -- val2, val1, val0)) {
@@ -1755,7 +1755,7 @@ dummy_func(
             val1 = PyStackRef_FromPyObjectSteal(PyTuple_GET_ITEM(seq_o, 1));
             val2 = PyStackRef_FromPyObjectSteal(PyTuple_GET_ITEM(seq_o, 2));
             PyObject_GC_UnTrack(seq_o);
-            _PyTuple_Free(seq_o);
+            _PyStolenTuple_Free(seq_o);
         }
 
         macro(UNPACK_SEQUENCE_TUPLE) =
@@ -1784,7 +1784,7 @@ dummy_func(
                 *values++ = PyStackRef_FromPyObjectSteal(items[i]);
             }
             PyObject_GC_UnTrack(seq_o);
-            _PyTuple_Free(seq_o);
+            _PyStolenTuple_Free(seq_o);
         }
 
         macro(UNPACK_SEQUENCE_LIST) =

diff --git a/Python/executor_cases.c.h b/Python/executor_cases.c.h
@@ -715,6 +715,8 @@ def has_error_without_pop(op: parser.CodeDef) -> bool:
     "_PyThreadState_PopCStackRefSteal",
     "doesnt_escape",
     "_Py_GatherStats_GetIter",
+    "_PyStolenTuple_Free",
+    "PyObject_GC_UnTrack",
 )