InternalDocs: the free threading GC can change ob_tid #144969

This came up in the Discord:

We should mention this in the InternalDocs/garbage_collector.md and _Py_CRITICAL_SECTION_ASSERT_OBJECT_LOCKED().

Context:

I have a question about _Py_CRITICAL_SECTION_ASSERT_OBJECT_LOCKED(). Why does it check Py_REFCNT(op) != 1 instead of calling PyUnstable_Object_IsUniquelyReferenced()

Answer:

In some cases, the free threading GC can change an object's ob_tid because it overwrites it and the restores it from the containing mimalloc segment data structure. (This can happen when an object is created by a thread and then the thread exits.)

So that means that in some rare cases:

if (PyUnstable_Object_IsUniquelyReferenced(obj)) {
   ... // trigger GC
   assert(PyUnstable_Object_IsUniquelyReferenced(obj);
}

the assert could fail. The important property we care about -- that we have exclusive access to obj -- is preserved, but PyUnstable_Object_IsUniquelyReferenced() is more conservative than that. So we use a looser check in the asserts.

Linked PRs

• gh-144969: Document that the free threading GC can change ob_tid #144972