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(generation=2)

Если аргументы не указаны, выполняет полную сборку мусора. Необязательный аргумент generation может быть целым числом, указывающим, какое поколение собирать (от 0 до 2). Если номер поколения недопустим, возникает исключение ValueError. Возвращается количество найденных недостижимых объектов.

При выполнении полной сборки мусора или сборки мусора для самого старого поколения (2) очищаются списки свободных объектов, поддерживаемые для ряда встроенных типов. Из-за особенностей реализации не все элементы некоторых списков свободных объектов могут быть освобождены, в частности float.

Поведение при вызове gc.collect() во время уже выполняющейся сборки мусора не определено.

gc.set_debug(flags): Установить флаги отладки сборщика мусора. Отладочная информация будет записана в sys.stderr. Список флагов отладки, которые можно комбинировать с помощью побитовых операций, приведён ниже.

gc.get_debug(): Возвращает текущие флаги отладки.

gc.get_objects(generation=None)

Возвращает список всех объектов, отслеживаемых сборщиком, за исключением самого возвращаемого списка. Если generation не равен None, возвращаются только объекты, отслеживаемые сборщиком и принадлежащие этому поколению.

Изменено в версии 3.8: Добавлен параметр generation.

Вызывает событие аудита gc.get_objects с аргументом generation.

gc.get_stats()

Возвращает список из трёх словарей, по одному на поколение, содержащих статистику сборки мусора с момента запуска интерпретатора. Число ключей может измениться в будущем, но сейчас каждый словарь содержит следующие элементы:

collections — количество сборок мусора для этого поколения;
collected — общее количество объектов, собранных в этом поколении;
uncollectable — общее количество объектов, признанных несобираемыми (и поэтому перемещённых в список garbage) в этом поколении.

Добавлено в версии 3.4.

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

Установить пороги сборки мусора (частоту сборки). Установка значения threshold0 равного нулю отключает сборку мусора.

Сборщик мусора распределяет объекты по трём поколениям в зависимости от того, сколько циклов сборки они пережили. Новые объекты помещаются в самое молодое поколение (поколение 0). Если объект переживает сборку мусора, он перемещается в следующее, более старое поколение. Поскольку поколение 2 — самое старое, объекты в нём остаются после сборки в том же поколении. Чтобы определить, когда запускать сборку, сборщик отслеживает количество выделений и освобождений объектов с момента последней сборки. Сборка начинается, когда количество выделений за вычетом количества освобождений превышает threshold0. Сначала проверяется только поколение 0. Если поколение 0 проверялось более threshold1 раз с момента последней проверки поколения 1, проверяется также поколение 1. С третьим поколением всё немного сложнее; подробнее см. в разделе Сборка мусора в самом старом поколении.

gc.get_count(): Возвращает текущие счётчики сборки мусора в виде кортежа из (count0, count1, count2).

gc.get_threshold(): Возвращает текущие пороги сборки мусора в виде кортежа из (threshold0, threshold1, threshold2).

gc.get_referrers(*objs)

Возвращает список объектов, которые напрямую ссылаются на любой из объектов objs. Эта функция находит только контейнеры, поддерживающие сборку мусора; типы расширений, которые ссылаются на другие объекты, но не поддерживают сборку мусора, обнаружены не будут.

Обратите внимание, что среди найденных объектов могут оказаться объекты, на которые уже нет ссылок, но которые находятся в циклах и ещё не были собраны сборщиком мусора. Чтобы получить только активные объекты, вызовите collect() перед вызовом get_referrers().

Предупреждение

При работе с объектами, возвращёнными функцией get_referrers(), следует соблюдать осторожность: некоторые из них могут ещё создаваться и поэтому находиться во временно некорректном состоянии. Не используйте get_referrers() ни для каких целей, кроме отладки.

Вызывает событие аудита gc.get_referrers с аргументом objs.

gc.get_referents(*objs)

Возвращает список объектов, на которые напрямую ссылается любой из аргументов. В список попадают объекты, посещённые C-методами tp_traverse аргументов (если такие методы есть); в нём могут отсутствовать некоторые объекты, до которых действительно можно добраться напрямую. Методы tp_traverse поддерживаются только объектами, поддерживающими сборку мусора, и должны посещать только объекты, которые могут участвовать в цикле. Поэтому, например, если целое число напрямую достижимо из аргумента, этот объект целого числа может присутствовать в возвращаемом списке, а может и отсутствовать.

Вызывает событие аудита gc.get_referents с аргументом objs.

gc.is_tracked(obj)

Возвращает True, если объект в данный момент отслеживается сборщиком мусора, и False в противном случае. Как правило, экземпляры атомарных типов не отслеживаются, а экземпляры неатомарных типов (контейнеры, объекты, определённые пользователем…) отслеживаются. Однако для некоторых типов могут применяться специальные оптимизации, позволяющие уменьшить нагрузку на сборщик мусора при работе с простыми экземплярами (например, словарями, содержащими только атомарные ключи и значения):

>>> 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.is_finalized(obj)

Возвращает True, если переданный объект был финализирован сборщиком мусора, и False в противном случае.

>>> x = None
>>> class Lazarus:
...     def __del__(self):
...         global x
...         x = self
...
>>> lazarus = Lazarus()
>>> gc.is_finalized(lazarus)
False
>>> del lazarus
>>> gc.is_finalized(x)
True

Добавлено в версии 3.9.

gc.freeze()

Заморозить все объекты, отслеживаемые сборщиком мусора: переместить их в постоянное поколение и исключить из всех последующих сборок мусора.

Если процесс будет fork() без exec(), предотвращение ненужного копирования при записи в дочерних процессах позволит максимально увеличить совместное использование памяти и снизить общее потребление памяти. Для этого необходимо как избегать создания освободившихся «дыр» на страницах памяти в родительском процессе, так и гарантировать, что сборки мусора в дочерних процессах не затронут счётчик gc_refs долгоживущих объектов, унаследованных от родительского процесса. Чтобы добиться этого, вызовите gc.disable() в начале родительского процесса, gc.freeze() непосредственно перед fork(), а gc.enable() — в начале дочерних процессов.

Добавлено в версии 3.7.

gc.unfreeze(): Разморозить объекты в постоянном поколении и вернуть их в самое старое поколение.

Добавлено в версии 3.7.

gc.get_freeze_count(): Возвращает количество объектов в постоянном поколении.

Добавлено в версии 3.7.

Для доступа только на чтение предоставлены следующие переменные (их значения можно изменять, но не следует переназначать сами переменные):

gc.garbage

Список объектов, признанных сборщиком мусора недостижимыми, но не поддающихся освобождению (несобираемых объектов). Начиная с Python 3.4, этот список обычно должен быть пуст, за исключением случаев использования экземпляров типов расширений C с не-NULL tp_del слотом.

Если установлен флаг DEBUG_SAVEALL, все недостижимые объекты будут добавляться в этот список, а не освобождаться.

Изменено в версии 3.2: Если этот список не пуст при завершении работы интерпретатора, выдаётся предупреждение ResourceWarning, которое по умолчанию не отображается. Если установлен флаг DEBUG_UNCOLLECTABLE, дополнительно выводятся все несобираемые объекты.

Изменено в версии 3.4: В соответствии с PEP 442, объекты с методом __del__() больше не попадают в gc.garbage.

gc.callbacks

Список обратных вызовов, которые сборщик мусора выполняет до и после сборки. Обратные вызовы получают два аргумента: phase и info.

phase может принимать одно из двух значений:

«start»: сборка мусора вот-вот начнётся.

«stop»: сборка мусора завершена.

info — это словарь с дополнительной информацией для обратного вызова. Сейчас определены следующие ключи:

«generation»: самое старое поколение, участвующее в сборке.

«collected»: если phase равно «stop», количество успешно собранных объектов.

«uncollectable»: если phase равно «stop», количество объектов, которые не удалось собрать и которые были помещены в garbage.

Приложения могут добавлять в этот список собственные обратные вызовы. Основные варианты применения:

Сбор статистики о работе сборщика мусора, например о частоте сборки различных поколений и длительности сборки.

Предоставление приложениям возможности находить и очищать собственные несобираемые типы, когда те появляются в garbage.

Добавлено в версии 3.3.

Для использования с set_debug() предоставлены следующие константы:

gc.DEBUG_STATS: Выводить статистику во время сборки мусора. Эта информация может быть полезна при настройке частоты сборки.

gc.DEBUG_COLLECTABLE: Выводить информацию о найденных собираемых объектах.

gc.DEBUG_UNCOLLECTABLE: Выводить информацию о найденных несобираемых объектах (объектах, которые недостижимы, но не могут быть освобождены сборщиком). Эти объекты будут добавлены в список garbage.

Изменено в версии 3.2: При завершении работы интерпретатора также выводить содержимое списка garbage, если он не пуст.

gc.DEBUG_SAVEALL: Если установлен, все найденные недостижимые объекты будут добавляться в garbage, а не освобождаться. Это может быть полезно для отладки программы с утечками.

gc.DEBUG_LEAK: Флаги отладки, необходимые сборщику для вывода информации о программе с утечками (эквивалентны DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE | DEBUG_SAVEALL).