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: Параметр нового поколения.

Создает auditing event gc.get_objects с аргументом generation.

gc.get_stats()¶

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

• collections - это количество раз, когда было собрано это поколение;

• collected - это общее количество объектов, собранных в рамках этого поколения;

• uncollectable - это общее количество объектов, которые были признаны недоступными для сбора (и, следовательно, были перемещены в список garbage) в этом поколении.

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

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

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

Общая коллекция классифицирует объекты по трем поколениям в зависимости от того, сколько раз они проходили проверку в коллекции. Новые объекты помещаются в самое молодое поколение (поколение 0). Если объект остается в коллекции, он перемещается в следующее более старое поколение. Поскольку поколение 2 является самым старым поколением, объекты этого поколения остаются там после сбора. Чтобы решить, когда запускать, сборщик отслеживает количество выделений и освобождений объектов с момента последнего сбора. Когда количество назначений за вычетом количества отмененных назначений превышает пороговое значение 0, начинается сбор данных. Первоначально проверяется только генерация 0. Если поколение 0 проверялось более порогового значения 1 раз с момента проверки поколения 1, то также проверяется поколение 1. С третьим поколением все немного сложнее, дополнительную информацию смотрите в разделе Collecting the oldest generation.

gc.get_count()¶

Возвращает значение текущей коллекции как кортеж из (count0, count1, count2).

gc.get_threshold()¶

Возвращает текущие пороговые значения сбора в виде кортежа (threshold0, threshold1, threshold2).

gc.get_referrers(*objs)¶

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

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

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

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

Создает auditing event gc.get_referrers с аргументом objs.

gc.get_referents(*objs)¶

Возвращает список объектов, на которые непосредственно ссылается любой из аргументов. Возвращаемые ссылки - это те объекты, которые были посещены методами уровня C аргументов tp_traverse (если таковые имеются), и не все объекты могут быть доступны непосредственно. :методы c:member:~PyTypeObject.tp_traverse поддерживаются только объектами, поддерживающими сборку мусора, и требуются только для посещения объектов, которые могут быть задействованы в цикле. Так, например, если целое число доступно непосредственно из аргумента, этот целочисленный объект может отображаться, а может и не отображаться в списке результатов.

Создает auditing event gc.get_referents с аргументом objs.

gc.is_tracked(obj)¶

Возвращает True, если объект в данный момент отслеживается сборщиком мусора, False в противном случае. Как правило, экземпляры атомарных типов не отслеживаются, а экземпляры неатомарных типов (контейнеры, пользовательские объекты…) отслеживаются. Однако могут быть применены некоторые оптимизации, зависящие от типа, чтобы уменьшить объем сборщика мусора для простых экземпляров (например, dicts, содержащих только атомарные ключи и значения).:

>>> 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 в дочерних процессах не затрагивали счетчик долгоживущих объектов, происходящих из родительского процесса. Чтобы выполнить и то, и другое, вызовите 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: Если этот список непустой при interpreter shutdown, выводится значение ResourceWarning, которое по умолчанию не отображается. Если задано значение DEBUG_UNCOLLECTABLE, то, кроме того, выводятся все объекты, которые невозможно собрать.

Изменено в версии 3.4: После PEP 442 объекты с методом __del__() больше не попадают в gc.garbage.

gc.callbacks¶

Список обратных вызовов, которые будут вызываться сборщиком мусора до и после сбора. Обратные вызовы будут вызываться с двумя аргументами: phase и info.

фаза может быть одним из двух значений:

«начать»: Вот-вот начнется сборка мусора.

«стоп»: Сбор мусора завершен.

info - это dict, предоставляющий дополнительную информацию для обратного вызова. В настоящее время определены следующие ключи:

«поколение»: Собирается самое старое поколение.

«собрано»: когда фаза остановлена, отображается количество успешно собранных объектов.

«невозможно собрать»: когда фаза находится в состоянии «стоп», количество объектов, которые не удалось собрать и которые были помещены в garbage.

Приложения могут добавлять в этот список свои собственные обратные вызовы. Основными вариантами использования являются:

Сбор статистических данных о сборе мусора, таких как частота сбора данных различных поколений и продолжительность сбора данных.

Позволяет приложениям идентифицировать и удалять свои собственные типы, которые невозможно собрать, когда они отображаются в garbage.

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

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

gc.DEBUG_STATS¶

Печатайте статистику во время сбора данных. Эта информация может быть полезна при настройке частоты сбора данных.

gc.DEBUG_COLLECTABLE¶

Распечатайте информацию о найденных предметах коллекционирования.

gc.DEBUG_UNCOLLECTABLE¶

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

Изменено в версии 3.2: Также выведите содержимое списка garbage в interpreter shutdown, если он не пуст.

gc.DEBUG_SAVEALL¶

Если этот параметр установлен, все найденные недоступные объекты будут добавлены в «мусор», а не освобождены. Это может быть полезно для отладки программы с утечкой данных.

gc.DEBUG_LEAK¶

Флаги отладки, необходимые сборщику для вывода информации об утечке программы (равны DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE | DEBUG_SAVEALL).