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() во время уже выполняющейся сборки интерпретатором не определено.

Изменено в версии 3.14: generation=1 выполняет инкрементальную сборку.

Изменено в версии 3.14.5: generation=1 выполняет сборку среднего поколения.

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

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

gc.get_objects(generation=None)

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

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

Изменено в версии 3.14: Поколение 1 удалено

Изменено в версии 3.14.5: Поколение 1 возвращено для сохранения поведения GC из версии 3.13.

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

gc.get_stats()

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

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

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

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

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

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

В сборке без GIL перед запуском сборщика также проверяется увеличение использования памяти процессом. Если с момента последней сборки использование памяти не увеличилось на 10%, а чистое количество выделенных объектов не превысило 40-кратное значение threshold0, сборка не запускается.

Дополнительные сведения см. в разделе Устройство сборщика мусора.

Изменено в версии 3.14: threshold2 игнорируется

Изменено в версии 3.14.5: threshold2 восстановлен для соответствия поведению Python 3.13.

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})
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 в дочерних процессах не будут затрагивать счётчик 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).