Pybind11 高级应用：在 C++ 中嵌入 Python 解释器

Pybind11 高级应用：在 C++ 中嵌入 Python 解释器

pybind11 Seamless operability between C++11 and Python 项目地址: https://gitcode.com/gh_mirrors/py/pybind11

引言

在 Python 与 C++ 的互操作领域，pybind11 主要被用于在 Python 中调用 C++ 代码。然而，pybind11 也提供了反向操作的能力：将 Python 解释器嵌入到 C++ 程序中。本文将深入探讨 pybind11 的嵌入功能，帮助开发者掌握在 C++ 应用中集成 Python 运行环境的技术要点。

基础环境搭建

要创建一个包含嵌入式 Python 解释器的 C++ 可执行程序，只需要简单的 CMake 配置和 pybind11 的嵌入目标：

cmake_minimum_required(VERSION 3.15...4.0)
project(example)

find_package(pybind11 REQUIRED)

add_executable(example main.cpp)
target_link_libraries(example PRIVATE pybind11::embed)

对应的 C++ 主程序结构如下：

#include <pybind11/embed.h>
namespace py = pybind11;

int main() {
    py::scoped_interpreter guard{}; // 启动并保持解释器运行
    
    py::print("Hello, World!"); // 使用 Python API
}

关键点说明：

• 使用任何 Python API 前必须先初始化解释器
• scoped_interpreter 采用 RAII 模式管理解释器生命周期
• 守卫对象销毁后，解释器将关闭并释放所有资源

执行 Python 代码的多种方式

直接执行 Python 字符串

py::exec(R"(
    kwargs = dict(name="World", number=42)
    message = "Hello, {name}! The answer is {number}".format(**kwargs)
    print(message)
)");

使用 pybind11 API

auto kwargs = py::dict("name"_a="World", "number"_a=42);
auto message = "Hello, {name}! The answer is {number}"_s.format(**kwargs);
py::print(message);

混合模式

auto locals = py::dict("name"_a="World", "number"_a=42);
py::exec(R"(
    message = "Hello, {name}! The answer is {number}".format(**locals())
)", py::globals(), locals);

auto message = locals["message"].cast<std::string>();
std::cout << message;

模块导入与管理

导入系统模块

py::module_ sys = py::module_::import("sys");
py::print(sys.attr("path"));

导入本地 Python 文件

假设有 calc.py 文件：

def add(i, j):
    return i + j

C++ 中调用方式：

py::module_ calc = py::module_::import("calc");
py::object result = calc.attr("add")(1, 2);
int n = result.cast<int>();
assert(n == 3);

模块重载

当源文件被外部进程修改后，可以重新加载模块：

module_::reload()

注意：此函数不会递归重载依赖模块。

创建嵌入式模块

使用 PYBIND11_EMBEDDED_MODULE 宏可以创建嵌入式二进制模块：

PYBIND11_EMBEDDED_MODULE(fast_calc, m) {
    m.def("add", [](int i, int j) {
        return i + j;
    });
}

int main() {
    py::scoped_interpreter guard{};
    auto fast_calc = py::module_::import("fast_calc");
    auto result = fast_calc.attr("add")(1, 2).cast<int>();
    assert(result == 3);
}

特点：

• 可以创建任意数量的嵌入式模块
• 模块会被添加到 Python 的内置模块列表中
• 可以与纯 Python 模块自然交互

解释器生命周期管理

关键注意事项：

• 解释器在 scoped_interpreter 销毁后关闭
• 可以重新初始化新的解释器实例
• 也可以使用 initialize_interpreter/finalize_interpreter 手动控制
• pybind11 模块可以安全地重新初始化
• 第三方扩展模块可能有内存释放问题

警告：

• 不要创建多个并发的 scoped_interpreter 守卫
• 不要重复调用 initialize_interpreter
• 不要直接使用 CPython 的 Py_Initialize 和 Py_Finalize

子解释器高级特性

Python 3.12+ 引入了具有独立 GIL 的子解释器，pybind11 通过 subinterpreter 类提供支持。

创建子解释器

py::subinterpreter sub = py::subinterpreter::create();

激活子解释器

{
    py::subinterpreter_scoped_activate guard(sub);
    // 在此作用域内子解释器处于活动状态
}

GIL 管理

gil_scoped_release 和 gil_scoped_acquire 会自动管理当前活动解释器的 GIL。

最佳实践

1. 不要在不同解释器间共享 Python 对象
2. 异常处理必须限定在激活作用域内
3. 避免全局/静态状态，使用解释器状态字典
4. 避免跨函数调用缓存 Python 对象
5. 注意多 GIL 环境下的死锁风险
6. Python 3.12 中子解释器必须在创建线程销毁

总结

pybind11 的嵌入功能为 C++ 应用程序提供了强大的 Python 集成能力。通过合理使用解释器管理、模块系统和子解释器等特性，开发者可以构建出既高效又灵活的混合语言应用。在实际开发中，应当特别注意资源管理和线程安全问题，遵循本文介绍的最佳实践，以确保系统的稳定性和可靠性。

pybind11 Seamless operability between C++11 and Python 项目地址: https://gitcode.com/gh_mirrors/py/pybind11