Python调用C++之PYBIND11源码分析

前情提要

在之前的文章Python调用C++之PYBIND11简介中我们介绍了pybind11的基本用法，我们已经知其然，接下来我们通过代码分析，知其所以然。通过之前的讲解，我们知道使用pybind11去导出C++接口到Python，只要使用一个宏PYBIND11_MODULE，例如之前的例子，将已有的C++函数int add(int, int)导出到Python：

#include "existence.h"
#include 

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

1. 拥有一个需要导出到Python的C++接口；
2. 将这个C++接口用一个PyMethodDef结构体封装起来，构成一个方法表，如果使用PyModule_AddObject这一步是不需要的；如果将PyModuleDef比作车头，PyMethodDef比作车厢，两种方法的区别就相当于是PyModule_AddObject()先把车厢挂在车头上在网上装货物，而手动封装PyMethodDef`就是先装了货物在将车头链接上；
3. 调用Py_InitModule(name, PyMethodDef**)得到一个模块对象，假设叫做m；
4. 调用PyModule_AddObject(m, name, PyObject*)将函数添加到模块；或者调用Py_InitModule去装载第二步中封装的方法表；
5. 给出一个按一定规则命名的函数供Python解析器加在该模块的时候调用，这个函数名的命名规则是特定前缀 + 模块名。Python 2的是init。例如，initexample，其中example是模块名。作用是调用第四步中的两个函数之一去盘活整个创建过程。

Python3

1. 拥有一个需要导出到Python的C++接口；
2. 将这个C++接口用一个PyMethodDef结构体封装起来，构成一个方法表，如果使用PyModule_AddObject()这一步是不需要的。如果将PyModuleDef比作车头，PyMethodDef比作车厢，两种方法的区别就相当于是PyModule_AddObject()先把车厢挂在车头上在网上装货物，而手动封装PyMethodDef`就是先装了货物在将车头链接上；
3. 将第二步方法表使用PyModuleDef结构体封装；
4. 根据PyModuleDef种的内容初始化模块，调用PyModule_Create(PyModuleDef*)函数创建模块；
5. 给出一个按一定规则命名的函数供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 
    module &def(const char *name_, Func &&f, const Extra& ... extra) {
        cpp_function func(std::forward(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，扫描下方二维码获取更多精彩原创内容！