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

Возвращает список объектов, напрямую ссылающихся на любой из переданных аргументов. Возвращаемые ссылки — это те объекты, которые посещаются методами 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.freeze(): Заморозить все отслеживаемые gc объекты — переместить их в постоянную генерацию и игнорировать все будущие сборки. Это может быть использовано перед вызовом POSIX fork() для повышения дружественности gc по отношению к копированию по записи или для ускорения сбора. Также сбор перед вызовом POSIX fork() может освободить страницы для будущего выделения, что также может способствовать копированию по записи, поэтому рекомендуется отключить gc в родительском процессе и заморозить его перед вызовом fork, а затем включить gc в дочернем процессе.

Добавлена в версии 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).