Capsule 對(duì)象?

有關(guān)使用這些對(duì)象的更多信息請(qǐng)參閱 給擴(kuò)展模塊提供C API

3.1 新版功能.

type PyCapsule?

這個(gè) PyObject 的子類型代表一個(gè)隱藏的值,適用于需要將隱藏值(作為 void* 指針)通過 Python 代碼傳遞到其他 C 代碼的 C 擴(kuò)展模塊。 它常常被用來(lái)讓在一個(gè)模塊中定義的 C 函數(shù)指針在其他模塊中可用,這樣就可以使用常規(guī)導(dǎo)入機(jī)制來(lái)訪問在動(dòng)態(tài)加載的模塊中定義的 C API。

type PyCapsule_Destructor?
Part of the Stable ABI.

Capsule 的析構(gòu)器回調(diào)的類型。 定義如下:

typedef void (*PyCapsule_Destructor)(PyObject *);

參閱 PyCapsule_New() 來(lái)獲取 PyCapsule_Destructor 返回值的語(yǔ)義。

int PyCapsule_CheckExact(PyObject *p)?

如果參數(shù)是一個(gè) PyCapsule 則返回真值。 此函數(shù)總是會(huì)成功執(zhí)行。

PyObject *PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)?
Return value: New reference. Part of the Stable ABI.

創(chuàng)建一個(gè)封裝了 pointerPyCapsulepointer 參考可以不為 NULL。

在失敗時(shí)設(shè)置一個(gè)異常并返回 NULL

字符串 name 可以是 NULL 或是一個(gè)指向有效的 C 字符串的指針。 如果不為 NULL,則此字符串必須比 capsule 長(zhǎng)(雖然也允許在 destructor 中釋放它。)

如果 destructor 參數(shù)不為 NULL,則當(dāng)它被銷毀時(shí)將附帶 capsule 作為參數(shù)來(lái)調(diào)用。

如果此 capsule 將被保存為一個(gè)模塊的屬性,則 name 應(yīng)當(dāng)被指定為 modulename.attributename。 這將允許其他模塊使用 PyCapsule_Import() 來(lái)導(dǎo)入此 capsule。

void *PyCapsule_GetPointer(PyObject *capsule, const char *name)?
Part of the Stable ABI.

提取保存在 capsule 中的 pointer。 在失敗時(shí)設(shè)置一個(gè)異常并返回 NULL。

name 形參必須與保存在 capsule 中的名稱進(jìn)行精確比較。 如果保存在 capsule 中的名稱為 NULL,則傳入的 name 也必須為 NULL。 Python 會(huì)使用 C 函數(shù) strcmp() 來(lái)比較 capsule 名稱。

PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)?
Part of the Stable ABI.

返回保存在 capsule 中的當(dāng)前析構(gòu)器。 在失敗時(shí)設(shè)置一個(gè)異常并返回 NULL。

capsule 具有 NULL 析構(gòu)器是合法的。 這會(huì)使得 NULL 返回碼有些歧義;請(qǐng)使用 PyCapsule_IsValid()PyErr_Occurred() 來(lái)消除歧義。

void *PyCapsule_GetContext(PyObject *capsule)?
Part of the Stable ABI.

返回保存在 capsule 中的當(dāng)前上下文。 在失敗時(shí)設(shè)置一個(gè)異常并返回 NULL。

capsule 具有 NULL 上下文是全法的。 這會(huì)使得 NULL 返回碼有些歧義;請(qǐng)使用 PyCapsule_IsValid()PyErr_Occurred() 來(lái)消除歧義。

const char *PyCapsule_GetName(PyObject *capsule)?
Part of the Stable ABI.

返回保存在 capsule 中的當(dāng)前名稱。 在失敗時(shí)設(shè)置一個(gè)異常并返回 NULL。

capsule 具有 NULL 名稱是合法的。 這會(huì)使得 NULL 返回碼有些歧義;請(qǐng)使用 PyCapsule_IsValid()PyErr_Occurred() 來(lái)消除歧義。

void *PyCapsule_Import(const char *name, int no_block)?
Part of the Stable ABI.

Import a pointer to a C object from a capsule attribute in a module. The name parameter should specify the full name to the attribute, as in module.attribute. The name stored in the capsule must match this string exactly.

成功時(shí)返回 capsule 的內(nèi)部 指針。 在失敗時(shí)設(shè)置一個(gè)異常并返回 NULL

在 3.3 版更改: no_block has no effect anymore.

int PyCapsule_IsValid(PyObject *capsule, const char *name)?
Part of the Stable ABI.

確定 capsule 是否是一個(gè)有效的。 有效的 capsule 必須不為 NULL,傳遞 PyCapsule_CheckExact(),在其中存儲(chǔ)一個(gè)不為 NULL 的指針,并且其內(nèi)部名稱與 name 形參相匹配。 (請(qǐng)參閱 PyCapsule_GetPointer() 了解如何對(duì) capsule 名稱進(jìn)行比較的有關(guān)信息。)

換句話說(shuō),如果 PyCapsule_IsValid() 返回真值,則任何對(duì)訪問器(以 PyCapsule_Get() 開頭的任何函數(shù))的調(diào)用都保證會(huì)成功。

如果對(duì)象有效并且匹配傳入的名稱則返回非零值。 否則返回 0。 此函數(shù)一定不會(huì)失敗。

int PyCapsule_SetContext(PyObject *capsule, void *context)?
Part of the Stable ABI.

capsule 內(nèi)部的上下文指針設(shè)為 context。

成功時(shí)返回 0。 失敗時(shí)返回非零值并設(shè)置一個(gè)異常。

int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)?
Part of the Stable ABI.

capsule 內(nèi)部的析構(gòu)器設(shè)為 destructor。

成功時(shí)返回 0。 失敗時(shí)返回非零值并設(shè)置一個(gè)異常。

int PyCapsule_SetName(PyObject *capsule, const char *name)?
Part of the Stable ABI.

capsule 內(nèi)部的名稱設(shè)為 name。 如果不為 NULL,則名稱的存在期必須比 capsule 更長(zhǎng)。 如果之前保存在 capsule 中的 name 不為 NULL,則不會(huì)嘗試釋放它。

成功時(shí)返回 0。 失敗時(shí)返回非零值并設(shè)置一個(gè)異常。

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)?
Part of the Stable ABI.

capsule 內(nèi)部的空指針設(shè)為 pointer。 指針不可為 NULL。

成功時(shí)返回 0。 失敗時(shí)返回非零值并設(shè)置一個(gè)異常。