C++调用Python回调时pybind11的GIL处理方法

核心结论 #

pybind11 不会自动处理C侧创建线程中触发Python回调的GIL管理逻辑——它无法感知C++内部的线程调度、异步触发逻辑，所有跨线程调用Python代码的场景，都需要开发者手动保证GIL的正确获取与释放。
你提到的手动调用PyGILState_Ensure()/PyGILState_Release()的逻辑，pybind11已经提供了现成的RAII封装，不需要直接调用Python C API的底层接口。

具体实现规则 #

1. 不要误用py::call_guard #

py::call_guard<py::gil_scoped_acquire>()仅对Python侧直接调用的C++绑定接口生效：它只会在Python代码调用你通过.def()注册的函数的瞬间自动获取GIL，函数返回后立刻释放。
这个机制完全无法覆盖你遇到的场景：当subscribe_mode把回调存起来、后续在C侧创建的工作线程中异步触发时，call_guard的作用域早就结束，GIL已经被释放，此时直接调用Python回调必然触发未定义行为（通常是直接崩溃、解释器死锁）。

2. 通用正确写法：回调触发时自动获取GIL #

pybind11内置的py::gil_scoped_acquire类就是对PyGILState_Ensure()/PyGILState_Release()的完整封装：构造时自动调用PyGILState_Ensure()完成线程注册、GIL获取，析构时自动调用PyGILState_Release()释放GIL，哪怕回调抛异常也能正确释放，不会造成GIL死锁。
针对你给出的订阅接口，只需要在绑定的时候加一层包装，把传入的Python回调封装成带GIL保证的C++可调用对象即可：

py::class_<SomeApi> some_api(m, "SomeApi"); 
some_api
    .def(py::init<>())
    .def("mode", [](SomeApi& api, py::function cb) {
        // 按值捕获Python回调，自动维护引用计数
        api.subscribe_mode([cb](Mode mode) {
            // 调用Python代码前栈上创建gil对象，自动获取GIL
            py::gil_scoped_acquire gil;
            // 安全调用Python回调
            cb(mode);
            // 离开作用域时gil对象析构，自动释放GIL
        });
    }, "Subscribe to 'mode' updates.");

这个写法是兼容性最高的方案，不管回调是第三方库内部线程触发、还是你自己创建的线程触发，都能正常工作，不需要修改C++侧的原有逻辑。

3. 长驻线程的优化写法 #

如果你能完全控制C侧工作线程的入口逻辑（比如线程是你自己写的、不是第三方库内部创建的黑盒线程），也可以选择在线程启动时一次性获取GIL，线程退出时自动释放，不需要每次回调触发都重复获取释放，性能会略高一点。
但这个方案有明显限制：

• 你必须能拿到线程的入口函数执行权限，第三方库私有线程无法使用
• 线程持有GIL期间不能做长时间的阻塞计算/IO操作，否则会阻塞整个Python进程的所有线程
• 如果线程逻辑里会调用回可能获取GIL的Python/C接口，很容易出现死锁
  除非你对线程的执行逻辑完全可控，否则优先使用前面的回调处获取GIL的写法，更稳妥。

常见注意事项 #

• 任何对py::object/py::function等pybind11包装的Python对象的操作，都必须在持有GIL的状态下执行，包括对象的析构——如果你把py::function存在全局结构里，销毁的时候也要保证持有GIL。
• 如果持有GIL期间需要执行耗时的C++阻塞操作，可以在作用域内再创建一个py::gil_scoped_release对象临时释放GIL，等阻塞操作完成后再继续持有GIL执行后续Python相关逻辑，避免长时间阻塞Python解释器。
• 不要手动调用底层PyGILState_Ensure()/PyGILState_Release()，用pybind11提供的RAII类可以避免异常分支、early return场景下的GIL泄漏问题。

内容的提问来源于stack exchange，提问作者JonasVautherin