Python free-threaded 构建中 C 扩展如何声明线程安全状态

Python 的 free-threaded 构建并不等于“把 GIL 关掉，C 扩展就自动线程安全”。从 Python 3.13 开始，CPython 支持禁用 GIL 的构建；但扩展必须显式声明自己支持这种构建，否则导入时可能重新启用 GIL。真正要检查的是三件事：构建是否带有 free-threading 能力、模块初始化采用哪种方式、原来由 GIL 掩盖的共享状态是否已经有自己的同步。

最小可行做法是：用 Py_GIL_DISABLED 判断 C 编译分支；多阶段初始化添加 Py_mod_gil，单阶段初始化在模块创建成功后调用 PyUnstable_Module_SetGIL()；然后逐项清理借用引用、PyDict_Next()、全局缓存和其他内部状态。

先确认构建能力，再声明模块支持

不要只用运行时的“当前 GIL 是否启用”来决定扩展是否兼容。C 代码里，free-threaded 构建会定义 Py_GIL_DISABLED；Python 侧可以用 sysconfig.get_config_var("Py_GIL_DISABLED") 判断构建能力，sys._is_gil_enabled() 则回答当前进程的 GIL 状态。

#include 

static int extension_build_supports_free_threading(void) {
#ifdef Py_GIL_DISABLED
    /* 这个分支表示头文件对应的构建支持 free-threading。 */
    return 1;
#else
    /* 普通构建未定义该宏，不代表扩展本身不能继续编译。 */
    return 0;
#endif
}

这只是编译目标判断，不是线程安全证明。Windows 从源码构建扩展时还要留意官方文档提到的宏定义限制；发布测试则应把普通解释器和 free-threaded 解释器分开跑。

多阶段初始化用 Py_mod_gil 明确表达

如果扩展使用 PyModuleDef_Slot 的多阶段初始化，应在模块定义的 slot 数组中加入 Py_mod_gil。兼容旧版 CPython 时，用 PY_VERSION_HEX 保护新 slot，避免旧头文件无法识别它。

static PyModuleDef_Slot module_slots[] = {
    /* 其他多阶段初始化 slot 放在这里。 */
#if PY_VERSION_HEX >= 0x030D0000
    /* 告诉 free-threaded 构建：本扩展不依赖 GIL。 */
    {Py_mod_gil, Py_MOD_GIL_NOT_USED},
#endif
    {0, NULL}
};

这里的声明只适用于你已经完成线程安全改造的扩展。若仍有未经保护的静态缓存，添加 slot 反而会把隐藏问题暴露给真正的并行执行，因此应把声明和并发测试作为同一次改动。

单阶段初始化用 PyUnstable_Module_SetGIL

仍使用 PyModule_Create() 的单阶段扩展，做法不同：先检查返回值，再在 Py_GIL_DISABLED 条件下调用 PyUnstable_Module_SetGIL(m, Py_MOD_GIL_NOT_USED)。该函数只在 free-threaded 构建中提供，宏保护不能省略。

static PyModuleDef moduledef = {
    PyModuleDef_HEAD_INIT,
    "sample_ext",
    "A small extension module.",
    -1,
    NULL
};

PyMODINIT_FUNC PyInit_sample_ext(void) {
    PyObject *m = PyModule_Create(&moduledef);
    if (m == NULL) {
        /* 创建失败时把 NULL 交给 CPython 处理。 */
        return NULL;
    }
#ifdef Py_GIL_DISABLED
    /* 仅在支持该 API 的构建中声明不使用 GIL。 */
    if (PyUnstable_Module_SetGIL(m, Py_MOD_GIL_NOT_USED) 

两种初始化方式不能混写成“看到宏就统一调用”。迁移时先确认模块定义方式，再选择 slot 或初始化函数中的声明点；这也便于为旧 Python 版本保留同一份源码。

把容器访问和扩展内部状态分开保护

free-threaded CPython 会为部分内置容器提供内部锁，但这不是扩展业务状态的通用锁。官方文档特别指出，PyDict_Next() 不会自动锁字典；如果字典可能被并发修改，应使用临界区。借用引用也要重新审视，例如可修改列表上的 PyList_GetItem() 应优先改为返回强引用的 PyList_GetItemRef()。

static int count_entries(PyObject *dict) {
    PyObject *key = NULL;
    PyObject *value = NULL;
    Py_ssize_t position = 0;
    int count = 0;

    /* PyDict_Next 不自行加锁，遍历期间保护可能变化的字典。 */
    Py_BEGIN_CRITICAL_SECTION(dict);
    while (PyDict_Next(dict, &position, &key, &value)) {
        count++;
    }
    Py_END_CRITICAL_SECTION();
    return count;
}

临界区适合围绕 Python 对象访问；扩展自己的缓存、全局状态或 C 结构体字段，则应使用扩展锁、原子操作或 thread_local。不要因为 PyList_Append() 有内部保护，就推断“追加后更新全局计数”也是原子的。

构建产物和兼容边界怎么落地

free-threaded 扩展需要针对该构建单独编译，相关 wheel、共享库和二进制使用 t 后缀，例如 Python 3.14 的 python3.14t。不要把普通构建的 wheel 当作 free-threaded wheel 复用。还要注意：当前 free-threaded 构建不支持 Limited C API 或 stable ABI，因此启用 py_limited_api=True 的 setuptools 配置需要按 Py_GIL_DISABLED 选择性关闭。

常见问题

声明了 Py_MOD_GIL_NOT_USED 就一定能并行加速吗？

不一定。声明只告诉解释器扩展不依赖 GIL，速度仍取决于工作负载、锁竞争、内存分配和是否真的存在可并行的 C 工作。

普通构建还能使用这份源码吗？

可以。用 PY_VERSION_HEX 和 Py_GIL_DISABLED 保护 free-threaded 专用 API，普通构建会跳过这些分支；但仍需分别编译和测试两套产物。

参考：Python support for free threading；C API Extension Support for Free Threading。