Bug description:

On free-threaded builds, the interpreter can deadlock when Python code running under an unpinned TYPE_LOCK stops the world, directly or through an automatic GC, while another thread holds TYPE_LOCK pinned and waits to stop the world. The callbacks are a metaclass mro() (from type_ready()) and a str-subclass class-dict key's __eq__ (from type_setattro()).

Observed on fresh free-threaded builds of main a000129 (which includes PR #152826), main 8c056c3 and 3.15 13b1659 (macOS arm64, Clang, 2026-09-25), and earlier on main 6757482, 3.15 2dafe2a and 3.14 1d8c9f8. The default build is not affected.

This is the same lock-order family as gh-158194 (PyType_Freeze()), gh-156910 and gh-155400, but a distinct bug. Those were fixed by pinning at C call sites, which cannot cover arbitrary Python code or the GC. The broader approach below might also cover gh-158194; gh-158194's pin does not fix this.

Reproducer (main, 3.15 and 3.14.4+)

Trimmed from the attached repro.py (mro bug):

import faulthandler, sys, threading, time
print("sys._is_gil_enabled() =", sys._is_gil_enabled())
if sys._is_gil_enabled() is not False:
    sys.exit("needs a free-threaded build with the GIL disabled")
faulthandler.dump_traceback_later(20, exit=True)   # dump stacks and exit if hung

def f(): pass

class Meta(type):
    def mro(cls):             # called by type_ready() with TYPE_LOCK held, not pinned
        f.__qualname__ = "f"  # stops the world (func_set_qualname)
        return type.mro(cls)

stop, errors = threading.Event(), []

def guarded(fn):
    def run():
        try: fn()
        except BaseException as e: errors.append(e); raise
    return run

def setter():
    while not stop.is_set():
        Meta("K", (), {})

def pinner():                 # type_set_bases(): pinned TYPE_LOCK, then stop-the-world
    class A: pass
    class B: pass
    class X(A): pass
    while not stop.is_set():
        X.__bases__ = (B,); X.__bases__ = (A,)

def contender():              # plain stop-the-world; keeps stw->mutex contended
    def g(): pass
    while not stop.is_set():
        g.__qualname__ = "g"

ts = [threading.Thread(target=guarded(fn)) for fn in (setter, pinner, contender) for _ in range(2)]
for t in ts: t.start()
time.sleep(5); stop.set()
for t in ts: t.join()
if errors: sys.exit(f"FAIL: {errors[0]!r}")
print("done")

• Actual: the process hangs. faulthandler dumps the stacks after 20 s and exits with status 1.
• Expected: done after about 5 s.

repro_realistic.py (ABC subclasses + functools.wraps + GC) and repro_dunder_pinner.py hang on main and 3.15 only: 3.14 (from 3.14.4, which backported type_lock_prevent_release()) pins only the __bases__/MRO path.

Native stacks of a hang

Stock main 8c056c3 (free-threaded debug, no patch), repro.py mro bug, captured with macOS sample (trimmed):

setter   type_ready_publish typeobject.c:9513 -> mro_internal typeobject.c:3641 -> [Python mro()]
         -> func_set_qualname funcobject.c:755 -> stop_the_world pystate.c:2475 -> _PyMutex_LockTimed
         -> _PyThreadState_Attach pystate.c:2305 -> _PyCriticalSection_Resume critical_section.c:152
         -> _PyMutex_LockTimed
pinner   type_set_bases typeobject.c:2002 -> stop_the_world pystate.c:2475 -> _PyMutex_LockTimed

These stacks are consistent with the lock-cycle diagnosis below; lock ownership is inferred from the code paths, not read from the samples.

Mechanism

1. T1's callback under unpinned TYPE_LOCK stops the world and parks on a busy stw->mutex. Parking detaches T1, which releases TYPE_LOCK.
2. T2 takes TYPE_LOCK pinned (e.g. __bases__ assignment) and parks on stw->mutex.
3. stw->mutex is handed to T1, whose re-attach (_PyCriticalSection_Resume()) waits for TYPE_LOCK: ABBA.

A proposed approach, for specialist review

fix-{main,3.15,3.14}.diff change Python/pystate.c so that stop_the_world() never waits for a critical-section mutex while owning the stop-the-world locks: if the critical section cannot be resumed without blocking, it drops stw->mutex and the rwmutex, waits, and retries. Regression-tested candidate fix. Broader attachment, finalization, progress, and interaction concerns remain for specialist review:

• Re-attaching with tstate->critical_section temporarily set to 0 around _PyThreadState_Attach(): every attachment outcome, including shutdown/finalization and free-threaded builds running with the GIL enabled.
• Nested and two-mutex critical sections; pinned sections. Only the topmost critical section is restored, which matches what _PyCriticalSection_Resume() already does.
• Global vs per-interpreter stop-the-world; progress under contention.
• PR gh-151518: Avoid STW starvation of attaching threads #152826 (Free-threaded CPython can starve a thread reattaching during repeated stop-the-world GC #151518), merged on 2026-09-25, changes attach and the stop-the-world state machine. The bug still reproduces on main a000129, which includes it: repro.py mro bug hung 5/5 there with the same stack shape (stop_the_world now at pystate.c:2523). fix-main.diff applies cleanly to a000129 and completed 5/5, but the two changes still need review together; applying cleanly does not establish that they are compatible.
• Maintainability: the try-resume could move into the critical-section implementation instead of duplicating its private representation in pystate.c.

Performance impact has not been measured. No failure was observed on the patched build tested (main 8c056c3 debug, exactly fix-main.diff): each configuration that hung on stock main debug ran 0/5 or 0/3 hung, and both regression tests passed 3/3.

Fresh out-of-tree free-threaded builds of main 8c056c3 (stock, and with exactly the attached fix-main.diff, sha256 844eee86…) and 3.15 13b1659 (stock), run one at a time on 2026-09-25. A run counts as hung only when the process stopped using CPU and a native sample showed stacks consistent with the lock cycle above.

mro bug also hung on stock main release (5/5) and stock 3.15 debug (3/3). On main a000129 (after PR #152826, debug), repro.py mro bug hung 5/5 stock and completed 5/5 with fix-main.diff; a native sample of one stock hang had the same shape as above. test_free_threading, test_types and test_descr pass when patched. Not built: patched main release, patched 3.15 and 3.14 (fix-3.15.diff, fix-3.14.diff).

python -VV of the fresh stock builds:

Python 3.16.0a0 free-threading build (heads/val/main-base-dirty:8c056c3, Sep 25 2026, 08:58:37) [Clang 21.0.0 (clang-2100.3.34.2)]
Python 3.15.0rc2+dev free-threading build (heads/val/315-base-dirty:13b1659, Sep 25 2026, 09:07:27) [Clang 21.0.0 (clang-2100.3.34.2)]

Earlier stock builds (used for the older results below):

Python 3.16.0a0 free-threading build (heads/main-dirty:6757482, Sep 22 2026, 20:29:11) [Clang 21.0.0 (clang-2100.3.34.2)]
Python 3.15.0rc2+dev free-threading build (heads/3.15-dirty:2dafe2a, Sep 22 2026, 21:35:07) [Clang 21.0.0 (clang-2100.3.34.2)]
Python 3.14.7+ free-threading build (heads/3.14-dirty:1d8c9f8, Sep 22 2026, 20:25:42) [Clang 21.0.0 (clang-2100.3.34.2)]

The -dirty suffix comes from CPython's Makefile running git describe --dirty from the out-of-tree build directory, where git sees every tracked file as missing. All of these builds were made out-of-tree, and their source trees show no tracked changes; the fresh trees were verified clean after each build.

Attached files. Each reproducer prints sys._is_gil_enabled() and exits with status 2 unless it is False. A worker exception exits with status 3.

• repro.py [mro|strkey] [bug|gc|ctl] [secs]: bug stops the world directly inside the callback, gc only allocates cycles (the automatic GC stops the world), and ctl is the control (no stop-the-world, GC disabled).
• repro_dunder_pinner.py: the same, with X.__repr__ assignment as the pinned partner (main and 3.15).
• repro_realistic.py [gc|bug]: ABC subclass creation plus functools.wraps plus GC (main and 3.15).
• test_type_stw_deadlock.py: a standalone copy of the two regression tests in the diffs.

Older stock-build results. These are stock builds (no patch) of main @ 6757482, 3.15 @ 2dafe2a and 3.14 @ 1d8c9f8, run on 2026-09-25 with the reproducers as they were before the GIL check and the exception propagation were added (the stress logic is the same). CPU-time inactivity was used only to screen for a hang. A native sample was taken of the first hang in each cell; those samples had the same shape as the stacks above (with stop_the_world at pystate.c:2454 on 6757482).

Control: repro.py mro ctl completed on main release. The standalone regression tests hung on stock main release. In the earlier investigation (2026-09-23, same stock commits), the gc modes of repro.py hung on all three branches, and repro_dunder_pinner.py hung on main and 3.15.

Earlier investigation (2026-09-23; stock main 6757482 / 3.15 2dafe2a / 3.14 1d8c9f8; earlier revision of the patch). Most of these patched builds were made before the attached diffs were finalized, so the exact source they were built from may differ.

• All reproducer configurations that hang on stock builds completed on patched main debug and release, 3.15 debug and 3.14 debug.
• The two new tests passed in 2.4–5.6 s.
• test_free_threading, test_threading, test_gc, test_descr, test_capi and related suites passed on the patched debug builds.
• After the diffs were finalized, patched main release was re-run: 2/2 repro.py mro bug and 3/3 regression-test runs completed.

Code locations.

The unpinned sites are unchanged at the current tips (checked 2026-09-25). stop_the_world() was reworked by PR #152826, but the hang remains on main after it. On 3.14, v3.14.3 has no type_lock_prevent_release() and v3.14.4 does (the backport of gh-145685). This is the same hand-off-after-detach hazard described in gh-144513.

How the patch works. A new stw_lock() replaces the direct PyMutex_Lock(&stw->mutex). If the thread has a resumable critical section and the fast path fails, it:

1. detaches, which suspends its critical sections;
2. takes stw->mutex without detaching;
3. re-attaches without resuming;
4. tries to resume the critical section with PyMutex_LockFast;
5. on failure, releases stw->mutex and the rwmutex, blocks in _PyCriticalSection_Resume() while owning nothing, and retries.

A mutex pinned by type_lock_prevent_release() is not stored in the critical section, so pinned holders take the unchanged path. The rwmutex is released too, because holding it while waiting for TYPE_LOCK could still deadlock against a pending global stop-the-world such as os.fork().

Alternatives considered:

• Call mro() outside TYPE_LOCK. This is incomplete: the str-key path and GC inside such code remain.
• Never run Python code under TYPE_LOCK. This would be a large restructuring.
• Disable hand-off for stw->mutex. This is not enough, because a consumed wake-up can still hang.
• Pin at the callback sites. This is not possible across arbitrary Python code.

As noted above, the try-resume helpers could instead live in critical_section.c, for example as _PyCriticalSection_TryResume(), so that pystate.c does not depend on the critical section's private representation.

Open questions and gaps.

• Starvation on the retry path is not ruled out.
• Linux, Windows, subinterpreters and a real os.fork() racing this path were not tested.
• How often real programs combine a Python-level mro() or a str-subclass class-dict key with a concurrent pinned type update is unknown.
• 3.15.0 final is expected on 2026-10-01 (PEP 790). Deadlock caused by type_lock_prevent_release() #155400, from the same family, was marked release blocker. I leave any priority decision to the release manager.

How it was found

An audit of stop_the_world() callers for locks that are held across the wait.

CPython versions tested on:

3.14, 3.15, CPython main branch

Operating systems tested on:

macOS

Attachments

repro.py.txt
repro_dunder_pinner.py.txt
repro_realistic.py.txt
test_type_stw_deadlock.py.txt
fix-main.diff.txt
fix-3.15.diff.txt
fix-3.14.diff.txt

Linked PRs

• gh-158195: Defer critical section restoration after STW #158678
• gh-158195: Do not hold the type lock during stop-the-world #159972