使對(duì)象類型支持循環(huán)垃圾回收?

Python 對(duì)循環(huán)引用的垃圾檢測與回收需要“容器”對(duì)象類型的支持，此類型的容器對(duì)象中可能包含其它容器對(duì)象。不保存其它對(duì)象的引用的類型，或者只保存原子類型（如數(shù)字或字符串）的引用的類型，不需要顯式提供垃圾回收的支持。

若要?jiǎng)?chuàng)建一個(gè)容器類，類型對(duì)象的 tp_flags 字段必須包含 Py_TPFLAGS_HAVE_GC 并提供一個(gè) tp_traverse 處理的實(shí)現(xiàn)。如果該類型的實(shí)例是可變的，還需要實(shí)現(xiàn) tp_clear 。

Py_TPFLAGS_HAVE_GC

設(shè)置了此標(biāo)志位的類型的對(duì)象必須符合此處記錄的規(guī)則。為方便起見，下文把這些對(duì)象稱為容器對(duì)象。

容器類型的構(gòu)造函數(shù)必須符合兩個(gè)規(guī)則：

1. 必須使用 PyObject_GC_New() 或 PyObject_GC_NewVar() 為這些對(duì)象分配內(nèi)存。

2. 初始化了所有可能包含其他容器的引用的字段后，它必須調(diào)用 PyObject_GC_Track() 。

同樣的，對(duì)象的釋放器必須符合兩個(gè)類似的規(guī)則：

1. 在引用其它容器的字段失效前，必須調(diào)用 PyObject_GC_UnTrack() 。

2. 必須使用 PyObject_GC_Del() 釋放對(duì)象的內(nèi)存。

   警告

   如果一個(gè)類型添加了 Py_TPFLAGS_HAVE_GC，則它 必須 實(shí)現(xiàn)至少一個(gè) tp_traverse 句柄或顯式地使用來自其一個(gè)或多個(gè)子類的句柄。

   當(dāng)調(diào)用 PyType_Ready() 或者 API 中某些間接調(diào)用它的函數(shù)例如 PyType_FromSpecWithBases() 或 PyType_FromSpec() 時(shí)解釋器就自動(dòng)填充 tp_flags, tp_traverse 和 tp_clear 字段，如果該類型是繼承自實(shí)現(xiàn)了垃圾回收器協(xié)議的類并且該子類 沒有 包括 Py_TPFLAGS_HAVE_GC 旗標(biāo)的話。

TYPE *PyObject_GC_New(TYPE, PyTypeObject *type)?

類似于 PyObject_New() ，適用于設(shè)置了 Py_TPFLAGS_HAVE_GC 標(biāo)簽的容器對(duì)象。

TYPE *PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)?

類似于 PyObject_NewVar() ，適用于設(shè)置了 Py_TPFLAGS_HAVE_GC 標(biāo)簽的容器對(duì)象。

TYPE *PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize)?

為 PyObject_NewVar() 所分配對(duì)象重新調(diào)整大小。 返回調(diào)整大小后的對(duì)象或在失敗時(shí)返回 NULL。 op 必須尚未被垃圾回收器追蹤。

void PyObject_GC_Track(PyObject *op)?

Part of the Stable ABI.

把對(duì)象 op 加入到垃圾回收器跟蹤的容器對(duì)象中。對(duì)象在被回收器跟蹤時(shí)必須保持有效的，因?yàn)榛厥掌骺赡茉谌魏螘r(shí)候開始運(yùn)行。在 tp_traverse 處理前的所有字段變?yōu)橛行Ш?，必須調(diào)用此函數(shù)，通常在靠近構(gòu)造函數(shù)末尾的位置。

int PyObject_IS_GC(PyObject *obj)?

如果對(duì)象實(shí)現(xiàn)了垃圾回收器協(xié)議則返回非零值，否則返回 0。

如果此函數(shù)返回 0 則對(duì)象無法被垃圾回收器追蹤。

int PyObject_GC_IsTracked(PyObject *op)?

Part of the Stable ABI since version 3.9.

如果 op 對(duì)象的類型實(shí)現(xiàn)了 GC 協(xié)議且 op 目前正被垃圾回收器追蹤則返回 1， 否則返回 0。

這類似于 Python 函數(shù) gc.is_tracked()。

3.9 新版功能.

int PyObject_GC_IsFinalized(PyObject *op)?

Part of the Stable ABI since version 3.9.

如果 op 對(duì)象的類型實(shí)現(xiàn)了 GC 協(xié)議且 op 已經(jīng)被垃圾回收器終結(jié)則返回 1， 否則返回 0。

這類似于 Python 函數(shù) gc.is_finalized()。

3.9 新版功能.

void PyObject_GC_Del(void *op)?

Part of the Stable ABI.

釋放對(duì)象的內(nèi)存，該對(duì)象初始化時(shí)由 PyObject_GC_New() 或 PyObject_GC_NewVar() 分配內(nèi)存。

void PyObject_GC_UnTrack(void *op)?

Part of the Stable ABI.

從回收器跟蹤的容器對(duì)象集合中移除 op 對(duì)象。 請(qǐng)注意可以在此對(duì)象上再次調(diào)用 PyObject_GC_Track() 以將其加回到被跟蹤對(duì)象集合。 釋放器 (tp_dealloc 句柄) 應(yīng)當(dāng)在 tp_traverse 句柄所使用的任何字段失效之前為對(duì)象調(diào)用此函數(shù)。

tp_traverse 處理接收以下類型的函數(shù)形參。

typedef int (*visitproc)(PyObject *object, void *arg)?

Part of the Stable ABI.

傳給 tp_traverse 處理的訪問函數(shù)的類型。object 是容器中需要被遍歷的一個(gè)對(duì)象，第三個(gè)形參對(duì)應(yīng)于 tp_traverse 處理的 arg 。Python核心使用多個(gè)訪問者函數(shù)實(shí)現(xiàn)循環(huán)引用的垃圾檢測，不需要用戶自行實(shí)現(xiàn)訪問者函數(shù)。

tp_traverse 處理必須是以下類型：

typedef int (*traverseproc)(PyObject *self, visitproc visit, void *arg)?

Part of the Stable ABI.

用于容器對(duì)象的遍歷函數(shù)。 它的實(shí)現(xiàn)必須對(duì) self 所直接包含的每個(gè)對(duì)象調(diào)用 visit 函數(shù)，visit 的形參為所包含對(duì)象和傳給處理程序的 arg 值。 visit 函數(shù)調(diào)用不可附帶 NULL 對(duì)象作為參數(shù)。 如果 visit 返回非零值，則該值應(yīng)當(dāng)被立即返回。

為了簡化 tp_traverse 處理的實(shí)現(xiàn)，Python提供了一個(gè) Py_VISIT() 宏。若要使用這個(gè)宏，必須把 tp_traverse 的參數(shù)命名為 visit 和 arg 。

void Py_VISIT(PyObject *o)?

如果 o 不為 NULL，則調(diào)用 visit 回調(diào)函數(shù)，附帶參數(shù) o 和 arg。 如果 visit 返回一個(gè)非零值，則返回該值。 使用此宏之后，tp_traverse 處理程序的形式如下:

static int
my_traverse(Noddy *self, visitproc visit, void *arg)
{
    Py_VISIT(self->foo);
    Py_VISIT(self->bar);
    return 0;
}

tp_clear 處理程序必須為 inquiry 類型，如果對(duì)象不可變則為 NULL。

typedef int (*inquiry)(PyObject *self)?

Part of the Stable ABI.

丟棄產(chǎn)生循環(huán)引用的引用。不可變對(duì)象不需要聲明此方法，因?yàn)樗麄儾豢赡苤苯赢a(chǎn)生循環(huán)引用。需要注意的是，對(duì)象在調(diào)用此方法后必須仍是有效的（不能對(duì)引用只調(diào)用 Py_DECREF() 方法）。當(dāng)垃圾回收器檢測到該對(duì)象在循環(huán)引用中時(shí)，此方法會(huì)被調(diào)用。