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. Эта функция найдёт только те контейнеры, которые поддерживают сбор мусора; типы расширений, которые ссылаются на другие объекты, но не поддерживают сбор мусора, не будут найдены.

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

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

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