Python：Py_mod_gil 槽位是什么：C 扩展声明"我线程安全"的正式方式

一、引子：一个槽位背后的十年博弈

2024 年 10 月，CPython 3.13 正式发布，其中最受争议也最受期待的特性，是官方首次提供"自由线程"（free-threaded）构建版本，也就是社区俗称的"无 GIL 版 Python"。与这个构建一同进入公众视野的，还有一个此前鲜为人知的 C API 概念——Py_mod_gil 槽位。

如果你写过 C 扩展，可能熟悉 PyModuleDef 结构体里的 m_slots 数组。过去这个数组里常见的是 Py_mod_exec、Py_mod_multiple_interpreters 等槽位。3.13 新增的 Py_mod_gil 槽位，允许扩展在模块初始化时明确告诉解释器："我这个模块在无 GIL 环境下是线程安全的。"

听起来只是加了一个枚举值，但笔者认为，它的意义远超一个 API 增量。它把"线程安全"从扩展作者的口头承诺，变成了一个可被运行时读取、可被工具审计、可被生态追踪的正式契约。这是 Python 生态在并发治理上的一次范式转变——从"默认信任"走向"显式声明"。

本文的主线就是"声明即契约"：一个槽位如何把模糊的工程承诺，转化为机器可验证的接口约定，并由此牵动整个 C 扩展生态的迁移节奏。

在展开细节之前，先给出一个最小可运行的代码印象，让读者对 Py_mod_gil 的用法有直观认知：

#include <Python.h>

static struct PyModuleDef mymodule = {
    PyModuleDef_HEAD_INIT,
    .m_name = "mymodule",
    .m_doc = "A free-threading-ready extension.",
    .m_size = -1,
    .m_slots = (PyModuleDef_Slot[]){
        {Py_mod_gil, Py_MOD_GIL_NOT_USED},   /* 关键声明 */
        {0, NULL}
    },
};

PyMODINIT_FUNC PyInit_mymodule(void) {
    return PyModuleDef_Init(&mymodule);
}

这一行 {Py_mod_gil, Py_MOD_GIL_NOT_USED} 就是全文的核心。它告诉解释器：本模块不依赖 GIL 保护其内部状态。下文将逐层拆解它为何存在、如何生效、以及如何正确使用。

二、GIL 的历史成因与代价

2.1 GIL 是什么，为什么存在

全局解释器锁（Global Interpreter Lock，GIL）是 CPython 中一把保护解释器内部状态的互斥锁。任意时刻，只有一个线程能持有 GIL 并执行 Python 字节码。它的存在并非语言规范要求，而是 CPython 实现层面的历史选择。

其成因主要有三：其一，CPython 的引用计数机制需要原子性保护，若无 GIL，每次 Py_INCREF/Py_DECREF 都需加锁，开销巨大；其二，早期单核时代，多线程并行的收益有限，GIL 简化了实现；其三，大量 C 扩展默认在 GIL 保护下编写，隐式依赖这一假设。

本文评述：GIL 本质上是一份"全局默认契约"——所有扩展都被默认为非线程安全，由解释器统一兜底。这份契约降低了扩展开发门槛，却把并发成本转嫁给了整个运行时。

2.2 多核时代的代价

随着多核 CPU 普及，GIL 的代价愈发明显。计算密集型任务无法通过多线程获得真正的并行加速，只能退而求其次使用多进程（multiprocessing），带来进程间通信、内存复制、启动开销等一系列问题。

表中"free-threaded"一行的数据为机制性描述，非具体基准测试结果；实际加速比高度依赖工作负载、扩展生态成熟度与 CPython 版本，读者应以官方基准（如 pyperformance）为准。

2.3 历史上的多次尝试

移除 GIL 并非新话题。早在 1999 年，Greg Stein 就提交过"free-threading"补丁；此后 Larry Hastings 的 Gilectomy 项目（2016 年前后）也尝试过系统性地移除 GIL。这些尝试大多因单线程性能回退过大、C 扩展兼容性难以维持而未能进入主线。

本文评述：历史上失败的根因，不是技术不可行，而是缺少一份"扩展如何声明自己线程安全"的正式协议。没有这份协议，解释器无法安全地放开 GIL，只能继续全局兜底。PEP 703 的突破，正在于补上了这块拼图。

三、PEP 703：自由线程的工程权衡

3.1 PEP 703 的核心主张

PEP 703（Making the Global Interpreter Lock Optional in CPython）由 Sam Gross 主导提出，核心主张是：让 GIL 成为可选项，通过构建时开关启用"无 GIL"解释器，同时引入一系列机制保证内存安全与扩展兼容性。

其关键技术手段包括：偏置引用计数（biased reference counting）、延迟引用计数（deferred reference counting）、对象级锁（per-object locks）、以及针对容器的线程安全优化。这些机制共同替代了 GIL 的全局保护职责。

3.2 兼容性优先的设计哲学

PEP 703 最务实的一点，是承认"生态不可能一夜迁移"。因此它设计了渐进式路径：默认构建仍带 GIL；自由线程构建为实验特性；扩展可逐步声明线程安全。而 Py_mod_gil 槽位，正是这条渐进路径上的关键闸门。

本文评述：PEP 703 的工程智慧在于"用声明换兼容"。它不强制所有扩展立即线程安全，而是允许扩展按自身节奏声明，解释器据此决定是否启用 GIL 兜底。

3.3 三个构建变体的关系

从 3.13 起，CPython 实际存在三类构建形态，理解它们的差异是理解 Py_mod_gil 行为的前提：

可见，Py_mod_gil 只在自由线程构建且未强制启用 GIL 时才有实际意义。这也是为什么很多开发者在默认构建下测试时"看不到效果"。

四、Py_mod_gil 槽位的 ABI 语义

4.1 槽位机制回顾

PyModuleDef_Slot 是 CPython 多阶段初始化（multi-phase initialization）的一部分。每个槽位是一个 {slot_id, value} 对，解释器在模块初始化时按顺序读取并执行相应逻辑。

相比单阶段初始化（直接返回 module 对象），多阶段初始化允许解释器在创建模块对象前后插入钩子，从而支持子解释器、模块重载等高级场景。Py_mod_gil 正是借助这一机制，在初始化阶段向解释器传递线程安全声明。

4.2 Py_mod_gil 的取值与含义

该槽位目前有两个语义取值：

• Py_MOD_GIL_USED：默认值。表示扩展依赖 GIL，未声明线程安全。
• Py_MOD_GIL_NOT_USED：表示扩展不依赖 GIL，可在无 GIL 环境下运行。

注意：未提供该槽位等价于 Py_MOD_GIL_USED。这是"默认保守"原则的体现——不声明即视为不安全，解释器会为它重新启用 GIL。

4.3 与 Py_mod_multiple_interpreters 的对照

3.12 引入的 Py_mod_multiple_interpreters 槽位与 Py_mod_gil 在设计哲学上一脉相承：都是让扩展显式声明自己在某种隔离/并发模型下的安全性。前者针对子解释器隔离，后者针对无 GIL 并发。

本文评述：这两个槽位共同构成 CPython 的"能力声明体系"雏形。笔者认为，未来可能出现更多此类槽位（如针对特定内存模型、异步安全的声明），扩展作者需要习惯"显式声明能力"这一新范式。

五、声明即契约：运行时行为全景

5.1 声明 Py_MOD_GIL_NOT_USED 后发生什么

在自由线程构建下，若某扩展声明 Py_MOD_GIL_NOT_USED，解释器在导入该模块时不会为其重新启用 GIL。这意味着该模块的代码将在真正的无 GIL 环境下执行，多个线程可同时进入其 C 函数。

反之，若扩展未声明或声明 Py_MOD_GIL_USED，解释器会在导入时重新启用 GIL，并通常发出警告。这保证了旧扩展在自由线程构建下仍能"安全但降级"地运行。

5.2 警告机制与可观测性

CPython 在导入未声明线程安全的扩展时，会通过 RuntimeWarning 提示。开发者可通过环境变量或命令行选项调整警告行为，便于在 CI 中批量筛查不兼容扩展。

# 在自由线程构建下运行，观察警告
python3.13t -X gil=0 -W error::RuntimeWarning your_script.py

# 强制启用 GIL（用于对比）
PYTHON_GIL=1 python3.13t your_script.py

本文评述：把警告提升为 error 是 CI 中筛查扩展兼容性的高效手段。它把"是否声明"这一隐性事实，转化为可失败、可追踪的构建信号，这正是"契约"落地为工程实践的关键一步。

5.3 契约的边界：声明不等于正确

必须强调：Py_MOD_GIL_NOT_USED 是扩展作者的自我声明，解释器无法验证其真实性。如果扩展实际存在数据竞争却错误声明，后果是难以复现的内存错误或崩溃。

本文评述：契约的价值取决于履约的严肃性。Py_mod_gil 把责任交还给扩展作者，这既是赋权，也是风险。因此配套的测试与工具链（如 ThreadSanitizer、压力测试）不可或缺。

六、工程实践：迁移与验证步骤

6.1 迁移前的评估清单

在为一个 C 扩展添加 Py_mod_gil 声明前，建议先完成以下评估：

1. 扩展是否持有可变全局状态（全局变量、静态缓存）？
2. 是否使用了非线程安全的 C 库（如某些旧版解析库）？
3. 是否依赖 GIL 提供的隐式原子性（如引用计数操作）？
4. 是否在 C 代码中释放过 GIL（Py_BEGIN_ALLOW_THREADS）并访问共享数据？
5. 是否使用了 CPython 内部非公开 API？

6.2 分步迁移路径

基于上述评估，推荐如下分步路径：

6.3 用 ThreadSanitizer 验证

ThreadSanitizer（TSan）是检测数据竞争的利器。将扩展与 CPython 一起用 TSan 编译并运行测试，可发现潜在的竞态。以下为示意性编译流程（具体参数随平台而异）：

# 示意：以 TSan 编译扩展（简化，非完整命令）
CFLAGS="-fsanitize=thread -g -O1" \
LDFLAGS="-fsanitize=thread" \
python3.13t setup.py build_ext --inplace

# 运行多线程压测
TSAN_OPTIONS="halt_on_error=0" python3.13t -X gil=0 stress_test.py

本文评述：TSan 报告需要人工甄别，因为 CPython 内部本身存在大量有意的"良性竞争"。建议聚焦扩展自有代码路径，并结合官方文档对已知误报的说明进行过滤。

6.4 常见陷阱与规避

• 误用全局缓存：用 PyThread_tss_* 或对象属性替代。
• 假设引用计数原子：无 GIL 下需使用 CPython 提供的原子引用计数 API。
• 忘记保护惰性初始化：双重检查锁定需配合正确的内存序。
• 依赖第三方非线程安全库：需自行加锁或寻找替代。

七、性能与生态实测数据

7.1 官方基准的启示

CPython 团队在 PEP 703 及相关文档中给出了自由线程构建的性能数据。总体结论是：单线程性能存在一定回退，多线程计算密集场景可获得显著加速。具体数值随版本迭代持续改善，读者应以对应版本的官方基准为准。

下表为基于公开资料整理的定性对比（非精确测量，仅供理解趋势）：

本文评述：自由线程不是"免费午餐"，而是"用单线程开销换多线程并行"的交易。是否值得，取决于工作负载的并行度与扩展生态的成熟度。

7.2 生态现状扫描

截至 3.13 发布后的一段时间，主流科学计算与 Web 框架生态对自由线程的支持仍在推进中。NumPy、Cython 等项目已陆续开展兼容性工作，但完整覆盖仍需时间。

本文评述：生态迁移的瓶颈往往不在 CPython 核心，而在长尾 C 扩展。Py_mod_gil 的警告机制恰好为这些长尾扩展提供了"被看见"的通道，这是推动迁移的隐性杠杆。

7.3 一个可复现的微基准思路

读者可自行构造微基准：编写一个计算密集的 C 扩展函数，分别在默认构建与自由线程构建下用多线程调用，记录墙钟时间。注意固定 CPU 亲和性、关闭频率调节，并多次取中位数，以降低噪声。

八、前沿研判与风险清单

8.1 三条演进主线

笔者认为，围绕 Py_mod_gil 及自由线程，未来将沿三条主线演进：

1. 声明体系扩展：更多能力声明槽位出现，形成"扩展能力清单"。
2. 工具链成熟：静态分析、运行时检测、CI 集成逐步标准化。
3. 生态分层：核心扩展率先迁移，长尾扩展通过兼容层过渡。

8.2 风险清单

8.3 给扩展作者的建议

短期看，建议所有维护中的 C 扩展至少完成"可观测"阶段——在自由线程构建下运行测试并收集警告。中期看，应把线程安全纳入代码审查清单。长期看，显式声明能力将成为扩展质量的基本门槛。

九、结语

Py_mod_gil 槽位看似微小，却承载着 Python 并发治理的一次范式转变。它把"线程安全"从隐性假设变为显式契约，让解释器、扩展作者与工具链之间有了可协商的接口。

本文评述：理解 Py_mod_gil，本质上是理解"声明即契约"这一工程哲学。它提醒我们，真正的并发安全不来自某个开关，而来自清晰的责任边界与可验证的承诺。对于每一位 C 扩展作者，这既是挑战，也是提升工程质量的历史机遇。

主要参考文献