Python 3.14 自由线程程序怎样显式保护共享状态

Python 3.14 的自由线程构建允许多个线程真正并行执行 Python 代码，但这不等于共享状态会自动保持业务一致。最稳妥的做法是：先确认解释器状态，再把一次完整的读改写操作放进 threading.Lock，最后用压力测试验证边界。不要把“内置类型当前有内部锁”当成业务同步协议。

官方文档：https://docs.python.org/3.14/

先确认当前解释器是否真的关闭 GIL

CPython 从 3.13 开始提供自由线程构建，3.14 仍然可以在运行时重新启用 GIL。应用启动时至少记录构建标识和当前状态，避免把普通构建上的偶然结果误认为自由线程安全。

import sys
import sysconfig

# 先判断构建是否支持自由线程，再判断本次进程是否启用了 GIL。
free_threaded_build = sysconfig.get_config_var("Py_GIL_DISABLED") == 1
gil_enabled = sys._is_gil_enabled() if hasattr(sys, "_is_gil_enabled") else True

print({
    "free_threaded_build": free_threaded_build,
    "gil_enabled": gil_enabled,
    "version": sys.version.split()[0],
})

构建支持不代表 GIL 当前一定关闭；不兼容的 C 扩展导入后也可能让 GIL 重新启用。这个检查适合写入启动日志和测试报告，不适合代替同步设计。

把共享不变量和锁放在同一个临界区

真正需要保护的不是某个字典方法，而是“读取旧值、计算新值、写回结果”这一整个不变量。下面的计数器即使在自由线程模式下也不依赖字典内部锁，异常时由 with 自动释放锁。

import threading

state = {"processed": 0}
state_lock = threading.Lock()

def add_processed(amount: int = 1) -> int:
    # 读改写必须在同一个临界区，避免两个线程覆盖彼此的结果。
    with state_lock:
        state["processed"] += amount
        # 返回值也在锁内读取，保证它和本次写回属于同一个状态快照。
        return state["processed"]

def worker(rounds: int) -> None:
    for _ in range(rounds):
        add_processed()

threads = [threading.Thread(target=worker, args=(10_000,)) for _ in range(4)]
for thread in threads:
    thread.start()
for thread in threads:
    thread.join()  # 中文注释：主线程等待所有更新完成后再读取最终结果。

print(state["processed"])

如果共享对象由多个字段组成，例如余额和版本号，就把两者的更新放进同一临界区；不要分别加锁后让读者看到半更新状态。只读配置可以在启动后冻结，线程私有的临时变量则可放入 threading.local()，从源头减少竞争。

第三方扩展和共享对象要单独排查

自由线程不会把所有对象都变成可并发对象。Python 文档明确建议优先使用显式同步原语；同一个迭代器被多个线程同时访问，可能出现重复或遗漏。执行中的线程 frame 的 f_locals 也不能跨线程随意读取。涉及 C 扩展时，还要看扩展是否明确声明支持禁用 GIL 的构建；否则导入可能触发 GIL 回退。

用回退开关和压力测试确认迁移结果

线上迁移可以保留 PYTHON_GIL=1 或 -X gil 作为临时回退，但回退只改变运行模式，不能修复本来就缺少同步的代码。测试时同时覆盖自由线程和默认构建，观察计数是否稳定、锁是否在异常路径释放、第三方依赖是否改变 GIL 状态。

还要接受自由线程构建的现实代价：官方文档指出它通常有更高的单线程开销和内存占用。只有在 CPU 并行收益、依赖兼容性和锁竞争都能接受时，才适合扩大灰度。

常见问题

自由线程模式下 dict 的单次读取还安全吗？

CPython 当前会用内部同步保护部分内置类型操作，但这不代表多个操作组成的业务逻辑自动安全；读改写仍应使用显式锁。

设置了自由线程构建，为什么运行时仍有 GIL？

可能是通过 PYTHON_GIL 或 -X gil 启用了 GIL，也可能是导入的扩展尚未声明自由线程兼容。用 sys._is_gil_enabled() 和启动日志确认。

锁会不会让自由线程失去意义？

只会限制受保护的共享临界区；把不可变数据、线程本地数据和独立任务移出临界区，仍可让不同线程并行执行主要工作。