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

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

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

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

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

gc.get_referents(*objs)

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

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

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