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(): Возвращает список всех объектов, отслеживаемых сборщиком, за исключением возвращённого списка.

gc.get_stats()

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

collections — количество раз, когда это поколение было собрано;
collected — общее количество объектов, собранных в этом поколении;
uncollectable — общее количество объектов, которые были признаны неподлежащими сборке (и были поэтому перемещены в список garbage) в этом поколении.

Новое в версии 3.4.

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

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

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

gc.get_count(): Возвращает текущие счётчики сборок в виде кортежа (count0, count1, count2).

gc.get_threshold(): Возвращает текущие пороги сбора в виде кортежа (threshold0, threshold1, threshold2).

gc.get_referrers(*objs)

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

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

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

gc.get_referents(*objs): Возвращает список объектов, напрямую ссылающихся на любой из аргументов. Возвращаемые referents — это те объекты, посещённые методами 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.garbage

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