gc – интерфейс сборщика мусора¶gc – Garbage Collector interface

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

Изменено в версии 3.14: generation=1 выполняет инкремент сборки.

Изменено в версии 3.14.5: generation=1 выполняет сборку среднего поколения.

gc.set_debug(flags)¶

Устанавливает флаги отладки сборщика мусора. Отладочная информация будет записываться в sys.stderr. См. ниже список флагов отладки, которые можно комбинировать с помощью битовых операций для управления отладкой.

gc.get_debug()¶

Возвращает текущие установленные флаги отладки.

gc.get_objects(generation=None)¶

Возвращает список всех объектов, отслеживаемых сборщиком, за исключением возвращаемого списка. Если generation не равно None, возвращает только объекты, отслеживаемые сборщиком, которые находятся в этом поколении.

Изменено в версии 3.8: Новый параметр generation.

Изменено в версии 3.14: Поколение 1 удалено

Изменено в версии 3.14.5: Поколение 1 повторно введено для сохранения поведения GC из версии 3.13.

Вызывает событие аудита gc.get_objects с аргументом generation.

gc.get_stats()¶

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

• collections – количество сборок этого поколения;

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

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

• candidates – общее количество объектов в этом поколении, которые были рассмотрены для сборки и обойдены;

• duration – общее время в секундах, затраченное на сборки для этого поколения.

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

Изменено в версии 3.15: Добавлены duration и candidates.

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

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

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

Подробнее см. Garbage collector design.

Изменено в версии 3.14: threshold2 игнорируется

Изменено в версии 3.14.5: threshold2 восстановлено для соответствия поведению Python 3.13.

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

Возвращает список объектов, на которые напрямую ссылается любой из аргументов. Возвращаемые референты – это объекты, посещённые C-уровневыми методами tp_traverse аргументов (если они есть), и это могут быть не все объекты, действительно достижимые напрямую. Методы 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})
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.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: Если этот список не пуст при завершении интерпретатора, выдается 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.

“candidates”: Когда phase имеет значение «stop», общее количество объектов в этом поколении, которые были рассмотрены для сборки и обойдены.

“duration”: Когда phase имеет значение «stop», время в секундах, затраченное на сборку.

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

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

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

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

Изменено в версии 3.15: Добавлены «duration» и «candidates».

Следующие константы предоставляются для использования с 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).