胶囊 — Python 文档

来自菜鸟教程
Python/docs/3.7/c-api/capsule
跳转至:导航、​搜索

胶囊

有关使用这些对象的更多信息,请参阅 为扩展模块提供 C API

3.1 版中的新功能。


type PyCapsule
PyObject 的这个子类型表示不透明值,对于需要通过 Python 代码将不透明值(作为 void* 指针)传递给其他 C 代码的 C 扩展模块非常有用。 它通常用于使在一个模块中定义的 C 函数指针可用于其他模块,因此常规导入机制可用于访问动态加载模块中定义的 C API。
type PyCapsule_Destructor

胶囊的析构函数回调的类型。 定义为:

typedef void (*PyCapsule_Destructor)(PyObject *);

有关 PyCapsule_Destructor 回调的语义,请参阅 PyCapsule_New()

int PyCapsule_CheckExact(PyObject *p)
如果其参数是 PyCapsule,则返回 true。
PyObject *PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)

创建一个 PyCapsule 封装 指针pointer 参数可能不是 NULL

失败时,设置异常并返回 NULL

name 字符串可以是 NULL 或指向有效 C 字符串的指针。 如果非 NULL,则此字符串必须比胶囊存活时间长。 (尽管允许在 析构函数 中释放它。)

如果 destructor 参数不是 NULL,它会在被销毁时以胶囊为参数被调用。

如果此胶囊将作为模块的属性存储,则 name 应指定为 modulename.attributename。 这将使其他模块能够使用 PyCapsule_Import() 导入胶囊。

void *PyCapsule_GetPointer(PyObject *capsule, const char *name)

检索存储在胶囊中的 指针 。 失败时,设置异常并返回 NULL

name 参数必须与存储在胶囊中的名称完全一致。 如果capsule中存储的名字是NULL,那么传入的name也必须是NULL。 Python 使用 C 函数 strcmp() 来比较胶囊名称。

PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)

返回存储在胶囊中的当前析构函数。 失败时,设置异常并返回 NULL

胶囊具有 NULL 析构函数是合法的。 这使得 NULL 返回码有些模糊; 使用 PyCapsule_IsValid()PyErr_Occurred() 来消除歧义。

void *PyCapsule_GetContext(PyObject *capsule)

返回存储在胶囊中的当前上下文。 失败时,设置异常并返回 NULL

胶囊具有 NULL 上下文是合法的。 这使得 NULL 返回码有些模糊; 使用 PyCapsule_IsValid()PyErr_Occurred() 来消除歧义。

const char *PyCapsule_GetName(PyObject *capsule)

返回存储在胶囊中的当前名称。 失败时,设置异常并返回 NULL

胶囊具有 NULL 名称是合法的。 这使得 NULL 返回码有些模糊; 使用 PyCapsule_IsValid()PyErr_Occurred() 来消除歧义。

void *PyCapsule_Import(const char *name, int no_block)

从模块中的胶囊属性导入指向 C 对象的指针。 name 参数应指定属性的全名,如 module.attribute。 存储在胶囊中的 name 必须与此字符串完全匹配。 如果 no_block 为真,则在不阻塞的情况下导入模块(使用 PyImport_ImportModuleNoBlock())。 如果 no_block 为 false,则按惯例导入模块(使用 PyImport_ImportModule())。

成功时返回胶囊的内部 指针 。 失败时,设置异常并返回 NULL

int PyCapsule_IsValid(PyObject *capsule, const char *name)

确定 capsule 是否是有效的 Capsule。 一个有效的胶囊是非NULL,通过PyCapsule_CheckExact(),其中存储了一个非NULL指针,其内部名称匹配名称[ X158X] 参数。 (有关如何比较胶囊名称的信息,请参阅 PyCapsule_GetPointer()。)

换句话说,如果 PyCapsule_IsValid() 返回真值,则保证调用任何访问器(以 PyCapsule_Get() 开头的任何函数)成功。

如果对象有效并且与传入的名称匹配,则返回一个非零值。 否则返回 0。 此功能不会失败。

int PyCapsule_SetContext(PyObject *capsule, void *context)

capsule 内的上下文指针设置为 context

成功返回 0。 返回非零值并在失败时设置异常。

int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)

capsule 内的析构函数设置为 destructor

成功返回 0。 返回非零值并在失败时设置异常。

int PyCapsule_SetName(PyObject *capsule, const char *name)

capsule 内的名称设置为 name。 如果非NULL,则名称必须比胶囊长。 如果之前存储在胶囊中的 name 不是 NULL,则不会尝试释放它。

成功返回 0。 返回非零值并在失败时设置异常。

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)

capsule 内的 void 指针设置为 pointer。 指针可能不是 NULL

成功返回 0。 返回非零值并在失败时设置异常。