使用C/C++扩展Python

冷不防 2022-08-06 10:12 299阅读 0赞

# [http://gashero.yeax.com/?p=38][http_gashero.yeax.com_p_38] #

<table> 
 <tbody> 
  <tr> 
   <th>翻译:</th> 
   <td>gashero</td> 
  </tr> 
 </tbody> 
</table>

如果你会用C，实现Python嵌入模块很简单。利用扩展模块可做很多Python不方便做的事情，他们可以直接调用C库和系统调用。

为了支持扩展，Python API定义了一系列函数、宏和变量，提供了对Python运行时系统的访问支持。Python的C API由C源码组成，并包含 “Python.h” 头文件。

编写扩展模块与你的系统相关，下面会详解。

*  [1   一个简单的例子][1]
 *  [2   关于错误和异常][2]
 *  [3   回到例子][3]
 *  [4   模块方法表和初始化函数][4]
 *  [5   编译和连接][5]
 *  [6   在C中调用Python函数][6_C_Python]
 *  [7   解析传给扩展模块函数的参数][7]
 *  [8   解析传给扩展模块函数的关键字参数][8]
 *  [9   构造任意值][9]
 *  [10   引用计数][10]
    
     *  [10.1   Python中的引用计数][10.1_Python]
     *  [10.2   拥有规则][10.2]
     *  [10.3   危险的薄冰][10.3]
     *  [10.4   NULL指针][10.4_NULL]
 *  [11   使用C++编写扩展][11_C]
 *  [12   提供给其他模块以C API][12_C API]

# [1   一个简单的例子][1 1] #

下面的例子创建一个叫做 “spam” 的扩展模块，调用C库函数 system() 。这个函数输入一个NULL结尾的字符串并返回整数，可供Python调用方式如下:

>>> import spam
    >>> status=spam.system("ls -l")

一个C扩展模块的文件名可以直接是 模块名.c 或者是 模块名module.c 。第一行应该导入头文件:

#include <Python.h>

这会导入Python API。

Warning

因为Python含有一些预处理定义，所以你必须在所有非标准头文件导入之前导入Python.h 。

Python.h中所有用户可见的符号都有 Py 或 PY 的前缀，除非定义在标准头文件中。为了方便 “Python.h” 也包含了一些常用的标准头文件，包括<stdio.h>，<string.h>，<errno.h>，<stdlib.h>。如果你的系统没有后面的头文件，则会直接定义函数 malloc() 、 free() 和 realloc() 。

下面添加C代码到扩展模块，当调用 “spam.system(string)” 时会做出响应:

static PyObject*
    spam_system(PyObject* self, PyObject* args) {
        const char* command;
        int sts;
        if (!PyArg_ParseTuple(args,"s",&command))
            return NULL;
        sts=system(command);
        return Py_BuildValue("i",sts);
    }

调用方的Python只有一个命令参数字符串传递到C函数。C函数总是有两个参数，按照惯例分别叫做 self 和 args 。

self 参数仅用于用C实现内置方法而不是函数。本例中， self 总是为NULL，因为我们定义的是个函数，不是方法。这一切都是相同的，所以解释器也就不需要刻意区分两种不同的C函数。

args 参数是一个指向Python的tuple对象的指针，包含参数。每个tuple子项对应一个调用参数。这些参数也全都是Python对象，所以需要先转换成C值。函数 PyArg\_ParseTuple() 检查参数类型并转换成C值。它使用模板字符串检测需要的参数类型。

PyArg\_ParseTuple() 正常返回非零，并已经按照提供的地址存入了各个变量值。如果出错(零)则应该让函数返回NULL以通知解释器出错。

# [2   关于错误和异常][2 1] #

一个常见惯例是，函数发生错误时，应该设置一个异常环境并返回错误值(NULL)。异常存储在解释器静态全局变量中，如果为NULL，则没有发生异常。异常的第一个参数也需要保存在静态全局变量中，也就是raise的第二个参数。第三个变量包含栈回溯信息。这三个变量等同于Python变量 sys.exc\_type 、 sys.exc\_value 、 sys.exc\_traceback 。这对找到错误是很必要的。

Python API中定义了一些函数来设置这些变量。

最常用的就是 PyErr\_SetString() 。参数是异常对象和C字符串。异常对象一般由像 PyExc\_ZeroDivisionError 这样的对象来预定义。C字符串指明异常原因，并最终存储在异常的第一个参数里面。

另一个有用的函数是 PyErr\_SetFromErrno() ，仅接受一个异常对象，异常描述包含在全局变量 errno 中。最通用的函数还是 PyErr\_SetObject() ，包含两个参数，分别为异常对象和异常描述。你不需要使用 Py\_INCREF() 来增加传递到其他函数的参数对象的引用计数。

你可以通过 PyErr\_Occurred() 获知当前异常，返回当前异常对象，如果确实没有则为NULL。一般来说，你在调用函数时不需要调用 PyErr\_Occurred() 检查是否发生了异常，你可以直接检查返回值。

如果调用更下层函数时出错了，那么本函数返回NULL表示错误，并且整个调用栈中只要有一处调用 PyErr\_\*() 函数设置异常就可以。一般来说，首先发现错误的函数应该设置异常。一旦这个错误到达了Python解释器的主循环，则会中断当前执行代码并追究异常。

有一种情况下，模块可能依靠其他 PyErr\_\*() 函数给出更加详细的错误信息，并且是正确的。但是按照一般规则，这并不重要，很多操作都会因为种种原因而挂掉。

想要忽略这些函数设置的异常，异常情况必须明确的使用 PyErr\_Clear() 来清除。只有在C代码想要自己处理异常而不是传给解释器时才这么做。

每次失败的 malloc() 调用必须抛出一个异常，直接调用 malloc() 或 realloc() 的地方要调用 PyErr\_NoMemory() 并返回错误。所有创建对象的函数都已经实现了这个异常的抛出，所以这是每个分配内存都要做的。

还要注意的是 PyArg\_ParseTuple() 系列函数的异常，返回一个整数状态码是有效的，0是成功，-1是失败，有如Unix系统调用。

最后，小心垃圾情理，也就是 Py\_XDECREF() 和 Py\_DECREF() 的调用，会返回的异常。

选择抛出哪个异常完全是你的个人爱好了。有一系列的C对象代表了内置Python异常，例如 PyExc\_ZeroDivisionError ，你可以直接使用。当然，你可能选择更合适的异常，不过别使用 PyExc\_TypeError 告知文件打开失败(有个更合适的 PyExc\_IOError )。如果参数列表有误， PyArg\_ParseTuple() 通常会抛出 PyExc\_TypeError 。如果参数值域有误， PyExc\_ValueError 更合适一些。

你也可以为你的模块定义一个唯一的新异常。需要在文件前部声明一个静态对象变量，如:

static PyObject* SpamError;

然后在模块初始化函数(initspam())里面初始化它，并省却了处理:

PyMODINIT_FUNC
    initspam(void) {
        PyObject* m;
        m=Py_InitModule("spam",SpamMethods);
        if (m==NULL)
            return NULL;
        SpamError=PyErr_NewException("spam.error",NULL,NULL);
        Py_INCREF(SpamError);
        PyModule_AddObject(m,"error",SpamError);
    }

注意实际的Python异常名字是 spam.error 。 PyErr\_NewException() 函数使用Exception为基类创建一个类(除非是使用另外一个类替代NULL)。

同样注意的是创建类保存了SpamError的一个引用，这是有意的。为了防止被垃圾回收掉，否则SpamError随时会成为野指针。

一会讨论 PyMODINIT\_FUNC 作为函数返回类型的用法。

# [3   回到例子][3 1] #

回到前面的例子，你应该明白下面的代码:

if (!PyArg_ParseTuple(args,"s",&command))
        return NULL;

就是为了报告解释器一个异常。如果执行正常则变量会拷贝到本地，后面的变量都应该以指针的方式提供，以方便设置变量。本例中的command会被声明为 “const char\* command” 。

下一个语句使用UNIX系统函数system()，传递给他的参数是刚才从 PyArg\_ParseTuple() 取出的:

sts=system(command);

我们的 spam.system() 函数必须返回一个PY对象，这可以通过 Py\_BuildValue() 来完成，其形式与 PyArg\_ParseTuple() 很像，获取格式字符串和C值，并返回新的Python对象:

return Py_BuildValue("i",sts);

在这种情况下，会返回一个整数对象，这个对象会在Python堆里面管理。

如果你的C函数没有有用的返回值，则必须返回None。你可以用 Py\_RETUN\_NONE 宏来完成:

Py_INCREF(Py_None);
    return Py_None;

Py\_None 是一个C名字指定Python对象None。这是一个真正的PY对象，而不是NULL指针。

# [4   模块方法表和初始化函数][4 1] #

把函数声明为可以被Python调用，需要先定义一个方法表:

static PyMethodDef SpamMethods[]= {
        ...
        {"system",spam_system,METH_VARARGS,
        "Execute a shell command."},
        ...
        {NULL,NULL,0,NULL}    /*必须的结束符*/
    };

注意第三个参数 METH\_VARARGS ，这个标志指定会使用C的调用惯例。可选值有 METH\_VARARGS 、 METH\_VARARGS | METH\_KEYWORDS 。值0代表使用 PyArg\_ParseTuple() 的陈旧变量。

如果单独使用 METH\_VARARGS ，函数会等待Python传来tuple格式的参数，并最终使用 PyArg\_ParseTuple() 进行解析。

METH\_KEYWORDS 值表示接受关键字参数。这种情况下C函数需要接受第三个 PyObject\* 对象，表示字典参数，使用 PyArg\_ParseTupleAndKeywords() 来解析出参数。

方法表必须传递给模块初始化函数。初始化函数函数名规则为 initname() ，其中 name 为模块名。并且不能定义为文件中的static函数:

PyMODINIT_FUNC
    initspam(void) {
        (void) Py_InitModule("spam",SpamMethods);
    }

注意 PyMODINIT\_FUNC 声明了void为返回类型，还有就是平台相关的一些定义，如C++的就要定义成 extern “C” 。

Python程序首次导入这个模块时就会调用initspam()函数。他调用 Py\_InitModule() 来创建一个模块对象，同时这个模块对象会插入到 sys.modules 字典中的 “spam” 键下面。然后是插入方法表中的内置函数到 “spam” 键下面。 Py\_InitModule() 返回一个指针指向刚创建的模块对象。他是有可能发生严重错误的，也有可能在无法正确初始化时返回NULL。

当嵌入Python时， initspam() 函数不会自动被调用，除非在入口处的 \_PyImport\_Inittab 表。最简单的初始化方法是在 Py\_Initialize() 之后静态调用 initspam() 函数:

int
    main(int argc, char* argv[]) {
        Py_SetProgramName(argv[0]);
        Py_Initialize();
        initspam();
        //...
    }

在Python发行版的 Demo/embed/demo.c 中有可以参考的源码。

Note

从 sys.modules 中移除模块入口，或者在多解释器环境中导入编译模块，会导致一些扩展模块出错。扩展模块作者应该特别注意初始化内部数据结构。同时要注意 reload() 函数可能会被用在扩展模块身上，并调用模块初始化函数，但是对动态状如对象(动态链接库)，却不会重新载入。

更多关于模块的现实的例子包含在Python源码包的Modules/xxmodule.c中。这些文件可以用作你的代码模板，或者学习。脚本 **modulator.py** 包含在源码发行版或Windows安装中，提供了一个简单的GUI，用来声明需要实现的函数和对象，并且可以生成供填入的模板。脚本在 Tools/modulator/ 目录。查看README以了解用法。

# [5   编译和连接][5 1] #

如果使用动态载入，细节依赖于系统，查看关于构建扩展模块部分，和关于在Windows下构建扩展的细节。

如果你无法使用动态载入，或者希望模块成为Python的永久组成部分，就必须改变配置并重新构建解释器。幸运的是，这对UNIX来说很简单，只要把你的代码(例如spammodule.c)放在 Modules/ Python源码目录下，然后增加一行到文件 Modules/Setup.local 来描述你的文件即可:

spam spammodule.o

然后重新构建解释器，使用make。你也可以在 Modules/ 子目录使用make，但是你接下来首先要重建Makefile文件，使用 make Makefile 命令。这对你改变 Setup 文件来说很重要。

如果你的模块需要其他扩展模块连接，则需要在配置文件后面加入，如:

spam spammodule.o -lX11

# [6   在C中调用Python函数][6_C_Python 1] #

迄今为止，我们一直把注意力集中于让Python调用C函数，其实反过来也很有用，就是用C调用Python函数。这在回调函数中尤其有用。如果一个C接口使用回调，那么就要实现这个回调机制。

幸运的是，Python解释器是比较方便回调的，并给标准Python函数提供了标准接口。这里就不再详述解析Python代码作为输入的方式，如果有兴趣可以参考 Python/pythonmain.c 中的 -c 命令代码。

调用Python函数，首先Python程序要传递Python函数对象。当调用这个函数时，用全局变量保存Python函数对象的指针，还要调用 Py\_INCREF() 来增加引用计数，当然不用全局变量也没什么关系。例如如下:

static PyObject* my_callback=NULL;
    static PyObject*
    my_set_callback(PyObject* dummy, PyObject* args) {
        PyObject* result=NULL;
        PyObject* temp;
        if (PyArg_ParseTuple(args,"O:set_callback",&temp)) {
            if (!PyCallable_Check(temp)) {
                PyErr_SetString(PyExc_TypeError,"parameter must be callable");
                return NULL;
            }
            Py_XINCREF(temp);
            Py_XINCREF(my_callback);
            my_callback=temp;
            Py_INCREF(Py_None);
            result=Py_None;
        }
        return result;
    }

这个函数必须使用 METH\_VARARGS 标志注册到解释器。宏 Py\_XINCREF() 和 Py\_XDECREF() 增加和减少对象的引用计数。

然后，就要调用函数了，使用 PyEval\_CallObject() 。这个函数有两个参数，都是指向Python对象：Python函数和参数列表。参数列表必须总是tuple对象，如果没有参数则要传递空的tuple。使用 Py\_BuildValue() 时，在圆括号中的参数会构造成tuple，无论有没有参数，如:

int arg;
    PyObject* arglist;
    PyObject* result;
    //...
    arg=123;
    //...
    arglist=Py_BuildValue("(i)",arg);
    result=PyEval_CallObject(my_callback,arglist);
    Py_DECREF(arglist);

PyEval\_CallObject() 返回一个Python对象指针表示返回值。 PyEval\_CallObject() 是 **引用计数无关** 的，有如例子中，参数列表对象使用完成后就立即减少引用计数了。\`PyEval\_CallObject()\` 返回一个Python对象指针表示返回值。 PyEval\_CallObject() 是 **引用计数无关** 的，有如例子中，参数列表对象使用完成后就立即减少引用计数了。

PyEval\_CallObject() 的返回值总是新的，新建对象或者是对已有对象增加引用计数。所以你必须获取这个对象指针，在使用后减少其引用计数，即便是对返回值没有兴趣也要这么做。但是在减少这个引用计数之前，你必须先检查返回的指针是否为NULL。如果是NULL，则表示出现了异常并中止了。如果没有处理则会向上传递并最终显示调用栈，当然，你最好还是处理好异常。如果你对异常没有兴趣，可以用 PyErr\_Clear() 清除异常，例如:

if (result==NULL)
        return NULL;  /*向上传递异常*/
    //使用result
    Py_DECREF(result);

依赖于具体的回调函数，你还要提供一个参数列表到 PyEval\_CallObject() 。在某些情况下参数列表是由Python程序提供的，通过接口再传到回调函数。这样就可以不改变形式直接传递。另外一些时候你要构造一个新的tuple来传递参数。最简单的方法就是 Py\_BuildValue() 函数构造tuple。例如，你要传递一个事件对象时可以用:

PyObject* arglist;
    //...
    arglist=Py_BuildValue("(l)",eventcode);
    result=PyEval_CallObject(my_callback,arglist);
    Py_DECREF(arglist);
    if (result==NULL)
        return NULL;  /*一个错误*/
    /*使用返回值*/
    Py_DECREF(result);

注意 Py\_DECREF(arglist) 所在处会立即调用，在错误检查之前。当然还要注意一些常规的错误，比如 Py\_BuildValue() 可能会遭遇内存不足等等。

# [7   解析传给扩展模块函数的参数][7 1] #

函数 PyArg\_ParseTuple() 声明如下:

int PyArg_ParseTuple(PyObject* arg, char* format, ...);

参数 arg 必须是一个tuple对象，包含传递过来的参数， format 参数必须是格式化字符串，语法解释见 “Python C/API” 的5.5节。剩余参数是各个变量的地址，类型要与格式化字符串对应。

注意 PyArg\_ParseTuple() 会检测他需要的Python参数类型，却无法检测传递给他的C变量地址，如果这里出错了，可能会在内存中随机写入东西，小心。

任何Python对象的引用，在调用者这里都是 **借用的引用** ，而不增加引用计数。

一些例子:

int ok;
    int i,j;
    long k,l;
    const char* s;
    int size;
    ok=PyArg_ParseTuple(args,"");
    /* python call: f() */
    
    ok=PyArg_ParseTuple(args,"s",&s);
    /* python call: f('whoops!') */
    
    ok=PyArg_ParseTuple(args,"lls",&k,&l,&s);
    /* python call: f(1,2,'three') */
    
    ok=PyArg_ParseTuple(args,"(ii)s#",&i,&j,&s,&size);
    /* python call: f((1,2),'three') */
    
    {
        const char* file;
        const char* mode="r";
        int bufsize=0;
        ok=PyArg_ParseTuple(args,"s|si",&file,&mode,&bufsize);
        /* python call:
            f('spam')
            f('spam','w')
            f('spam','wb',100000)
        */
    }
    
    {
        int left,top,right,bottom,h,v;
        ok=PyArg_ParseTuple(args,"((ii)(ii))(ii)",
            &left,&top,&right,&bottom,&h,&v);
        /* python call: f(((0,0),(400,300)),(10,10)) */
    }
    
    {
        Py_complex c;
        ok=PyArg_ParseTuple(args,"D:myfunction",&c);
        /* python call: myfunction(1+2j) */
    }

# [8   解析传给扩展模块函数的关键字参数][8 1] #

函数 PyArg\_ParseTupleAndKeywords() 声明如下:

int PyArg_ParseTupleAndKeywords(PyObject* arg, PyObject* kwdict, char* format, char* kwlist[],...);

参数arg和format定义同 PyArg\_ParseTuple() 。参数 kwdict 是关键字字典，用于接受运行时传来的关键字参数。参数 kwlist 是一个NULL结尾的字符串，定义了可以接受的参数名，并从左到右与format中各个变量对应。如果执行成功 PyArg\_ParseTupleAndKeywords() 会返回true，否则返回false并抛出异常。

Note

嵌套的tuple在使用关键字参数时无法生效，不在kwlist中的关键字参数会导致 **TypeError** 异常。

如下是使用关键字参数的例子模块，作者是 Geoff Philbrick ([phibrick@hks.com][phibrick_hks.com]):

#include "Python.h"
    
    static PyObject*
    keywdarg_parrot(PyObject* self, PyObject* args, PyObject* keywds) {
        int voltage;
        char* state="a stiff";
        char* action="voom";
        char* type="Norwegian Blue";
        static char* kwlist[]={"voltage","state","action","type",NULL};
        if (!PyArg_ParseTupleAndKeywords(args,keywds,"i|sss",kwlist,
                &voltage,&state,&action,&type))
            return NULL;
        printf("-- This parrot wouldn't %s if you put %i Volts through it.n",action,voltage);
        printf("-- Lovely plumage, the %s -- It's %s!n",type,state);
        Py_INCREF(Py_None);
        return Py_None;
    }
    
    static PyMethodDef keywdary_methods[]= {
        /*注意PyCFunction，这对需要关键字参数的函数很必要*/
        {"parrot",(PyCFunction)keywdarg_parrot, METH_VARARGS | METH_KEYWORDS,"Print a lovely skit to standard output."},
        {NULL,NULL,0,NULL}
    };
    
    void
    initkeywdarg(void) {
        Py_InitModule("keywdarg",keywdarg_methods);
    }

# [9   构造任意值][9 1] #

这个函数声明与 PyArg\_ParseTuple() 很相似，如下:

PyObject* Py_BuildValue(char* format, ...);

接受一个格式字符串，与 PyArg\_ParseTuple() 相同，但是参数必须是原变量的地址指针。最终返回一个Python对象适合于返回给Python代码。

一个与 PyArg\_ParseTuple() 的不同是，后面可能需要的要求返回一个tuple，比如用于传递给其他Python函数以参数。 Py\_BuildValue() 并不总是生成tuple，在多于1个参数时会生成tuple，而如果没有参数则返回None，一个参数则直接返回该参数的对象。如果要求强制生成一个长度为空的tuple，或包含一个元素的tuple，需要在格式字符串中加上括号。

例如：

<table> 
 <tbody> 
  <tr> 
   <td>代码</td> 
   <td>返回值</td> 
  </tr> 
  <tr> 
   <td>Py_BuildValue(”")</td> 
   <td>None</td> 
  </tr> 
  <tr> 
   <td>Py_BuildValue(”i”,123)</td> 
   <td>123</td> 
  </tr> 
  <tr> 
   <td>Py_BuildValue(”iii”,123,456,789)</td> 
   <td>(123,456,789)</td> 
  </tr> 
  <tr> 
   <td>Py_BuildValue(”s”,”hello”)</td> 
   <td>‘hello’</td> 
  </tr> 
  <tr> 
   <td>Py_BuildValue(”ss”,”hello”,”world”)</td> 
   <td>(’hello’, ‘world’)</td> 
  </tr> 
  <tr> 
   <td>Py_BuildValue(”s#”,”hello”,4)</td> 
   <td>‘hell’</td> 
  </tr> 
  <tr> 
   <td>Py_BuildValue(”()”)</td> 
   <td>()</td> 
  </tr> 
  <tr> 
   <td>Py_BuildValue(”(i)”,123)</td> 
   <td>(123,)</td> 
  </tr> 
  <tr> 
   <td>Py_BuildValue(”(ii)”,123,456)</td> 
   <td>(123,456)</td> 
  </tr> 
  <tr> 
   <td>Py_BuildValue(”(i,i)”,123,456)</td> 
   <td>(123,456)</td> 
  </tr> 
  <tr> 
   <td>Py_BuildValue(”[i,i]”,123,456)</td> 
   <td>[123,456]</td> 
  </tr> 
  <tr> 
   <td>Py_BuildValue(”{s:i,s:i}”,’a',1,’b',2)</td> 
   <td>{’a':1,’b':2}</td> 
  </tr> 
  <tr> 
   <td>Py_BuildValue(”((ii)(ii))(ii)”,1,2,3,4,5,6)</td> 
   <td>(((1,2),(3,4)),(5,6))</td> 
  </tr> 
 </tbody> 
</table>

# [10   引用计数][10 1] #

在C/C++语言中，程序员负责动态分配和回收堆(heap)当中的内存。这意味着，我们在C中编程时必须面对这个问题。

每个由 malloc() 分配的内存块，最终都要由 free() 扔到可用内存池里面去。而调用 free() 的时机非常重要，如果一个内存块忘了 free() 则是内存泄漏，程序结束前将无法重新使用。而如果对同一内存块 free() 了以后，另外一个指针再次访问，则叫做野指针。这同样会导致严重的问题。

内存泄露往往发生在一些并不常见的程序流程上面，比如一个函数申请了资源以后，却提前返回了，返回之前没有做清理工作。人们经常忘记释放资源，尤其对于后加新加的代码，而且会长时间都无法发现。这些函数往往并不经常调用，而且现在大多数机器都有庞大的虚拟内存，所以内存泄漏往往在长时间运行的进程，或经常被调用的函数中才容易发现。所以最好有个好习惯加上代码约定来尽量避免内存泄露。

Python往往包含大量的内存分配和释放，同样需要避免内存泄漏和野指针。他选择的方法就是 **引用计数** 。其原理比较简单：每个对象都包含一个计数器，计数器的增减与引用的增减直接相关，当引用计数为0时，表示对象已经没有存在的意义了，就可以删除了。

一个叫法是 **自动垃圾回收** ，引用计数是一种垃圾回收方法，用户必须要手动调用 free() 函数。优点是可以提高内存使用率，缺点是C语言至今也没有一个可移植的自动垃圾回收器。引用计数却可以很好的移植，有如C当中的 malloc() 和 free() 一样。也许某一天会出现C语言饿自动垃圾回收器，不过在此之前我们还得用引用计数。

Python使用传统的引用计数实现，不过他包含一个循环引用探测器。这允许应用不需要担心的直接或间接的创建循环引用，而这实际上是引用计数实现的自动垃圾回收的致命缺点。循环引用指对象经过几层引用后回到自己，导致了其引用计数总是不为0。传统的引用计数实现无法解决循环引用的问题，尽管已经没有其他外部引用了。

循环引用探测器可以检测出垃圾回收中的循环并释放其中的对象。只要Python对象有 \_\_del\_\_() 方法，Python就可以通过 gc module 模块来自动暴露出循环引用。gc模块还提供 collect() 函数来运行循环引用探测器，可以在配置文件或运行时禁用循环应用探测器。

循环引用探测器作为一个备选选项，默认是打开的，可以在构建时使用 **–without-cycle-gc** 选项加到 **configure** 上来配置，或者移除 pyconfig.h 文件中的 WITH\_CYCLE\_GC 宏定义。在循环引用探测器禁用后，gc模块将不可用。

## [10.1   Python中的引用计数][10.1_Python 1] ##

有两个宏 Py\_INCREF(x) 和 Py\_DECREF(x) 用于增减引用计数。 Py\_DECREF() 同时会在引用计数为0时释放对象资源。为了灵活性，他并不是直接调用 free() 而是调用对象所在类型的析构函数。

一个大问题是何时调用 Py\_INCREF(x) 和 Py\_DECREF(x) 。首先介绍一些术语。没有任何人都不会 **拥有** 一个对象，只能拥有其引用。对一个对象的引用计数定义了引用数量。拥有的引用，在不再需要时负责调用 Py\_DECREF() 来减少引用计数。传递引用计数有三种方式：传递、存储和调用 Py\_DECREF() 。忘记减少拥有的引用计数会导致内存泄漏。

同样重要的一个概念是 **借用** 一个对象，借用的对象不能调用 Py\_DECREF() 来减少引用计数。借用者在不需要借用时，不保留其引用就可以了。应该避免拥有者释放对象之后仍然访问对象，也就是野指针。

借用的优点是你无需管理引用计数，缺点是可能被野指针搞的头晕。借用导致的野指针问题常发生在看起来无比正确，但是事实上已经被释放的对象。

借用的引用也可以用 Py\_INCREF() 来改造成拥有的引用。这对引用的对象本身没什么影响，但是拥有引用的程序有责任在适当的时候释放这个拥有。

## [10.2   拥有规则][10.2 1] ##

一个对象的引用进出一个函数时，其引用计数也应该同时改变。

大多数函数会返回一个对对象拥有的引用。而且几乎所有的函数其实都会创建一个对象，例如 PyInt\_FromLong() 和 Py\_BuildValue() ，传递一个拥有的引用给接受者。即便不是刚创建的，你也需要接受一个新的拥有引用。一般来说， PyInt\_FromLong() 会维护一个常用值缓存，并且返回缓存项的引用。

很多函数提取一些对象的子对象并传递拥有引用，例如 PyObject\_GetAttrString() 。另外，小心一些函数，包括： PyTuple\_GetItem() 、 PyList\_GetItem() 、 PyDict\_GetItem() 和 PyDict\_GetItemString() ，他们返回的都是借用的引用。

函数 PyImport\_AddModule() 也是返回借用的引用，尽管他实际上创建了对象，只不过其拥有的引用实际存储在了 sys.modules 中。

当你传递一个对象的引用到另外一个函数时，一般来说，函数是借用你的引用，如果他确实需要存储，则会使用 Py\_INCREF() 来变为拥有引用。这个规则有两种可能的异常： PyTuple\_SetItem() 和 PyList\_SetItem() ，这两个函数获取传递给他的拥有引用，即便是他们执行出错了。不过 PyDict\_SetItem() 却不是接收拥有的引用。

当一个C函数被py调用时，使用对参数的借用。调用者拥有参数对象的拥有引用。所以，借用的引用的寿命是函数返回。只有当这类参数必须存储时，才会使用 Py\_INCREF() 变为拥有的引用。

从C函数返回的对象引用必须是拥有的引用，这时的拥有者是调用者。

## [10.3   危险的薄冰][10.3 1] ##

有些使用借用的情况会出现问题。这是对解释器的盲目理解所导致的，因为拥有者往往提前释放了引用。

首先而最重要的情况是使用 Py\_DECREF() 来释放一个本来是借用的对象，比如列表中的元素:

void
    bug(PyObject* list) {
        PyObject* item=PyList_GetItem(list,0);
        PyList_SetItem(list,1,PyInt_FromLong(0L));
        PyObject_Print(item,stdout,0); /* BUG! */
    }

这个函数首先借用了 list\[0\] ，然后把 list\[1\] 替换为值0，最后打印借用的引用。看起来正确么，不是！

我们来跟踪一下 PyList\_SetItem() 的控制流，列表拥有所有元素的引用，所以当项目1被替换时，他就释放了原始项目1。而原始项目1是一个用户定义类的实例，假设这个类定义包含 \_\_del\_\_() 方法。如果这个类的实例引用计数为1，处理过程会调用 \_\_del\_\_() 方法。

因为使用python编写，所以 \_\_del\_\_() 中可以用任何python代码来完成释放工作。替换元素的过程会执行 del list\[0\] ，即减掉了对象的最后一个引用，然后就可以释放内存了。

知道问题后，解决方案就出来了：临时增加引用计数。正确的版本如下:

void
    no_bug(PyObject* list) {
        PyObject* item=PyList_GetItem(list,0);
        Py_INCREF(item);
        PyList_SetItem(list,1,PyInt_FromLong(0L));
        PyObject_Print(item,stdout,0);
        Py_DECREF(item);
    }

这是一个真实的故事，旧版本的Python中多处包含这个问题，让guido花费大量时间研究 \_\_del\_\_() 为什么失败了。

第二种情况的问题出现在多线程中的借用引用。一般来说，python中的多线程之间并不能互相影响对方，因为存在一个GIL。不过，这可能使用宏 Py\_BEGIN\_ALLOW\_THREADS 来临时释放锁，最后通过宏 Py\_END\_ALLOW\_THREADS 来再申请锁，这在IO调用时很常见，允许其他线程使用处理器而不是等待IO结束。很明显，下面的代码与前面的问题相同:

void
    bug(PyObject* list) {
        PyObject* item=PyList_GetItem(list,0);
        Py_BEGIN_ALLOW_THREADS
        //一些IO阻塞调用
        Py_END_ALLOW_THREADS
        PyObject_Print(item,stdout,0); /*BUG*/
    }

## [10.4   NULL指针][10.4_NULL 1] ##

一般来说，函数接受的参数并不希望你传递一个NULL指针进来，这会出错的。函数的返回对象引用返回NULL则代表发生了异常。这是Python的机制，毕竟，一个函数如果执行出错了，那么也没有必要多解释了，浪费时间。(注：彪悍的异常也不需要解释)

最好的测试NULL的方法就是在代码里面，一个指针如果收到了NULL，例如 malloc() 或其他函数，则表示发生了异常。

宏 Py\_INCREF() 和 Py\_DECREF() 并不检查NULL指针，不过还好， Py\_XINCREF() 和 Py\_XDECREF() 会检查。

检查特定类型的宏，形如 Pytype\_Check() 也不检查NULL指针，因为这个检查是多余的。

C函数的调用机制确保传递的参数列表(也就是args参数)用不为NULL，事实上，它总是一个tuple。

而把NULL扔到Python用户那里可就是一个非常严重的错误了。

# [11   使用C++编写扩展][11_C 1] #

有时候需要用C++编写Python扩展模块。不过有一些严格的限制。如果Python解释器的主函数是使用C编译器编译和连接的，那么全局和静态对象的构造函数将无法使用。而主函数使用C++编译器时则不会有这个问题。被Python调用的函数，特别是模块初始化函数，必须声明为 extern “C” 。没有必要在Python头文件中使用 extern “C” 因为在使用C++编译器时会自动加上 \_\_cplusplus 这个定义，而一般的C++编译器一般都会设置这个符号。

# [12   提供给其他模块以C API][12_C API 1] #

很多模块只是提供给Python使用的函数和新类型，但是偶尔也有可能被其他扩展模块所调用。例如一个模块实现了 “collection” 类型，可以像list一样工作而没有顺序。有如标准Python中的list类型一样，提供的C接口可以让扩展模块创建和管理list，这个新的类型也需要有C函数以供其他扩展模块直接管理。

初看这个功能可能以为很简单：只要写这些函数就行了(不需要声明为静态)，提供适当的头文件，并注释C的API。当然，如果所有的扩展模块都是静态链接到Python解释器的话，这当然可以正常工作。但是当其他扩展模块是动态链接库时，定义在一个模块中的符号，可能对另外一个模块来说并不是可见的。而这个可见性又是依赖操作系统实现的，一些操作系统对Python解释器使用全局命名空间和所有的扩展模块(例如Windows)，也有些系统则需要明确的声明模块的导出符号表(AIX就是个例子)，或者提供一个不同策略的选择(大多数的Unices)。即便这些符号是全局可见的，拥有函数的模块，也可能尚未载入。

为了可移植性，不要奢望任何符号会对外可见。这意味着模块中所有的符号都声明为 **static** ，除了模块的初始化函数以外，这也是为了避免各个扩展模块之间的符号名称冲突。这也意味着必须以其他方式导出扩展模块的符号。

Python提供了一种特殊的机制，以便在扩展模块间传递C级别的信息(指针)： **CObject** 。一个CObject是一个Python的数据类型，存储了任意类型指针(void\*)。CObject可以只通过C API来创建和存取，但是却可以像其他Python对象那样来传递。在特别的情况下，他们可以被赋予一个扩展模块命名空间内的名字。其他扩展模块随后可以导入这个模块，获取这个名字的值，然后得到CObject中保存的指针。

通过CObject有很多种方式导出扩展模块的C API。每个名字都可以得到他自己的CObject，或者可以把所有的导出C API放在一个CObject指定的数组中来发布。所以可以有很多种方法导出C API。

如下的示例代码展示了把大部分的重负载任务交给扩展模块，作为一个很普通的扩展模块的例子。他保存了所有的C API的指针到一个数组中，而这个数组的指针存储在CObject中。对应的头文件提供了一个宏以管理导入模块和获取C API的指针，客户端模块只需要在存取C API之前执行这个宏就可以了。

这个导出模块是修改自1.1节的spam模块。函数 spam.system() 并不是直接调用C库的函数 system() ，而是调用 PySpam\_System() ，提供了更加复杂的功能。这个函数 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"

这个宏定义是告诉头文件需要作为导出模块，而不是客户端模块。最终模块的初始化函数必须管理初始化C API指针数组的初始化:

PyMODINIT_FUNC
    initspam(void)
    {
        PyObject *m;
        static void *PySpam_API[PySpam_API_pointers];
        PyObject *c_api_object;
    
        m = Py_InitModule("spam", SpamMethods);
        if (m == NULL)
            return;
    
        /* 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;
        m=Py_InitModule("client",ClientMethods);
        if (m==NULL)
            return;
        if (import_spam()<0)
            return;
        /*其他初始化语句*/
    }

这样做的缺点是 spammodule.h 有点复杂。不过这种结构却可以方便的用于其他导出函数，所以学着用一次也就好了。

最后需要提及的是CObject提供的一些附加函数，用于CObject指定的内存块的分配和释放。详细信息可以参考Python的C API参考手册的CObject一节，和CObject的实现，参考文件 Include/cobject.h 和 Objects/cobject.c 。

[http_gashero.yeax.com_p_38]: http://gashero.yeax.com/?p=38
[1]: http://writeblog.csdn.net/#id2
[2]: http://writeblog.csdn.net/#id3
[3]: http://writeblog.csdn.net/#id4
[4]: http://writeblog.csdn.net/#id5
[5]: http://writeblog.csdn.net/#id6
[6_C_Python]: http://writeblog.csdn.net/#c-python
[7]: http://writeblog.csdn.net/#id7
[8]: http://writeblog.csdn.net/#id8
[9]: http://writeblog.csdn.net/#id9
[10]: http://writeblog.csdn.net/#id10
[10.1_Python]: http://writeblog.csdn.net/#python
[10.2]: http://writeblog.csdn.net/#id11
[10.3]: http://writeblog.csdn.net/#id12
[10.4_NULL]: http://writeblog.csdn.net/#null
[11_C]: http://writeblog.csdn.net/#c
[12_C API]: http://writeblog.csdn.net/#c-api
[1 1]: http://writeblog.csdn.net/#id13
[2 1]: http://writeblog.csdn.net/#id14
[3 1]: http://writeblog.csdn.net/#id15
[4 1]: http://writeblog.csdn.net/#id16
[5 1]: http://writeblog.csdn.net/#id17
[6_C_Python 1]: http://writeblog.csdn.net/#id18
[7 1]: http://writeblog.csdn.net/#id19
[8 1]: http://writeblog.csdn.net/#id20
[phibrick_hks.com]: mailto:phibrick@hks.com
[9 1]: http://writeblog.csdn.net/#id21
[10 1]: http://writeblog.csdn.net/#id22
[10.1_Python 1]: http://writeblog.csdn.net/#id23
[10.2 1]: http://writeblog.csdn.net/#id24
[10.3 1]: http://writeblog.csdn.net/#id25
[10.4_NULL 1]: http://writeblog.csdn.net/#id26
[11_C 1]: http://writeblog.csdn.net/#id27
[12_C API 1]: http://writeblog.csdn.net/#id28