使對象類型支持循環垃圾回收 · Python3.7.3官方文檔簡體中文

### 導航 - [索引](../genindex.xhtml "總目錄") - [模塊](../py-modindex.xhtml "Python 模塊索引") | - [下一頁](apiabiversion.xhtml "API 和 ABI 版本管理") | - [上一頁](typeobj.xhtml "Type 對象") | - ![](https://box.kancloud.cn/a721fc7ec672275e257bbbfde49a4d4e_16x16.png) - [Python](https://www.python.org/) ? - zh\_CN 3.7.3 [文檔](../index.xhtml) ? - [Python/C API 參考手冊](index.xhtml) ? - [對象實現支持](objimpl.xhtml) ? - $('.inline-search').show(0); | # 使對象類型支持循環垃圾回收 Python 對循環引用的垃圾檢測與回收需要“容器”對象類型的支持，此類型的容器對象中可能包含其它容器對象。不保存其它對象的引用的類型，或者只保存原子類型（如數字或字符串）的引用的類型，不需要顯式提供垃圾回收的支持。若要創建一個容器類，類型對象的 [`tp_flags`](typeobj.xhtml#c.PyTypeObject.tp_flags "PyTypeObject.tp_flags") 字段必須包含 [`Py_TPFLAGS_HAVE_GC`](typeobj.xhtml#Py_TPFLAGS_HAVE_GC "Py_TPFLAGS_HAVE_GC") 并提供一個 [`tp_traverse`](typeobj.xhtml#c.PyTypeObject.tp_traverse "PyTypeObject.tp_traverse") 處理的實現。如果該類型的實例是可變的，還需要實現 [`tp_clear`](typeobj.xhtml#c.PyTypeObject.tp_clear "PyTypeObject.tp_clear") 。 `Py_TPFLAGS_HAVE_GC`設置了此標志位的類型的對象必須符合此處記錄的規則。為方便起見，下文把這些對象稱為容器對象。容器類型的構造函數必須符合兩個規則： 1. 必須使用 [`PyObject_GC_New()`](#c.PyObject_GC_New "PyObject_GC_New") 或 [`PyObject_GC_NewVar()`](#c.PyObject_GC_NewVar "PyObject_GC_NewVar") 為這些對象分配內存。 2. 初始化了所有可能包含其他容器的引用的字段后，它必須調用 [`PyObject_GC_Track()`](#c.PyObject_GC_Track "PyObject_GC_Track") 。 TYPE\* `PyObject_GC_New`(TYPE, [PyTypeObject](type.xhtml#c.PyTypeObject "PyTypeObject") *\*type*)類似于 [`PyObject_New()`](allocation.xhtml#c.PyObject_New "PyObject_New") ，適用于設置了 [`Py_TPFLAGS_HAVE_GC`](typeobj.xhtml#Py_TPFLAGS_HAVE_GC "Py_TPFLAGS_HAVE_GC") 標簽的容器對象。 TYPE\* `PyObject_GC_NewVar`(TYPE, [PyTypeObject](type.xhtml#c.PyTypeObject "PyTypeObject") *\*type*, Py\_ssize\_t *size*)類似于 [`PyObject_NewVar()`](allocation.xhtml#c.PyObject_NewVar "PyObject_NewVar") ，適用于設置了 [`Py_TPFLAGS_HAVE_GC`](typeobj.xhtml#Py_TPFLAGS_HAVE_GC "Py_TPFLAGS_HAVE_GC") 標簽的容器對象。 TYPE\* `PyObject_GC_Resize`(TYPE, [PyVarObject](structures.xhtml#c.PyVarObject "PyVarObject") *\*op*, Py\_ssize\_t *newsize*)為 [`PyObject_NewVar()`](allocation.xhtml#c.PyObject_NewVar "PyObject_NewVar") 分配的對象重新設置大小，并返回調整大小后的對象。當重分配失敗時返回 *NULL* 。*op* 必須沒有被垃圾回收器監控。 void `PyObject_GC_Track`([PyObject](structures.xhtml#c.PyObject "PyObject") *\*op*)把對象 *op* 加入到垃圾回收器跟蹤的容器對象中。對象在被回收器跟蹤時必須保持有效的，因為回收器可能在任何時候開始運行。在 [`tp_traverse`](typeobj.xhtml#c.PyTypeObject.tp_traverse "PyTypeObject.tp_traverse") 處理前的所有字段變為有效后，必須調用此函數，通常在靠近構造函數末尾的位置。 void `_PyObject_GC_TRACK`([PyObject](structures.xhtml#c.PyObject "PyObject") *\*op*)[`PyObject_GC_Track()`](#c.PyObject_GC_Track "PyObject_GC_Track") 的宏實現版本。它不能被用于擴展模塊。 3\.6 版后已移除: 這個宏在 Python 3.8 中被移除。同樣的，對象的釋放器必須符合兩個類似的規則： 1. 在引用其它容器的字段失效前，必須調用 [`PyObject_GC_UnTrack()`](#c.PyObject_GC_UnTrack "PyObject_GC_UnTrack") 。 2. 必須使用 [`PyObject_GC_Del()`](#c.PyObject_GC_Del "PyObject_GC_Del") 釋放對象的內存。 void `PyObject_GC_Del`(void *\*op*)釋放對象的內存，該對象初始化時由 [`PyObject_GC_New()`](#c.PyObject_GC_New "PyObject_GC_New") 或 [`PyObject_GC_NewVar()`](#c.PyObject_GC_NewVar "PyObject_GC_NewVar") 分配內存。 void `PyObject_GC_UnTrack`(void *\*op*)從回收器跟蹤的容器對象集合中移除 *op* 對象。請注意可以在此對象上再次調用 [`PyObject_GC_Track()`](#c.PyObject_GC_Track "PyObject_GC_Track") 以將其加回到被跟蹤對象集合。釋放器 ([`tp_dealloc`](typeobj.xhtml#c.PyTypeObject.tp_dealloc "PyTypeObject.tp_dealloc") 句柄) 應當在 [`tp_traverse`](typeobj.xhtml#c.PyTypeObject.tp_traverse "PyTypeObject.tp_traverse") 句柄所使用的任何字段失效之前為對象調用此函數。 void `_PyObject_GC_UNTRACK`([PyObject](structures.xhtml#c.PyObject "PyObject") *\*op*)[`PyObject_GC_UnTrack()`](#c.PyObject_GC_UnTrack "PyObject_GC_UnTrack") 的使用宏實現的版本。不能用于擴展模塊。 3\.6 版后已移除: 這個宏在 Python 3.8 中被移除。 [`tp_traverse`](typeobj.xhtml#c.PyTypeObject.tp_traverse "PyTypeObject.tp_traverse") 處理接收以下類型的函數形參。 int `(*visitproc)`([PyObject](structures.xhtml#c.PyObject "PyObject") *\*object*, void *\*arg*)傳給 [`tp_traverse`](typeobj.xhtml#c.PyTypeObject.tp_traverse "PyTypeObject.tp_traverse") 處理的訪問函數的類型。*object* 是容器中需要被遍歷的一個對象，第三個形參對應于 [`tp_traverse`](typeobj.xhtml#c.PyTypeObject.tp_traverse "PyTypeObject.tp_traverse") 處理的 *arg* 。Python核心使用多個訪問者函數實現循環引用的垃圾檢測，不需要用戶自行實現訪問者函數。 [`tp_traverse`](typeobj.xhtml#c.PyTypeObject.tp_traverse "PyTypeObject.tp_traverse") 處理必須是以下類型： int `(*traverseproc)`([PyObject](structures.xhtml#c.PyObject "PyObject") *\*self*, [visitproc](#c.visitproc "visitproc") *visit*, void *\*arg*)用于容器對象的遍歷函數。在函數的實現中，必須對 *self* 容器內直接包含的每個對象調用 *visit* 函數，容器內的對象作為 *visit* 的形參，*arg* 作為參數。不能使用 *NULL* 對象作為 *visit* 函數的參數。如果 *visit* 返回非零值，此函數需要立即返回此非零值。為了簡化 [`tp_traverse`](typeobj.xhtml#c.PyTypeObject.tp_traverse "PyTypeObject.tp_traverse") 處理的實現，Python提供了一個 [`Py_VISIT()`](#c.Py_VISIT "Py_VISIT") 宏。若要使用這個宏，必須把 [`tp_traverse`](typeobj.xhtml#c.PyTypeObject.tp_traverse "PyTypeObject.tp_traverse") 的參數命名為 *visit* 和 *arg* 。 void `Py_VISIT`([PyObject](structures.xhtml#c.PyObject "PyObject") *\*o*)如果 *o* 不是 *NULL* ，則調用 *visit* 回調函數，并把 *o* 和 *arg* 作為回調函數的參數。如果 *visit* 返回一個非零值，則把此非零值返回上層調用。在使用此宏后， [`tp_traverse`](typeobj.xhtml#c.PyTypeObject.tp_traverse "PyTypeObject.tp_traverse") 處理組織為以下形式： ``` static int my_traverse(Noddy *self, visitproc visit, void *arg) { Py_VISIT(self->foo); Py_VISIT(self->bar); return 0; } ``` The [`tp_clear`](typeobj.xhtml#c.PyTypeObject.tp_clear "PyTypeObject.tp_clear") handler must be of the [`inquiry`](#c.inquiry "inquiry") type, or *NULL*if the object is immutable. int `(*inquiry)`([PyObject](structures.xhtml#c.PyObject "PyObject") *\*self*)丟棄產生循環引用的引用。不可變對象不需要聲明此方法，因為他們不可能直接產生循環引用。需要注意的是，對象在調用此方法后必須仍是有效的（不能對引用只調用 [`Py_DECREF()`](refcounting.xhtml#c.Py_DECREF "Py_DECREF") 方法）。當垃圾回收器檢測到該對象在循環引用中時，此方法會被調用。 ### 導航 - [索引](../genindex.xhtml "總目錄") - [模塊](../py-modindex.xhtml "Python 模塊索引") | - [下一頁](apiabiversion.xhtml "API 和 ABI 版本管理") | - [上一頁](typeobj.xhtml "Type 對象") | - ![](https://box.kancloud.cn/a721fc7ec672275e257bbbfde49a4d4e_16x16.png) - [Python](https://www.python.org/) ? - zh\_CN 3.7.3 [文檔](../index.xhtml) ? - [Python/C API 參考手冊](index.xhtml) ? - [對象實現支持](objimpl.xhtml) ? - $('.inline-search').show(0); | ? [版權所有](../copyright.xhtml) 2001-2019, Python Software Foundation. Python 軟件基金會是一個非盈利組織。 [請捐助。](https://www.python.org/psf/donations/) 最后更新于 5月 21, 2019. [發現了問題](../bugs.xhtml)？使用[Sphinx](http://sphinx.pocoo.org/)1.8.4 創建。