支持循环垃圾回收

Python 支持检测和收集包含循环引用的垃圾，这需要来自“容器”对象的类型支持，这些容器对象可能也包含其他对象。不存储对其他对象的引用，或者只存储对原子类型（如数字或字符串）的引用的类型，不需要提供任何显式支持垃圾回收。

要创建容器类型，类型对象的 tp_flags 字段必须包含 Py_TPFLAGS_HAVE_GC 并提供 tp_traverse 处理程序的实现。如果该类型的实例是可变的，则还必须提供 tp_clear 实现。

Py_TPFLAGS_HAVE_GC

具有此标志设置的类型的对象必须符合此处记录的规则。为了方便起见，这些对象将被称为容器对象。

容器类型的构造函数必须符合两条规则

  1. 对象的内存必须使用 PyObject_GC_New 或 PyObject_GC_NewVar 分配。

  2. 一旦所有可能包含对其他容器引用的字段都被初始化，它必须调用 PyObject_GC_Track()。

类似地，对象的析构函数必须符合类似的两条规则

  1. 在引用其他容器的字段失效之前，必须调用 PyObject_GC_UnTrack()。

  2. 对象的内存必须使用 PyObject_GC_Del() 释放。

    警告

    如果类型添加了 Py_TPFLAGS_HAVE_GC，那么它必须至少实现一个 tp_traverse 处理程序，或者显式地使用其子类或子类的处理程序。

    当调用 PyType_Ready() 或一些间接调用它的 API（如 PyType_FromSpecWithBases() 或 PyType_FromSpec()）时，解释器将自动填充 tp_flags、tp_traverse 和 tp_clear 字段，如果该类型继承自实现垃圾回收器协议的类，并且子类不包含 Py_TPFLAGS_HAVE_GC 标志。

PyObject_GC_New(TYPE, typeobj)

类似于 PyObject_New，但适用于设置了 Py_TPFLAGS_HAVE_GC 标志的容器对象。

PyObject_GC_NewVar(TYPE, typeobj, size)

类似于 PyObject_NewVar，但用于设置了 Py_TPFLAGS_HAVE_GC 标志的容器对象。

PyObject *PyUnstable_Object_GC_NewWithExtraData(PyTypeObject *type, size_t extra_size)
这是 不稳定 API。它可能会在次要版本中发生更改，恕不另行通知。

类似于 PyObject_GC_New，但在对象末尾（偏移量为 tp_basicsize）分配 extra_size 字节。分配的内存被初始化为零，除了 Python object header。

额外数据将与对象一起释放，但其他方面不受 Python 管理。

警告

该函数被标记为不稳定，因为实例之后保留额外数据的最终机制尚未确定。对于分配可变数量的字段，建议使用 PyVarObject 和 tp_itemsize。

在 3.12 版本中添加。

PyObject_GC_Resize(TYPE, op, newsize)

调整由 PyObject_NewVar 分配的对象的大小。返回类型为 TYPE*（引用任何 C 类型）的调整大小的对象，或者在失败时返回 NULL。

op 必须是 PyVarObject* 类型，并且尚未被收集器跟踪。newsize 必须是 Py_ssize_t 类型。

void PyObject_GC_Track(PyObject *op)
是 稳定 ABI 的一部分。

将对象 op 添加到收集器跟踪的容器对象集中。收集器可以在意外的时间运行，因此对象在被跟踪时必须有效。这应该在所有由 tp_traverse 处理程序跟踪的字段变为有效后调用，通常在构造函数结束附近。

int PyObject_IS_GC(PyObject *obj)

如果对象实现了垃圾收集器协议，则返回非零值，否则返回 0。

如果此函数返回 0，则垃圾收集器无法跟踪该对象。

int PyObject_GC_IsTracked(PyObject *op)
自版本 3.9 起，作为 稳定 ABI 的一部分。

如果 op 的对象类型实现了 GC 协议，并且 op 当前正在被垃圾收集器跟踪，则返回 1，否则返回 0。

这类似于 Python 函数 gc.is_tracked()。

在版本 3.9 中添加。

int PyObject_GC_IsFinalized(PyObject *op)
自版本 3.9 起，作为 稳定 ABI 的一部分。

如果 op 的对象类型实现了 GC 协议，并且 op 已经被垃圾收集器完成，则返回 1，否则返回 0。

这类似于 Python 函数 gc.is_finalized()。

在版本 3.9 中添加。

void PyObject_GC_Del(void *op)
是 稳定 ABI 的一部分。

释放使用 PyObject_GC_New 或 PyObject_GC_NewVar 分配给对象的内存。

void PyObject_GC_UnTrack(void *op)
是 稳定 ABI 的一部分。

从收集器跟踪的容器对象集中删除对象 op。请注意，可以再次对该对象调用 PyObject_GC_Track() 以将其添加回跟踪对象集中。释放器（tp_dealloc 处理程序）应该在 tp_traverse 处理程序使用的任何字段变得无效之前为此对象调用此函数。

在版本 3.8 中更改: 已从公共 C API 中删除 _PyObject_GC_TRACK() 和 _PyObject_GC_UNTRACK() 宏。

tp_traverse 处理程序接受此类型的函数参数

typedef int (*visitproc)(PyObject *object, void *arg)
是 稳定 ABI 的一部分。

传递给 tp_traverse 处理程序的访问器函数类型。该函数应使用要遍历的对象作为 object 和 tp_traverse 处理程序的第三个参数作为 arg 来调用。Python 核心使用多个访问器函数来实现循环垃圾检测；预计用户不需要编写自己的访问器函数。

tp_traverse 处理程序必须具有以下类型

typedef int (*traverseproc)(PyObject *self, visitproc visit, void *arg)
是 稳定 ABI 的一部分。

容器对象的遍历函数。实现必须对 self 直接包含的每个对象调用 visit 函数，visit 的参数是包含的对象和传递给处理程序的 arg 值。visit 函数不得使用 NULL 对象参数调用。如果 visit 返回非零值，则应立即返回该值。

为了简化编写 tp_traverse 处理程序，提供了一个 Py_VISIT() 宏。为了使用此宏，tp_traverse 实现必须将其参数命名为 visit 和 arg

void Py_VISIT(PyObject *o)

如果 o 不是 NULL，则调用 visit 回调，参数为 o 和 arg。如果 visit 返回非零值，则返回该值。使用此宏，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 类型，或者如果对象是不可变的，则为 NULL。

typedef int (*inquiry)(PyObject *self)
是 稳定 ABI 的一部分。

删除可能导致引用循环的引用。不可变对象不需要定义此方法，因为它们永远不会直接创建引用循环。请注意，在调用此方法后，对象必须仍然有效（不要仅仅对引用调用 Py_DECREF()）。如果检测到此对象参与了引用循环，收集器将调用此方法。

控制垃圾收集器状态

C-API 提供以下函数来控制垃圾收集运行。

Py_ssize_t PyGC_Collect(void)
是 稳定 ABI 的一部分。

如果垃圾收集器已启用，则执行完整的垃圾收集。（请注意，gc.collect() 无条件地运行它。）

返回已收集 + 不可达对象的数目，这些对象无法收集。如果垃圾收集器已禁用或正在收集，则立即返回 0。垃圾收集期间的错误将传递给 sys.unraisablehook。此函数不会引发异常。

int PyGC_Enable(void)
自版本 3.10 起，它是 稳定 ABI 的一部分。

启用垃圾收集器：类似于 gc.enable()。返回先前状态，0 表示禁用，1 表示启用。

在版本 3.10 中添加。

int PyGC_Disable(void)
自版本 3.10 起，它是 稳定 ABI 的一部分。

禁用垃圾收集器：类似于 gc.disable()。返回先前状态，0 表示禁用，1 表示启用。

在版本 3.10 中添加。

int PyGC_IsEnabled(void)
自版本 3.10 起，它是 稳定 ABI 的一部分。

查询垃圾收集器状态：类似于 gc.isenabled()。返回当前状态，0 表示禁用，1 表示启用。

在版本 3.10 中添加。

查询垃圾收集器状态

C-API 提供以下接口来查询有关垃圾收集器的信息。

void PyUnstable_GC_VisitObjects(gcvisitobjects_t callback, void *arg)
这是 不稳定 API。它可能会在次要版本中发生更改，恕不另行通知。

对所有活动的 GC 可用对象运行提供的 callback。arg 会传递到 callback 的所有调用中。

警告

如果回调分配了新的对象，则这些对象是否会被访问是未定义的。

在操作期间，垃圾回收已禁用。在回调中显式运行回收可能会导致未定义的行为，例如多次访问同一个对象或根本不访问。

在 3.12 版本中添加。

typedef int (*gcvisitobjects_t)(PyObject *object, void *arg)

传递给 PyUnstable_GC_VisitObjects() 的访问器函数的类型。arg 与传递给 PyUnstable_GC_VisitObjects 的 arg 相同。返回 0 以继续迭代，返回 1 以停止迭代。其他返回值目前保留，因此返回任何其他值的的行为是未定义的。

在 3.12 版本中添加。