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

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

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

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

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

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

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

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

END_OF_DOCUMENT_MARKER

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).