前情提要
在之前的文章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，扫描下方二维码获取更多精彩原创内容！
