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 в ноль отключает сбор.

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

Возвращает список объектов, напрямую ссылающихся на любые из аргументов. Возвращаемые референты — это те объекты, которые посещают методы 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})
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_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).