python c++混合编程文档缩减版笔记 - 1

官方文档

A Simple Example

• The C extension interface is specific to CPython, and extension modules do not work on other Python implementations.

  • 使用ctypes或者cffi有更好的可移植性

• An important convention throughout the Python interpreter is the following: when a function fails, it should set an exception condition and return an error value (usually a NULL pointer). Exceptions are stored in a static global variable inside the interpreter; if this variable is NULL no exception has occurred. A second global variable stores the “associated value” of the exception (the second argument to raise). A third variable contains the stack traceback in case the error originated in Python code. These three variables are the C equivalents of the result in Python of sys.exc_info() (see the section on module sys in the Python Library Reference). It is important to know about them to understand how errors are passed around.

• 几个常见的错误函数

  • PyErr_SetString()
  • PyErr_SetFromErrno()
  • PyErr_SetObject()
  • PyErr_Occurred()
  • PyErr_Clear()
  • You don’t need to Py_INCREF() the objects passed to any of these functions.

• malloc 之类的函数内存分配失败时必须调用 PyErr_NoMemory()，所有的对象创建函数比如PyLong_FromLong()等是这样实现的

• 除掉一些 PyArg_ParseTuple() 之类的函数，函数返回值是>=0成功，<0失败，和unix保持一致

• be careful to clean up garbage (by making Py_XDECREF() or Py_DECREF() calls for objects you have already created) when you return an error indicator!

• 错误类型不要瞎报

• 可以自定义模块异常

• When a function f that calls another function g detects that the latter fails, f should itself return an error value (usually NULL or -1). It should not call one of the PyErr_() functions — one has already been called by g. f’s caller is then supposed to also return an error indication to its caller, again without calling PyErr_(), and so on — the most detailed cause of the error was already reported by the function that first detected it.

  • 这也是PyArg_ParseTuple()失败直接返回NULL的原因，PyArg_ParseTuple()会自己触发异常
  • 可以发现 return NULL 和 PyErr 哥俩好

• If you have a C function that returns no useful argument (a function returning void), the corresponding Python function must return None. You need this idiom to do so (which is implemented by the Py_RETURN_NONE macro):

  Py_INCREF(Py_None);
  return Py_None;
  

• Note the third entry (METH_VARARGS). This is a flag telling the interpreter the calling convention to be used for the C function. It should normally always be METH_VARARGS or METH_VARARGS | METH_KEYWORDS;

• The METH_KEYWORDS 需要用PyArg_ParseTupleAndKeywords()

• When the Python program imports module spam for the first time, PyInit_spam() is called.

• When embedding Python, the PyInit_spam() function is not called automatically unless there’s an entry in the PyImport_Inittab table. To add the module to the initialization table, use PyImport_AppendInittab().

Calling Python Functions from C

• This function must be registered with the interpreter using the METH_VARARGS flag

• The macros Py_XINCREF() and Py_XDECREF() increment/decrement the reference count of an object and are safe in the presence of NULL pointers

• Later, when it is time to call the function, you call the C function PyObject_CallObject(). This function has two arguments, both pointers to arbitrary Python objects: the Python function, and the argument list. The argument list must always be a tuple object, whose length is the number of arguments. To call the Python function with no arguments, pass in NULL, or an empty tuple; to call it with one argument, pass a singleton tuple. Py_BuildValue() returns a tuple when its format string consists of zero or more format codes between parentheses.

• The return value of PyObject_CallObject() is “new”: either it is a brand new object, or it is an existing object whose reference count has been incremented. So, unless you want to save it in a global variable, you should somehow Py_DECREF() the result, even (especially!) if you are not interested in its value.

  • PyObject_CallObject()的返回值如果你不需要的话应该Py_DECREF()，但是需要对返回值做NULL判定，所以可以用Py_XDECREF()

Extracting Parameters in Extension Functions

• PyArg_ParseTuple()的参数类型必须对上，对不上可能导致崩溃或者其他未定义行为

• Note that any Python object references which are provided to the caller are borrowed references; do not decrement their reference count!

• int PyArg_ParseTupleAndKeywords(PyObject *arg, PyObject *kwdict, const char *format, char *kwlist[], …);

• kwlist参数是以NULL结尾的字符串列表

• PyArg_ParseTupleAndKeywords()使用关键字参数时无法解析嵌套的元组！传入的关键字参数不在kwlist中，这将导致引发TypeError。

• Py_BuildValue的参数只能是值不能是指针

Reference Counts

• Py_DECREF() also frees the object when the count reaches zero. For flexibility, it doesn’t call free() directly — rather, it makes a call through a function pointer in the object’s type object. For this purpose (and others), every object also contains a pointer to its type object.
• Nobody “owns” an object; however, you can own a reference to an object.
• The owner of a reference is responsible for calling Py_DECREF() when the reference is no longer needed. Ownership of a reference can be transferred. There are three ways to dispose of an owned reference: pass it on, store it, or call Py_DECREF(). Forgetting to dispose of an owned reference creates a memory leak.
• It is also possible to borrow [2] a reference to an object. The borrower of a reference should not call Py_DECREF(). The borrower must not hold on to the object longer than the owner from which it was borrowed. Using a borrowed reference after the owner has disposed of it risks using freed memory and should be avoided completely [3].
• The advantage of borrowing over owning a reference is that you don’t need to take care of disposing of the reference on all possible paths through the code — in other words, with a borrowed reference you don’t run the risk of leaking when a premature exit is taken. The disadvantage of borrowing over owning is that there are some subtle situations where in seemingly correct code a borrowed reference can be used after the owner from which it was borrowed has in fact disposed of it.
• A borrowed reference can be changed into an owned reference by calling Py_INCREF(). This does not affect the status of the owner from which the reference was borrowed — it creates a new owned reference, and gives full owner responsibilities (the new owner must dispose of the reference properly, as well as the previous owner).

Ownership Rules

• Whenever an object reference is passed into or out of a function, it is part of the function’s interface specification whether ownership is transferred with the reference or not.
• Most functions that return a reference to an object pass on ownership with the reference. In particular, all functions whose function it is to create a new object, such as PyLong_FromLong() and Py_BuildValue(), pass ownership to the receiver.
• Many functions that extract objects from other objects also transfer ownership with the reference, for instance PyObject_GetAttrString().
  • PyTuple_GetItem(), PyList_GetItem(), PyDict_GetItem(), and PyDict_GetItemString() all return references that you borrow from the tuple, list or dictionary.
• The function PyImport_AddModule() also returns a borrowed reference, even though it may actually create the object it returns: this is possible because an owned reference to the object is stored in sys.modules.
• When you pass an object reference into another function, in general, the function borrows the reference from you — if it needs to store it, it will use Py_INCREF() to become an independent owner.
  • There are exactly two important exceptions to this rule: PyTuple_SetItem() and PyList_SetItem(). These functions take over ownership of the item passed to them — even if they fail! (Note that PyDict_SetItem() and friends don’t take over ownership — they are “normal.”)
• When a C function is called from Python, it borrows references to its arguments from the caller. The caller owns a reference to the object, so the borrowed reference’s lifetime is guaranteed until the function returns. Only when such a borrowed reference must be stored or passed on, it must be turned into an owned reference by calling Py_INCREF().
• The object reference returned from a C function that is called from Python must be an owned reference — ownership is transferred from the function to its caller.
• 陷阱

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

  看起来 item 是借用于 list 中的最后 print 没有 bug，但是这里隐藏的问题是 SetItem 会转移引用，如果旧的 list[1] 刚好没有其他引用被释放了，会执行list[1].__del__的方法，那这个时候就尴尬了，你不知道这个__del__会做什么万一把item给释放了那可就有意思了。正常的做法如下。

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

NULL Pointers

• 时刻注意NULLpointer的检查，除了 Py_XINCREF() and Py_XDECREF() 别的都不会检查，要从源头source检查NULL

Providing a C API for an Extension Module

• 这部分我不怎么用，后面有需要了再看

#define PY_SSIZE_T_CLEAN
#include static PyObject *SpamError;static PyObject *spam_system(PyObject *self, PyObject *args) {const char *command;int sts;if (!PyArg_ParseTuple(args, "s", &command)) return NULL;sts = system(command);if (sts < 0) {PyErr_SetString(SpamError, "System command failed");return NULL;}return PyLong_FromLong(sts);
}static PyMethodDef SpamMethods[] = {{"system", spam_system, METH_VARARGS, "Execute a shell command."},{NULL, NULL, 0, NULL} /* Sentinel */
};static struct PyModuleDef spammodule = {PyModuleDef_HEAD_INIT, "spam", /* name of module */"spam_doc",                    /* module documentation, may be NULL */-1, /* size of per-interpreter state of the module,or -1 if the module keeps state in global variables. */SpamMethods};PyMODINIT_FUNC PyInit_spam(void) {PyObject *m;m = PyModule_Create(&spammodule);if (m == NULL) return NULL;SpamError = PyErr_NewException("spam.error", NULL, NULL);Py_XINCREF(SpamError);if (PyModule_AddObject(m, "error", SpamError) < 0) {Py_XDECREF(SpamError);Py_CLEAR(SpamError);Py_DECREF(m);return NULL;}return m;
}int main1(int argc, char *argv[]) {wchar_t *program = Py_DecodeLocale(argv[0], NULL);if (program == NULL) {fprintf(stderr, "Fatal error: cannot decode argv[0]\n");exit(1);}/* Add a built-in module, before Py_Initialize */if (PyImport_AppendInittab("spam", PyInit_spam) == -1) {fprintf(stderr, "Error: could not extend in-built modules table\n");exit(1);}/* Pass argv[0] to the Python interpreter */Py_SetProgramName(program);/* Initialize the Python interpreter.  Required.If this step fails, it will be a fatal error. */Py_Initialize();/* Optionally import the module; alternatively,import can be deferred until the embedded scriptimports it. */auto pmodule = PyImport_ImportModule("spam");if (!pmodule) {PyErr_Print();fprintf(stderr, "Error: could not import module 'spam'\n");}PyMem_RawFree(program);return 0;
}int main(int argc, char *argv[]) {main1(argc, argv);// main2(argc, argv);
}//
static PyObject *keywdarg_parrot(PyObject *self, PyObject *args,PyObject *keywds) {int voltage;const char *state = "a stiff";const char *action = "voom";const 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_RETURN_NONE;
}static PyMethodDef keywdarg_methods[] = {/* The cast of the function is necessary since PyCFunction values* only take two PyObject* parameters, and keywdarg_parrot() takes* three.*/{"parrot", (PyCFunction)(void (*)(void))keywdarg_parrot,METH_VARARGS | METH_KEYWORDS, "Print a lovely skit to standard output."},{NULL, NULL, 0, NULL} /* sentinel */
};static struct PyModuleDef keywdargmodule = {PyModuleDef_HEAD_INIT, "keywdarg",NULL, -1, keywdarg_methods};PyMODINIT_FUNC PyInit_keywdarg(void) {return PyModule_Create(&keywdargmodule);
}
//

#define PY_SSIZE_T_CLEAN
#include 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);        /* Add a reference to new callback */Py_XDECREF(my_callback); /* Dispose of previous callback */my_callback = temp;      /* Remember new callback *//* Boilerplate to return "None" */Py_INCREF(Py_None);result = Py_None;}return result;
}static PyObject *PyObject_Call_CallObject_F() {int arg;PyObject *arglist;PyObject *dict;PyObject *result;arg = 123;/* Time to call the callback */arglist = Py_BuildValue("(i)", arg);result = PyObject_CallObject(my_callback, arglist);dict = Py_BuildValue("{s:i}", "name", arg);result = PyObject_Call(my_callback, NULL, dict);Py_DECREF(arglist);if (result == NULL) return NULL; /* Pass error back */// use resultPy_DECREF(result);
}

本文来自互联网用户投稿，文章观点仅代表作者本人，不代表本站立场，不承担相关法律责任。如若转载，请注明出处。 如若内容造成侵权/违法违规/事实不符，请点击【内容举报】进行投诉反馈！