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: Новый параметр generation.

Вызывает событие аудита аудита gc.get_objects с аргументом 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)

Возвращает список объектов, которые напрямую ссылаются на любой из 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()

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

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

Добавлена в версии 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

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

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

“start”: Сбор мусора начался.

“stop”: Сбор мусора завершён.

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

“generation”: Самая старая собираемая генерация.

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

“uncollectable”: Когда фаза равна “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).