gc.md

1> **Источник:** https://python-all.ru/3.15/library/gc.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `gc` – интерфейс сборщика мусора89---1011Этот модуль предоставляет интерфейс к необязательному сборщику мусора. Он позволяет отключить сборщик, настроить частоту сборки и установить параметры отладки. Также он предоставляет доступ к недостижимым объектам, которые сборщик нашел, но не может освободить. Поскольку сборщик дополняет подсчёт ссылок, уже используемый в Python, его можно отключить, если программа не создаёт циклических ссылок. Автоматическую сборку можно отключить вызовом `gc.disable()`. Для отладки утекающей программы вызовите `gc.set_debug(gc.DEBUG_LEAK)`. Обратите внимание, что это включает `gc.DEBUG_SAVEALL`, что приводит к сохранению собранных объектов в gc.garbage для проверки.1213Модуль `gc` предоставляет следующие функции:1415#### `gc.enable()`1617Включить автоматическую сборку мусора.1819#### `gc.disable()`2021Отключить автоматическую сборку мусора.2223#### `gc.isenabled()`2425Возвращает `True`, если автоматическая сборка включена.2627#### `gc.collect(generation=2)`2829Без аргументов выполняет полную сборку. Необязательный аргумент *generation* может быть целым числом, указывающим, какое поколение собирать (от 0 до 2). Если номер поколения недопустим, возбуждается [`ValueError`](https://python-all.ru/3.15/library/exceptions.html#ValueError). Возвращается сумма собранных объектов и объектов, не подлежащих сборке.3031Списки свободной памяти, ведущиеся для ряда встроенных типов, очищаются при полной сборке или сборке самого старшего поколения (2). Не все элементы в некоторых списках свободной памяти могут быть освобождены из-за особенностей реализации, в частности [`float`](https://python-all.ru/3.15/library/functions.html#float).3233Эффект от вызова `gc.collect()`, когда интерпретатор уже выполняет сборку, не определён.3435Изменено в версии 3.14: `generation=1` выполняет инкремент сборки.3637Изменено в версии 3.14.5: `generation=1` выполняет сборку среднего поколения.3839#### `gc.set_debug(flags)`4041Устанавливает флаги отладки сборщика мусора. Отладочная информация будет записываться в `sys.stderr`. См. ниже список флагов отладки, которые можно комбинировать с помощью битовых операций для управления отладкой.4243#### `gc.get_debug()`4445Возвращает текущие установленные флаги отладки.4647#### `gc.get_objects(generation=None)`4849Возвращает список всех объектов, отслеживаемых сборщиком, за исключением возвращаемого списка. Если *generation* не равно `None`, возвращает только объекты, отслеживаемые сборщиком, которые находятся в этом поколении.5051Изменено в версии 3.8: Новый параметр *generation*.5253Изменено в версии 3.14: Поколение 1 удалено5455Изменено в версии 3.14.5: Поколение 1 повторно введено для сохранения поведения GC из версии 3.13.5657Вызывает [событие аудита](https://python-all.ru/3.15/library/sys.html#auditing) `gc.get_objects` с аргументом `generation`.5859#### `gc.get_stats()`6061Возвращает список из трёх словарей по поколениям, содержащих статистику сборки с момента запуска интерпретатора. Количество ключей может измениться в будущем, но в настоящее время каждый словарь содержит следующие элементы:6263- `collections` – количество сборок этого поколения;64- `collected` – общее количество объектов, собранных в этом поколении;65- `uncollectable` – общее количество объектов, которые оказались несобираемыми (и поэтому были перемещены в список [`garbage`](https://python-all.ru/3.15/library/gc.html#gc.garbage) ) внутри данного поколения;66- `candidates` – общее количество объектов в этом поколении, которые были рассмотрены для сборки и обойдены;67- `duration` – общее время в секундах, затраченное на сборки для этого поколения.6869Добавлено в версии 3.4.7071Изменено в версии 3.15: Добавлены `duration` и `candidates`.7273#### `gc.set_threshold(threshold0[, threshold1[, threshold2]])`7475Устанавливает пороги сборки мусора (частоту сборки). Установка *threshold0* в ноль отключает сборку.7677Сборщик мусора (GC) классифицирует объекты по трём поколениям в зависимости от того, сколько циклов сборки они пережили. Новые объекты помещаются в самое молодое поколение (поколение `0`). Если объект переживает сборку, он перемещается в следующее, более старое поколение. Поскольку поколение `2` является самым старым, объекты в этом поколении остаются там после сборки. Чтобы решить, когда запускать сборку, сборщик отслеживает количество выделений и освобождений объектов с момента последней сборки. Когда количество выделений минус количество освобождений превышает *threshold0*, сборка начинается. Изначально проверяется только поколение `0`. Если поколение `0` проверялось больше *threshold1* раз с момента проверки поколения `1`, то проверяется также поколение `1`. С третьим поколением ситуация немного сложнее: подробнее см. [Collecting the oldest generation](https://python-all.ru/3.15/library/gc.html).7879Подробнее см. [Garbage collector design](https://python-all.ru/3.15/library/gc.html).8081Изменено в версии 3.14: *threshold2* игнорируется8283Изменено в версии 3.14.5: *threshold2* восстановлено для соответствия поведению Python 3.13.8485#### `gc.get_count()`8687Возвращает текущие счётчики сборок в виде кортежа из `(count0, count1, count2)`.8889#### `gc.get_threshold()`9091Возвращает текущие пороговые значения сборок в виде кортежа из `(threshold0, threshold1, threshold2)`.9293#### `gc.get_referrers(*objs)`9495Возвращает список объектов, которые напрямую ссылаются на любой из objs. Эта функция находит только те контейнеры, которые поддерживают сборку мусора; типы расширений, которые ссылаются на другие объекты, но не поддерживают сборку мусора, найдены не будут.9697Обратите внимание, что объекты, на которые уже нет ссылок, но которые находятся в циклах и ещё не собраны сборщиком мусора, могут оказаться среди возвращаемых ссылающихся объектов. Чтобы получить только живые объекты, вызовите [`collect()`](https://python-all.ru/3.15/library/gc.html#gc.collect) перед вызовом `get_referrers()`.9899> **Предупреждение**100>101> Следует соблюдать осторожность при использовании объектов, возвращаемых `get_referrers()`, поскольку некоторые из них могут всё ещё находиться в процессе конструирования и, следовательно, во временно недопустимом состоянии. Избегайте использования `get_referrers()` для каких-либо целей, кроме отладки.102103Вызывает [событие аудита](https://python-all.ru/3.15/library/sys.html#auditing) `gc.get_referrers` с аргументом `objs`.104105#### `gc.get_referents(*objs)`106107Возвращает список объектов, на которые напрямую ссылается любой из аргументов. Возвращаемые референты – это объекты, посещённые C-уровневыми методами [`tp_traverse`](https://python-all.ru/3.15/c-api/typeobj.html#c.PyTypeObject.tp_traverse) аргументов (если они есть), и это могут быть не все объекты, действительно достижимые напрямую. Методы `tp_traverse` поддерживаются только объектами, которые поддерживают сборку мусора, и от них требуется только посещение объектов, которые могут участвовать в циклах. Так, например, если целое число напрямую достижимо из аргумента, этот целочисленный объект может как появиться в результирующем списке, так и нет.108109Вызывает [событие аудита](https://python-all.ru/3.15/library/sys.html#auditing) `gc.get_referents` с аргументом `objs`.110111#### `gc.is_tracked(obj)`112113Возвращает `True`, если объект в настоящее время отслеживается сборщиком мусора, и `False` в противном случае. Как правило, экземпляры атомарных типов не отслеживаются, а экземпляры неатомарных типов (контейнеры, пользовательские объекты и т.д.) отслеживаются. Однако могут присутствовать некоторые оптимизации для конкретных типов, чтобы уменьшить влияние на сборщик мусора простых экземпляров (например, словарей, содержащих только атомарные ключи и значения):114115```python116>>> gc.is_tracked(0)117False118>>> gc.is_tracked("a")119False120>>> gc.is_tracked([])121True122>>> gc.is_tracked({})123False124>>> gc.is_tracked({"a": 1})125True126```127128Добавлено в версии 3.1.129130#### `gc.is_finalized(obj)`131132Возвращает `True`, если указанный объект был финализирован сборщиком мусора, и `False` в противном случае.133134```python135>>> x = None136>>> class Lazarus:137...     def __del__(self):138...         global x139...         x = self140...141>>> lazarus = Lazarus()142>>> gc.is_finalized(lazarus)143False144>>> del lazarus145>>> gc.is_finalized(x)146True147```148149Добавлено в версии 3.9.150151#### `gc.freeze()`152153Замораживает все объекты, отслеживаемые сборщиком мусора; перемещает их в постоянное поколение и игнорирует во всех последующих сборках.154155Если процесс будет `fork()` без `exec()`, избегание ненужного копирования при записи в дочерних процессах максимизирует совместное использование памяти и снижает общее потребление памяти. Это требует как предотвращения создания освобождённых «дыр» в страницах памяти в родительском процессе, так и гарантии, что сборки мусора в дочерних процессах не затронут счётчик `gc_refs` долгоживущих объектов, созданных в родительском процессе. Для достижения обоих целей вызовите `gc.disable()` рано в родительском процессе, `gc.freeze()` непосредственно перед `fork()` и `gc.enable()` рано в дочерних процессах.156157Добавлено в версии 3.7.158159#### `gc.unfreeze()`160161Размораживает объекты в постоянном поколении, возвращает их обратно в самое старое поколение.162163Добавлено в версии 3.7.164165#### `gc.get_freeze_count()`166167Возвращает количество объектов в постоянном поколении.168169Добавлено в версии 3.7.170171Следующие переменные предназначены для доступа только для чтения (можно изменять их значения, но не следует их переназначать):172173#### `gc.garbage`174175Список объектов, которые сборщик обнаружил как недостижимые, но не смог освободить (неподлежащие сборке объекты). Начиная с Python 3.4, этот список в большинстве случаев должен быть пуст, за исключением использования экземпляров типов расширений C с не-`NULL` слотом `tp_del`.176177Если [`DEBUG_SAVEALL`](https://python-all.ru/3.15/library/gc.html#gc.DEBUG_SAVEALL) установлено, то все недостижимые объекты будут добавлены в этот список, а не освобождены.178179Изменено в версии 3.2: Если этот список не пуст при [завершении интерпретатора](https://python-all.ru/3.15/glossary.html#term-interpreter-shutdown), выдается [`ResourceWarning`](https://python-all.ru/3.15/library/exceptions.html#ResourceWarning), который по умолчанию является молчаливым. Если [`DEBUG_UNCOLLECTABLE`](https://python-all.ru/3.15/library/gc.html#gc.DEBUG_UNCOLLECTABLE) установлено, дополнительно выводятся все неподлежащие сборке объекты.180181Изменено в версии 3.4: В соответствии с [**PEP 442**](https://python-all.ru/3.15/library/gc.html), объекты с методом [`__del__()`](https://python-all.ru/3.15/reference/datamodel.html#object.__del__) больше не попадают в `gc.garbage`.182183#### `gc.callbacks`184185Список колбэков, которые будут вызываться сборщиком мусора до и после сборки. Колбэки будут вызываться с двумя аргументами: *phase* и *info*.186187*phase* может принимать одно из двух значений:188189> “start”: сборка мусора начинается.190>191> “stop”: сборка мусора завершена.192193*info* – это словарь, предоставляющий дополнительную информацию для колбэка. В настоящее время определены следующие ключи:194195> “generation”: самое старое поколение, участвующее в сборке.196>197> “collected”: когда *phase* равен “stop”, количество успешно собранных объектов.198>199> “uncollectable”: когда *phase* равен “stop”, количество объектов, которые не удалось собрать и которые были помещены в [`garbage`](https://python-all.ru/3.15/library/gc.html#gc.garbage).200>201> “candidates”: Когда *phase* имеет значение «stop», общее количество объектов в этом поколении, которые были рассмотрены для сборки и обойдены.202>203> “duration”: Когда *phase* имеет значение «stop», время в секундах, затраченное на сборку.204205Приложения могут добавлять свои собственные колбэки в этот список. Основные случаи использования:206207> Сбор статистики о сборке мусора, например, как часто собираются различные поколения и сколько времени занимает сборка.208>209> Позволяет приложениям выявлять и очищать собственные несобираемые типы, когда они появляются в [`garbage`](https://python-all.ru/3.15/library/gc.html#gc.garbage).210211Добавлено в версии 3.3.212213Изменено в версии 3.15: Добавлены «duration» и «candidates».214215Следующие константы предоставляются для использования с [`set_debug()`](https://python-all.ru/3.15/library/gc.html#gc.set_debug):216217#### `gc.DEBUG_STATS`218219Вывод статистики во время сборки. Эта информация может быть полезна при настройке частоты сборки.220221#### `gc.DEBUG_COLLECTABLE`222223Вывод информации о найденных собираемых объектах.224225#### `gc.DEBUG_UNCOLLECTABLE`226227Вывод информации о найденных несобираемых объектах (объекты, которые недостижимы, но не могут быть освобождены сборщиком). Эти объекты будут добавлены в список `garbage`.228229Изменено в версии 3.2: Также выводить содержимое списка [`garbage`](https://python-all.ru/3.15/library/gc.html#gc.garbage) при [завершении интерпретатора](https://python-all.ru/3.15/glossary.html#term-interpreter-shutdown), если он не пуст.230231#### `gc.DEBUG_SAVEALL`232233Если установлен, все найденные недостижимые объекты будут добавляться в *garbage*, а не освобождаться. Это может быть полезно для отладки программы с утечками.234235#### `gc.DEBUG_LEAK`236237Флаги отладки, необходимые для вывода сборщиком информации о программе с утечками (равно `DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE | DEBUG_SAVEALL`).238