Python扩展(pybind11混编)

背景介绍
pybind11是一个基于C++11标准的模版库. 与Boost.Python类似, pybind11主要着眼于创建C++代码的Python封装, 并为其提供了一套轻量级的解决方案.

安装与代码示例
①. 安装C++编译器(各平台略有不同, 支持C++11标准即可)
②. 安装cmake工具(官网下载安装即可, 用于组织C++工程)
③. 安装Python解释器(官网下载安装即可)
④. 安装pybind11库
终端运行: pip3 install pybind11
⑤. 获取pybind11库相关目录
解释器内运行:

import pybind11

pybind11.get_cmake_dir()     # 获取cmake目录

pybind11.get_include()       # 获取include目录

⑥. 待封装之C++源码
本文以一个main.cpp源文件为例, 简要给出一个函数与一个类的封装示例, 代码如下,

#include <string>

#include <iostream>

#include <pybind11/pybind11.h>

#include <pybind11/eigen.h>

int MyFunc(int i, int j)

{

    return i + j;

}

class MyClass

{

public:

    MyClass(const std::string& msg) : msg_(msg) {}

    void printMsg()

    {

        std::cout << this->msg_ << std::endl;

    }

    Eigen::VectorXd add(const Eigen::VectorXd& lhs, const Eigen::VectorXd& rhs)

    {

        Eigen::VectorXd ret = lhs + rhs;

        return ret;

    }

    std::string msg_;

};

PYBIND11_MODULE(testlib, m)     // 此处设置模块名为testlib

{

    m.doc() = "This is a test library";

    m.def("MyFunc", &MyFunc, "my first function",

        pybind11::arg("i") = 1, pybind11::arg("j") = 2);

    pybind11::class_<MyClass>(m, "MyClass")

        .def(pybind11::init<const std::string&>())

        .def("printMsg", &MyClass::printMsg)

        .def("add", &MyClass::add, pybind11::arg("lhs"), pybind11::arg("rhs"))

        .def_readwrite("msg_", &MyClass::msg_);

}

其中, MyFunc是待导出函数, MyClass是待导出类. 注意, 上例含eigen库(C++)与numpy库(Python)之映射, 无eigen库的小伙伴可以注释相关内容.

cmake工程示例
配合上述main.cpp源文件, CMakeLists.txt文件内容如下,

cmake_minimum_required(VERSION 3.15)

set(CMAKE_BUILD_TYPE "Release")

set(CMAKE_CXX_STANDARD 11)

project(test_lib)

set(test_srcs

main.cpp

)

set(pybind11_DIR "/opt/homebrew/lib/python3.9/site-packages/pybind11/share/cmake/pybind11")   # 此处设置pybind11之cmake目录, 即: pybind11.get_cmake_dir()

find_package(pybind11 REQUIRED)

pybind11_add_module(testlib ${test_srcs})   # 此处设置模块名为testlib

target_include_directories(testlib PUBLIC "/Users/xxhbdk/MyLibs/eigen-3.4.0")   # 此处附加包含eigen库目录

当前工程结构如下,

编译及效果展示
终端运行如下命令编译Python动态库:
```
mkdir build      # 创建编译目录

cd build

cmake ..

make
```
运行完成后, 笔者build目录下生成了Python动态库文件"testlib.cpython-39-darwin.so". 随后即可在Python环境中使用之, 测试效果如下,

可以看到, 接口导出整体符合预期.
注意事项
①. C++源文件中模块名需要与cmake工程文件中模块名保持一致;
②. 本文着重阐述pybind11配合cmake之通用流程, 具体API使用细节, 请大家参考官方文档等资料.
参考文档
①. https://pybind11.readthedocs.io/en/stable/②. https://cmake.org/cmake/help/latest/

补充1(C++调用Python)
①. 待调用之Python源码
本文以一个my_func.py源文件为例, 简要给出一个函数示例, 代码如下,

def MyFunc(i, j):

    return i + j

②. 待编译之C++源码
本文以一个main.cpp源文件为例, 简要给出一个C++调用Python函数之示例, 代码如下,

#include <iostream>

#include <pybind11/embed.h>

int main()

{

    pybind11::scoped_interpreter guard;     // 初始化python解释器

    pybind11::module my_func = pybind11::module::import("my_func");

    int i = 11;

    int j = 22;

    pybind11::object ret = my_func.attr("MyFunc")(i, j);

    int n = ret.cast<int>();

    std::cout << i << " + " << j << " = " << n << std::endl;

}

③. cmake工程示例
配合上述main.cpp源文件, CMakeLists.txt文件内容如下,

cmake_minimum_required(VERSION 3.15)

set(CMAKE_BUILD_TYPE "Release")

set(CMAKE_CXX_STANDARD 11)

project(test_cppInvokePy)

set(test_srcs

main.cpp

)

add_executable(main ${test_srcs})

set(pybind11_DIR "/opt/homebrew/lib/python3.9/site-packages/pybind11/share/cmake/pybind11")   # 此处设置pybind11之cmake目录, 即: pybind11.get_cmake_dir()

find_package(pybind11 REQUIRED)

target_link_libraries(main PUBLIC pybind11::embed)

④. 编译及效果展示
当前工程结构如下,

终端运行如下命令编译C++可执行文件,

mkdir build      # 创建编译目录

cd build

cmake ..

make

运行完成后, 笔者build目录下生成了可执行文件"main". 随后将Python文件my_func.py拷贝至此build目录下.终端运行可执行文件main, 测试效果如下,

可以看到, 执行结果符合预期, Python模块调用成功.

补充1 - 参考文档
①. https://www.yuque.com/u461675/pcadi1/hf4fha#e82c4d4d
补充2(Global Interpreter Lock)
当执行流从Python侧进入C++侧时, GIL总是持有的. 因此, 如果C++侧代码长时间运行, 且不释放GIL, 则Python侧多线程可能无法达到预期的运行效果(如: UI运行阻塞等).
因此, 通过Python调用C++时, 若C++侧代码执行时间较长且具备Python侧多线程需求, 建议在C++代码入口处释放GIL.
释放GIL之方法①(功能代码执行处): pybind11::gil_scoped_release release;
释放GIL之方法②(模块接口定义处): pybind11::call_guard<pybind11::gil_scoped_release>();
补充2 - 注意事项
①. C++侧多线程不受GIL影响.
补充2 - 参考文档
①. https://pybind11.readthedocs.io/en/stable/advanced/misc.html#global-interpreter-lock-gil

巴特西

Python扩展(pybind11混编)

最新文章

热门文章