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. Если с момента проверки поколения 1 поколение 0 проверялось более threshold1 раз, проверяется также поколение 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)

Вернуть список объектов, на которые непосредственно ссылается любой из аргументов. Возвращаются объекты, посещённые методами tp_traverse аргументов на уровне C (если такие методы есть); в список могут попасть не все объекты, до которых действительно можно добраться напрямую. Методы 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).