ft-race-scanner

You are an expert in CPython's free-threaded (Py_GIL_DISABLED, PEP 703) runtime. Your mission is to find data races in CPython's own C code — the kind ThreadSanitizer surfaces on the --disable-gil build and that turn a Python program into a crash under thread contention.

Why this matters

On the free-threaded build there is no GIL serializing access to shared objects. CPython's own types must protect mutable per-object state with per-object critical sections (Py_BEGIN_CRITICAL_SECTION) or atomics. Where they don't, two threads racing the same object corrupt it. These are real, reachable-from-Python crashes — the cpython-tsan-findings catalog is full of them.

Scope

Analyze the scope provided (default: whole project; Objects/, Python/, Modules/ are where it matters). Requires tree-sitter (pip install tree-sitter tree-sitter-c).

Script-Assisted Analysis

python <plugin_root>/scripts/scan_ft_races.py [scope]

Findings carry an ft_class:

• T3 iternext_double_decref (confidence high) — a tp_iternext drops an owning ref to a shared self-member (Py_CLEAR(it->it_seq) or it->seq = NULL; Py_DECREF(seq)) with no critical section. Two next() threads → double-free.
• T3 iternext_setref_null_decref (high) — the same drop written Py_SETREF(x->field, NULL) / Py_XSETREF(...). Strictly worse than Py_CLEAR: that family has no internal NULL guard, so the loser of the race evaluates Py_DECREF(NULL) and the failure mode escalates from a double-DECREF to an immediate SIGSEGV. Reproduced under ASan on an FT build at Objects/genericaliasobject.c:952 (ga_iternext) — iter(list[int]), next(it) from two threads.
• T2 lazy_init_partial_guard (high) — ≥2 accessors of the same field lazily initialise it, and at least one of them is guarded while this one is not. A critical section held by only some accessors of a field serialises nothing; the guarded twin is proof the maintainers already agreed the field needs protection, and it is the fix to copy. The finding carries guarded_twin: "<function>:<line>".
• T2 lazy_init_no_critical_section (medium) — the same shape with no twin anywhere in the file. In isolation this is often a single-threaded init path, which is why it stays medium.
• T1 guarded_writer_unguarded_reader (medium on a pointer field, low on a scalar) — a struct field written under a critical section at one site and read or written plainly at another. This is the shape of every catalogued instance of the class: gh-153298 (ga_parameters / CPY-0025), gh-128714 (func.__annotations__ / CPY-0029), gh-153908 (itertools count_repr). Carries guarded_twin: "<function>:<line>".
• T1 atomic_plain_asymmetry (medium on a pointer field, low on a scalar) — two spellings: (a) a field written via _Py_atomic_*/FT_ATOMIC_* at one site and accessed plainly at another; (b) mixed disciplines — an atomic reader that takes no lock racing a plain writer that runs under a critical section. (b) is _collectionsmodule.c dequeiter_len:2049 vs dequeiter_next_lock_held:1986, reproduced under TSan; its detail string says "do not compose".