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 также проверяется. С третьим поколением ситуация немного сложнее, см. Сбор самого старого поколения для получения более подробной информации.

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.freeze()

Заморозить все отслеживаемые сборщиком мусора объекты — переместить их в постоянную генерацию и игнорировать все последующие сборы. Это можно использовать перед вызовом POSIX fork() для обеспечения совместимости gc с copy-on-write или для ускорения сбора. Также сбор перед вызовом POSIX fork() может освободить страницы для будущих выделений, что также может привести к copy-on-write, поэтому рекомендуется отключить gc в главном процессе, заморозить перед вилкой и включить gc в дочернем процессе.

Новое в версии 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.

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

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

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