《扩展和嵌入python解释器》1.12 为扩展模块提供C API

最新推荐文章于 2024-10-18 00:00:00 发布

asmc51

最新推荐文章于 2024-10-18 00:00:00 发布

阅读量4.9k

点赞数

文章标签：扩展 api python c system pointers

1.12 为扩展模块提供C　API(Providing a C API for an Extension Module)

许多扩展模块仅仅提供Python使用的新函数和类型，但有时扩展模块的代码对其他模块有用。例如，一个扩展模块实现了新类型’collection’，功能象没有顺序的list一样。就象标准的Python　list类型有运行扩展模块创建操作list的C API一样，这个新collection类型也应有一个直接从扩展模块进行操作的C函数集。

起初，看起来很容易：仅是写些函数（当然，不能声明它们为static），提供一个合适的头文件，并编写相应的C API文档。事实上，如果所有的扩展模块总是和Python解释器静态连接，这样做有用。然而，当模块使用共享库时，在一个模块中定义的符号也许在另一个模块中不可见。可见性的细节依赖于操作系统，有的系统为Python解释器和所有扩展模块使用全局名字空间（如windows），但是，其他系统（AIX是其中一个例子）要求在模块连接时明确导入符号列表，或提供不同策略的选择（大多数Unices）。即使符号是全局可见的，函数在希望被调用时可能函数的模块还没有加载！

为此，可移植性要求不能假设符号的可见性。这意味着，为了避免和其他扩展模块(正如 1.4中讨论的)发生命名冲突，在扩展模块中的所有符号应该被声明为static，除了模块初始化函数。这意味着应该被从其他扩展模块访问的符号必须以不同的方式导出。

Python提供了一个特别的机制来从一个扩展模块到另一个扩展模块传递C-level信息（指针）：CObject。CObject是存储指针（void *）的Python数据类型。 CObject只能经由它们的C API创建和访问，但它们能象其他Python对象到处传递。特别地，它们能够在扩展模块的名字空间中指定一个名字。其他模块导入这个模块，获得这个名称的值，然后从CObject获取指针。

导出C API的扩展模块有多种方式使用CObject。每个名字能够获得它的CObject，或全部C API的指针保存在一个数组中，数组的地址在CObject发布。在提供代码的模块和客户模块间，不同的保存和获取指针的任务可以用不同的方式提供。

下面的例子演示了一种方式，它把大多数工作方在导出模块的作者身上，这对通常使用的库模块是正确的。它存储所有的C API指针（例子中只有一个指针）在一个void类型的指针数组中，这个指针数组成为CObject的一个值。相应模块的头文件提供一个宏，负责导出模块并接受模块C API指针。客户模块只需要在访问C API前调用这个宏。

导出模块是从 1.1节的spam例子修改的。函数spam.system()不直接调用C库函数system()，而是调用函数PySpam_System()，这个当然做些象现实当中一样更复杂的事情（诸如给每个命令增加spam）。PySpam_System()这个函数也导出到其他扩展模块。

函数PySpam_System()是一个纯粹的C函数，象其他函数一样声明为static：

static int
PySpam_System(const char *command)
{
    return system(command);
}

函数spam_system()以普通的方式修改：

static PyObject *
spam_system(PyObject *self, PyObject *args)
{
    const char *command;
    int sts;

    if (!PyArg_ParseTuple(args, "s", &command))
        return NULL;
    sts = PySpam_System(command);
    return Py_BuildValue("i", sts);
}

在模块的开始处，在

#include "Python.h"

行后面必须添加下面两行：

#define SPAM_MODULE
#include "spammodule.h"

#define用来在导出模块中，而不是客户模块中，识别头文件。最后，模块的初始化函数必须处理C API指针数组的初始化。

PyMODINIT_FUNC
initspam(void)
{
    PyObject *m;
    static void *PySpam_API[PySpam_API_pointers];
    PyObject *c_api_object;

    m = Py_InitModule("spam", SpamMethods);

    /* Initialize the C API pointer array */
    PySpam_API[PySpam_System_NUM] = (void *)PySpam_System;

    /* Create a CObject containing the API pointer array's address */
    c_api_object = PyCObject_FromVoidPtr((void *)PySpam_API, NULL);

    if (c_api_object != NULL)
        PyModule_AddObject(m, "_C_API", c_api_object);
}

注意：PySpam_API被声明为static，否则指针数组会在initspam()函数终止时消失。

主要工作在头文件spammodule.h中，如下：

#ifndef Py_SPAMMODULE_H
#define Py_SPAMMODULE_H
#ifdef __cplusplus
extern "C" {
#endif

/* Header file for spammodule */

/* C API functions */
#define PySpam_System_NUM 0
#define PySpam_System_RETURN int
#define PySpam_System_PROTO (const char *command)

/* Total number of C API pointers */
#define PySpam_API_pointers 1


#ifdef SPAM_MODULE
/* This section is used when compiling spammodule.c */

static PySpam_System_RETURN PySpam_System PySpam_System_PROTO;

#else
/* This section is used in modules that use spammodule's API */

static void **PySpam_API;

#define PySpam_System /
 (*(PySpam_System_RETURN (*)PySpam_System_PROTO) PySpam_API[PySpam_System_NUM])

/* Return -1 and set exception on error, 0 on success. */
static int
import_spam(void)
{
    PyObject *module = PyImport_ImportModule("spam");

    if (module != NULL) {
        PyObject *c_api_object = PyObject_GetAttrString(module, "_C_API");
        if (c_api_object == NULL)
            return -1;
        if (PyCObject_Check(c_api_object))
            PySpam_API = (void **)PyCObject_AsVoidPtr(c_api_object);
        Py_DECREF(c_api_object);
    }
    return 0;
}

#endif

#ifdef __cplusplus
}
#endif

#endif /* !defined(Py_SPAMMODULE_H) */

所有客户模块为了访问函数PySpam_System()，需要做的是在初始化函数中的调用import_spam()函数（而不是宏）:

PyMODINIT_FUNC
initclient(void)
{
    PyObject *m;

    Py_InitModule("client", ClientMethods);
    if (import_spam() < 0)
        return;
    /* additional initialization can happen here */
}

这种方式的主要缺点是文件spammodule.h相当负责。然而，对于每个导出函数基本结构是一样的，所以只需学习一次。

最后应该提到的是CObject提供其他功能，对存储在CObject的指针的内存申请和释放特别有用。在Python/C API Reference Manual的’CObjects’部分有详细描述，并有CObjects的实现(Python 提供的代码中Include/cobject.h ,Objects/cobject.c).