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) в данном поколении.

Added in version 3.4.

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

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

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

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

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

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

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

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

gc.get_referents(*objs)

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

Поднимает auditing event 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

Added in version 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

Added in version 3.9.

gc.freeze()

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

Если процесс будет fork() без exec(), то избегание ненужного копирования при записи в дочерних процессах позволит максимально разделить память и снизить общее потребление памяти. Для этого необходимо как избегать создания освобожденных «дыр» в страницах памяти в родительском процессе, так и гарантировать, что GC-коллекции в дочерних процессах не будут трогать счетчик gc_refs долгоживущих объектов, созданных в родительском процессе. Чтобы добиться того и другого, вызывайте gc.disable() в начале родительского процесса, gc.freeze() непосредственно перед fork() и gc.enable() в начале дочерних процессов.

Added in version 3.7.

gc.unfreeze()

Разморозьте объекты в постоянном поколении, поместите их обратно в самое старое поколение.

Added in version 3.7.

gc.get_freeze_count()

Возвращает количество объектов в постоянном поколении.

Added in version 3.7.

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

gc.garbage

Список объектов, которые сборщик счел недостижимыми, но не смог освободить (uncollectable objects). Начиная с 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.

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

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

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

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

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

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

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

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

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

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

Added in version 3.3.

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

gc.DEBUG_STATS

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

gc.DEBUG_COLLECTABLE

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

gc.DEBUG_UNCOLLECTABLE

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

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

gc.DEBUG_SAVEALL

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

gc.DEBUG_LEAK

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