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.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 в ноль отключает сбор.

GC классифицирует объекты в три поколения в зависимости от того, сколько циклов сбора они пережили. Новые объекты помещаются в самое молодое поколение (генерация 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)

Возвращает список объектов, напрямую ссылающихся на любые из аргументов. Возвращаемые ссылки — это те объекты, которые посещаются методами 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(): Заморозить все отслеживаемые сборщиком мусора объекты — переместить их в постоянную генерацию и игнорировать все будущие сборы. Это может быть использовано перед вызовом POSIX fork() для обеспечения совместимости copy-on-write или для ускорения сбора. Также сбор перед вызовом POSIX fork() может освободить страницы для будущего выделения памяти, что также может привести к copy-on-write, поэтому рекомендуется отключить gc в родительском процессе и заморозить его перед вызовом fork, а затем включить gc в дочернем процессе.

Введено в версии 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).