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)

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