# 29.11. `gc` - 垃圾收集器接口

此模块提供了到可选垃圾回收器的接口。它提供了禁用收集器，调整容器频率和设置调试选项的功能。它还提供对收集器发现但不能释放的无法访问的对象的访问。由于收集器补充了在Python中已经使用的引用计数，如果确定程序不创建引用循环，则可以禁用收集器。可以通过调用`gc.disable()`禁用自动容器。要调试泄漏程序调用`gc.set_debug(gc.DEBUG_LEAK)`。请注意，这包括`gc.DEBUG_SAVEALL`，导致垃圾收集的对象保存在gc.garbage中进行检查。

`gc`模块提供以下功能：

`gc.``enable`()

  启用自动垃圾容器。

`gc.``disable`()

  禁用自动垃圾容器。

`gc.``isenabled`()

  如果启用了自动容器，则返回true。

`gc.``collect`(generations=2)

  没有参数，运行一个完整的容器。可选参数生成可以是指定要收集哪个生成（从0到2）的整数。如果代数无效，则会引发`ValueError`。返回找到的不可达对象的数量。

  每当运行最高代（2）的完整容器或容器时，将清除为多个内建类型维护的空闲列表。由于特定实现，特别是`float`，某些空闲列表中的所有项目都可能被释放。

`gc.``set_debug`(flags)

  设置垃圾容器调试标志。调试信息将写入`sys.stderr`。请参见下面的调试标志列表，可以使用位操作来组合使用控制调试。

`gc.``get_debug`()

  返回当前设置的调试标志。

`gc.``get_objects`()

  返回收集器跟踪的所有对象的列表，不包括返回的列表。

`gc.``get_stats`()

  从解释器启动后，返回包含容器统计信息的三个每代字典的列表。键的数量可能会在将来更改，但目前每个字典将包含以下项目：

  - `collections`是此代的收集次数；
  - `collected`是在此世代内收集的对象的总数；
  - `uncollectable`是在这一代内发现无法收集（并因此移动到`garbage`列表）的对象的总数。

  版本3.4中的新功能。

`gc.``set_threshold`(threshold0[, threshold1[, threshold2]])

  设置垃圾容器阈值（容器频率）。将threshold0设置为零将禁用容器。

  GC根据它们存活了多少容器扫描将对象分为三代。新对象放置在最新一代（生成`0`）中。如果一个对象存在一个容器，它会被移动到下一个老一代。由于生成`2`是最旧的一代，该生成中的对象在容器之后仍保留在那里。为了决定何时运行，收集器跟踪自上一个容器以来的数字对象分配和释放。当分配数量减去解除分配数量超过threshold0时，容器开始。最初仅检查生成`0`。如果已经检查了生成`0`多于从生成`1`开始的threshold1时间，则检查生成`1`以及。类似地，在收集生成`2`之前，threshold2控制生成`1`的容器的数量。

`gc.``get_count`()

  将当前容器计数返回为`（count0， count1， count2）`的元组。

`gc.``get_threshold`()

  将当前容器阈值作为`（threshold0， threshold1， threshold2）`的元组返回。

`gc.``get_referrers`(*objs)

  返回直接引用任何obj的对象列表。这个函数只会定位那些支持垃圾容器的容器。不指向其他对象但不支持垃圾容器的扩展类型将不会被找到。

  注意，可以在结果引用中列出已经被解引用但是已经被循环生存并且尚未被垃圾收集器收集的对象。要仅获取当前活动对象，请在调用`get_referrers()`之前调用`collect()`。

  当使用由`get_referrers()`返回的对象时，必须小心，因为它们中的一些可能仍在构建中，因此处于临时无效状态。避免使用`get_referrers()`用于除调试之外的任何用途。

`gc.``get_referents`(*objs)

  返回由任何参数直接引用的对象列表。返回的对象是参数'C-level `tp_traverse`方法访问的那些对象（如果有的话），并且可能不是所有实际上可直接到达的对象。`tp_traverse`方法仅由支持垃圾容器的对象支持，并且只需要访问可能涉及循环的对象。因此，例如，如果一个整数可以从一个参数直接到达，则该整数对象可以或可以不出现在结果列表中。

`gc.``is_tracked`(obj)

  如果对象当前由垃圾收集器跟踪，则返回`True`，否则返回`False`。作为一般规则，原子类型的实例不被跟踪，并且非原子类型的实例（容器，用户定义的对象...）是。然而，可以存在一些类型特定的优化，以便抑制简单实例的垃圾收集器覆盖区（footprint）。只包含原子键和值的dicts）：

      >>> gc.is_tracked(0)
      False
      >>> gc.is_tracked("a")
      False
      >>> gc.is_tracked([])
      True
      >>> gc.is_tracked({})
      False
      >>> gc.is_tracked({"a": 1})
      False
      >>> gc.is_tracked({"a": []})
      True

  版本3.1中的新功能。

为只读访问提供了以下变量（您可以改变值，但不应重新绑定它们）：

`gc.``garbage`

  收集器发现无法访问但无法释放的对象列表（无法收集的对象）。从Python 3.4开始，这个列表在大多数时候应该是空的，除非使用具有非NULL `tp_del`插槽的C扩展类型的实例。

  如果设置了`DEBUG_SAVEALL`，则所有无法访问的对象将被添加到此列表，而不是释放。

  在版本3.2中更改：如果此列表在interpreter shutdown时为非空，则会发出一个`ResourceWarning` 如果设置了`DEBUG_UNCOLLECTABLE`，则还会打印所有无法收集的对象。

  版本3.4中改变：在 PEP 442之后，具有`__del__()`方法的对象不会以`gc.garbage`了。

`gc.``callbacks`

  将由容器之前和之后的垃圾收集器调用的回调列表。将使用两个参数（phase和info）调用回调。

  phase可以是以下两个值之一：

  > “start”: The garbage collection is about to start.

  > “stop”: The garbage collection has finished.

  info是为回调提供更多信息的dict。以下键目前已定义：

  > “generation”: The oldest generation being collected.

  > “collected”: When phase is “stop”, the number of objects successfully collected.

  > “uncollectable”: When phase is “stop”, the number of objects that could not be collected and were put in `garbage`.

  应用程序可以将自己的回调添加到此列表。主要用例是：

  > Gathering statistics about garbage collection, such as how often various generations are collected, and how long the collection takes.

  > Allowing applications to identify and clear their own uncollectable types when they appear in `garbage`.

  版本3.3中的新功能。

提供以下常量以与`set_debug()`配合使用：

`gc.``DEBUG_STATS`

  容器期间打印统计信息。在调整容器频率时，此信息可能很有用。

`gc.``DEBUG_COLLECTABLE`

  打印有关可找到的可收集对象的信息。

`gc.``DEBUG_UNCOLLECTABLE`

  打印找到的不可收集对象的信息（收集器不能访问但不能释放的对象）。这些对象将添加到`garbage`列表中。

  在版本3.2中更改：如果不为空，还打印interpreter shutdown中的`garbage`列表的内容。

`gc.``DEBUG_SAVEALL`

  设置时，找到的所有无法访问的对象将被附加到垃圾，而不是被释放。这对于调试泄漏程序很有用。

`gc.``DEBUG_LEAK`

  收集器打印有关泄漏程序的信息（等于`DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE | DEBUG_SAVEALL`）。