前情提要
在之前的文章Python调用C++之PYBIND11简介中我们介绍了pybind11的基本用法,我们已经知其然,接下来我们通过代码分析,知其所以然。通过之前的讲解,我们知道使用pybind11去导出C++接口到Python,只要使用一个宏PYBIND11_MODULE
,例如之前的例子,将已有的C++函数int add(int, int)
导出到Python:
#include "existence.h"
#include <pybind11/pybind11.h>
PYBIND11_MODULE(example, m) {
m.doc() = "pybind11 example plugin"; // optional module docstring
m.def("add", &add, "A function which adds two numbers");
}
我们知道,用传统方法编写C++扩展模块的方法主要有以下几步,对于Python2和Python3,方法略有不同:
Python2
- 拥有一个需要导出到Python的C++接口;
- 将这个C++接口用一个
PyMethodDef
结构体封装起来,构成一个方法表,如果使用PyModule_AddObject
这一步是不需要的;如果将PyModuleDef
比作车头,PyMethodDef
比作车厢,两种方法的区别就相当于是PyModule_AddObject()
先把车厢挂在车头上在网上装货物,而手动封装PyMethodDef`就是先装了货物在将车头链接上; - 调用
Py_InitModule(name, PyMethodDef**)
得到一个模块对象,假设叫做m
; - 调用
PyModule_AddObject(m, name, PyObject*)
将函数添加到模块;或者调用Py_InitModule
去装载第二步中封装的方法表; - 给出一个按一定规则命名的函数供Python解析器加在该模块的时候调用,这个函数名的命名规则是
特定前缀 + 模块名
。Python 2的是init
。例如,initexample
,其中example
是模块名。作用是调用第四步中的两个函数之一去盘活整个创建过程。
Python3
- 拥有一个需要导出到Python的C++接口;
- 将这个C++接口用一个
PyMethodDef
结构体封装起来,构成一个方法表,如果使用PyModule_AddObject()
这一步是不需要的。如果将PyModuleDef
比作车头,PyMethodDef
比作车厢,两种方法的区别就相当于是PyModule_AddObject()
先把车厢挂在车头上在网上装货物,而手动封装PyMethodDef`就是先装了货物在将车头链接上; - 将第二步方法表使用
PyModuleDef
结构体封装; - 根据
PyModuleDef
种的内容初始化模块,调用PyModule_Create(PyModuleDef*)
函数创建模块; - 给出一个按一定规则命名的函数供Python解析器加在该模块的时候调用,这个函数名的命名规则是
特定前缀 + 模块名
。Python 3 的特定前缀是PyInit_
。例如,PyInit_example
,其中example
是模块名。
总结就是,一个表示模块的对象,一个表,表的每一行用来表示模块拥有的一个方法对象,在模块初始化的时候,解析器找到一个特殊名字的方法,这个方法负责生成一个模块对象和填充表格的内容,这两件事谁先谁后并没有影响。
相比于使用Python官方介绍的方法,pybind11只用两三行代码就完成了工作,简直不要太爽。关于使用传统方法去导出C++接口,我在使用C语言编写Python模块-引子也有介绍过,没看过的可以去看一看,它是我们能看懂pybind11源码的基础。
正文
万变不离其宗,pybind11只不过是将原本我们所需要做的封装好了而已,下面我们就来揭开它神秘的面纱。首先,我们来看看宏PYBIND11_MODULE
定义,它所依赖一些宏我也一并找出并列了出来:
#define PYBIND11_MODULE(name, variable) \
static void PYBIND11_CONCAT(pybind11_init_, name)(pybind11::module &); \
PYBIND11_PLUGIN_IMPL(name) { \
PYBIND11_CHECK_PYTHON_VERSION \
auto m = pybind11::module(PYBIND11_TOSTRING(name)); \
try { \
PYBIND11_CONCAT(pybind11_init_, name)(m); \
return m.ptr(); \
} PYBIND11_CATCH_INIT_EXCEPTIONS \
} \
void PYBIND11_CONCAT(pybind11_init_, name)(pybind11::module &variable)
#define PYBIND11_CONCAT(first, second) first##second
#define PYBIND11_PLUGIN_IMPL(name) \
extern "C" PYBIND11_EXPORT PyObject *PyInit_##name(); \
extern "C" PYBIND11_EXPORT PyObject *PyInit_##name()
#define PYBIND11_CHECK_PYTHON_VERSION \
{ \
const char *compiled_ver = PYBIND11_TOSTRING(PY_MAJOR_VERSION) \
"." PYBIND11_TOSTRING(PY_MINOR_VERSION); \
const char *runtime_ver = Py_GetVersion(); \
size_t len = std::strlen(compiled_ver); \
if (std::strncmp(runtime_ver, compiled_ver, len) != 0 \
|| (runtime_ver[len] >= '0' && runtime_ver[len] <= '9')) { \
PyErr_Format(PyExc_ImportError, \
"Python version mismatch: module was compiled for Python %s, " \
"but the interpreter version is incompatible: %s.", \
compiled_ver, runtime_ver); \
return nullptr; \
} \
}
#define PYBIND11_STRINGIFY(x) #x
#define PYBIND11_TOSTRING(x) PYBIND11_STRINGIFY(x)
#define PYBIND11_CATCH_INIT_EXCEPTIONS \
catch (pybind11::error_already_set &e) { \
PyErr_SetString(PyExc_ImportError, e.what()); \
return nullptr; \
} catch (const std::exception &e) { \
PyErr_SetString(PyExc_ImportError, e.what()); \
return nullptr; \
}
#if !defined(PYBIND11_EXPORT)
# if defined(WIN32) || defined(_WIN32)
# define PYBIND11_EXPORT __declspec(dllexport)
# else
# define PYBIND11_EXPORT __attribute__ ((visibility("default")))
# endif
#endif
这么看比较晦涩,我们将文章开头的例子使用进行宏展开,得到下面的代码,这么一看,清晰很多:
static void pybind11_init_example(pybind11::module &);
static PyObject *pybind11_init_wrapper();
extern "C" __attribute__ ((visibility("default"))) void initexample();
extern "C" __attribute__ ((visibility("default"))) void initexample() { (void)pybind11_init_wrapper(); }
PyObject *pybind11_init_wrapper() {
{
const char *compiled_ver = "2" "." "7";
const char *runtime_ver = Py_GetVersion();
size_t len = std::strlen(compiled_ver);
if (std::strncmp(runtime_ver, compiled_ver, len) != 0 || (runtime_ver[len] >= '0' && runtime_ver[len] <= '9')) {
PyErr_Format(PyExc_ImportError, "Python version mismatch: module was compiled for Python %s, " "but the interpreter version is incompatible: %s.", compiled_ver, runtime_ver);
return nullptr;
}
}
auto m = pybind11::module("example");
try {
pybind11_init_example(m);
return m.ptr();
} catch (pybind11::error_already_set &e) {
PyErr_SetString(PyExc_ImportError, e.what());
return nullptr;
} catch (const std::exception &e) {
PyErr_SetString(PyExc_ImportError, e.what());
return nullptr;
}
}
void pybind11_init_example(pybind11::module &m) {
m.doc() = "pybind11 example plugin";
m.def("add", &add, "A function which adds two numbers");
}
从展开的代码第四行中可以看到,上面提到步骤中的第五步:给出一个特殊名字的函数已经体现了。在这个特殊函数中,调用了pybind11_init_wrapper
去创建了一个pybind11::module
的实例,并调用其def()
方,我们需要导出到Python的C++函数add
的地址作为参数传了进去,那我们顺藤摸瓜,看看在def()
中执行了什么操作。
// Wrapper for Python extension modules
class module : public object {
public:
PYBIND11_OBJECT_DEFAULT(module, object, PyModule_Check)
/// Create a new top-level Python module with the given name and docstring
explicit module(const char *name, const char *doc = nullptr) {
if (!options::show_user_defined_docstrings()) doc = nullptr;
#if PY_MAJOR_VERSION >= 3
PyModuleDef *def = new PyModuleDef();
std::memset(def, 0, sizeof(PyModuleDef));
def->m_name = name;
def->m_doc = doc;
def->m_size = -1;
Py_INCREF(def);
m_ptr = PyModule_Create(def);
#else
m_ptr = Py_InitModule3(name, nullptr, doc);
#endif
if (m_ptr == nullptr)
pybind11_fail("Internal error in module::module()");
inc_ref();
}
template <typename Func, typename... Extra>
module &def(const char *name_, Func &&f, const Extra& ... extra) {
cpp_function func(std::forward<Func>(f), name(name_), scope(*this),
sibling(getattr(*this, name_, none())), extra...);
// NB: allow overwriting here because cpp_function sets up a chain with the intention of
// overwriting (and has already checked internally that it isn't overwriting non-functions).
add_object(name_, func, true /* overwrite */);
return *this;
}
PYBIND11_NOINLINE void add_object(const char *name, handle obj, bool overwrite = false) {
if (!overwrite && hasattr(*this, name))
pybind11_fail("Error during initialization: multiple incompatible definitions with name \"" +
std::string(name) + "\"");
PyModule_AddObject(ptr(), name, obj.inc_ref().ptr() /* steals a reference */);
}
};
有种豁然开朗的感觉。在def()
中,我们看到,我们传递进去的函数指针,被cpp_function
这个类封装了起来,使用PyObject*
去保存,这样方便对它进行引用计数的管理,因为Python的垃圾回收主要依靠引用技术实现。之后它将这个cpp_function
作为参数传递给了add_object()
函数。最终,在add_object()
中我们看到它调用了我们上面说到的第四步,调用PyModule_AddObject(m, name, PyObject*)
将函数添加到模块。
那第二第三步在那里?答案是构造函数里面。在构造函数中,先创建了一个模块对象,然后等待用户调用的def()
的时候向方法表填充内容。
至此,pybind11的秘密在我面前展现的一览无遗。
总结
本文从传统方法入手,一步一步剖析pybind11如何化繁为简。有时候,基础的东西虽然繁琐,但是掌握了以后却能方便我们理解其他更高层的内容。
References
[1] Extending Python with C or C++
本文首发于个人公众号TensorBoy。如果你觉得内容还不错,欢迎分享并关注我的公众号TensorBoy,扫描下方二维码获取更多精彩原创内容!