gc — Garbage Collector interface

---

Цей модуль забезпечує інтерфейс для додаткового збирача сміття. Він надає можливість вимкнути збирач, налаштувати частоту збирання та встановити параметри налагодження. Він також надає доступ до недоступних об’єктів, які збирач знайшов, але не може звільнити. Оскільки збирач доповнює підрахунок посилань, який уже використовується в 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)

Perform a collection. The optional argument generation may be an integer specifying which generation to collect (from 0 to 2). A ValueError is raised if the generation number is invalid. The sum of collected objects and uncollectable objects is returned.

Calling gc.collect(0) will perform a GC collection on the young generation.

Calling gc.collect(1) will perform a GC collection on the young generation and an increment of the old generation.

Calling gc.collect(2) or gc.collect() performs a full collection

Безкоштовні списки, які підтримуються для ряду вбудованих типів, очищаються щоразу, коли запускається повна колекція або колекція найвищого покоління (2). Не всі елементи в деяких вільних списках можуть бути звільнені через певну реалізацію, зокрема float.

The effect of calling gc.collect() while the interpreter is already performing a collection is undefined.

Змінено в версії 3.13: generation=1 performs an increment of collection.

gc.set_debug(flags)

Встановіть позначки налагодження збору сміття. Інформація про налагодження буде записана в sys.stderr. Нижче наведено список прапорів налагодження, які можна комбінувати за допомогою бітових операцій для керування налагодженням.

gc.get_debug()

Повернути поточні встановлені позначки налагодження.

gc.get_objects(generation=None)

Returns a list of all objects tracked by the collector, excluding the list returned. If generation is not None, return only the objects as follows:

• 0: All objects in the young generation

• 1: No objects, as there is no generation 1 (as of Python 3.13)

• 2: All objects in the old generation

Змінено в версії 3.8: Новий параметр generation.

Змінено в версії 3.13: Generation 1 is removed

Викликає подію аудиту gc.get_objects з аргументом generation.

gc.get_stats()

Повертає список із трьох словників для кожного покоління, що містить статистику збору з моменту запуску інтерпретатора. У майбутньому кількість ключів може змінитися, але наразі кожен словник міститиме такі елементи:

• колекції — це кількість разів, коли було зібрано це покоління;

• collected - це загальна кількість об’єктів, зібраних у цій генерації;

• uncollectable — це загальна кількість об’єктів, які були визнані такими, що неможливо зібрати (і тому були переміщені до списку garbage) у цьому поколінні.

Added in version 3.4.

gc.set_threshold(threshold0[, threshold1[, threshold2]])

Встановіть порогові значення збору сміття (частоту збору). Встановлення threshold0 на нуль вимикає збір.

The GC classifies objects into two generations depending on whether they have survived a collection. New objects are placed in the young generation. If an object survives a collection it is moved into the old generation.

In order to decide when to run, the collector keeps track of the number of object allocations and deallocations since the last collection. When the number of allocations minus the number of deallocations exceeds threshold0, collection starts. For each collection, all the objects in the young generation and some fraction of the old generation is collected.

The fraction of the old generation that is collected is inversely proportional to threshold1. The larger threshold1 is, the slower objects in the old generation are collected. For the default value of 10, 1% of the old generation is scanned during each collection.

threshold2 is ignored.

See Garbage collector design for more information.

Змінено в версії 3.13: threshold2 is ignored

gc.get_count()

Повертає поточну колекцію підрахунків як кортеж (count0, count1, count2).

gc.get_threshold()

Повертає поточні порогові значення збору як кортеж (threshold0, threshold1, threshold2).

gc.get_referrers(*objs)

Повертає список об’єктів, які безпосередньо посилаються на будь-який з об’єктів. Ця функція знаходитиме лише ті контейнери, які підтримують збір сміття; типи розширень, які посилаються на інші об’єкти, але не підтримують збирання сміття, не будуть знайдені.

Зауважте, що об’єкти, які вже було розіменовано, але які живуть у циклах і ще не були зібрані збирачем сміття, можуть бути перераховані серед отриманих посилань. Щоб отримати лише активні об’єкти, викликайте collect() перед викликом get_referrers().

Попередження

Необхідно бути обережним, використовуючи об’єкти, які повертає get_referrers(), тому що деякі з них все ще можуть перебувати в стадії розробки і, отже, у тимчасово недійсному стані. Уникайте використання get_referrers() для будь-яких цілей, окрім налагодження.

Викликає подію аудиту gc.get_referrers з аргументом objs.

gc.get_referents(*objs)

Повертає список об’єктів, на які безпосередньо посилається будь-який з аргументів. Повернуті референти — це ті об’єкти, відвідані методами аргументів C-level tp_traverse (якщо такі є), і можуть бути не всі об’єкти, фактично доступні безпосередньо. tp_traverse методи підтримуються лише об’єктами, які підтримують збирання сміття, і потрібні лише для відвідування об’єктів, які можуть брати участь у циклі. Так, наприклад, якщо ціле число доступне безпосередньо з аргументу, цей цілочисельний об’єкт може з’явитися або не з’явитися у списку результатів.

Викликає подію аудиту gc.get_referents з аргументом objs.

gc.is_tracked(obj)

Повертає True, якщо об’єкт наразі відстежується збирачем сміття, False інакше. Як правило, екземпляри атомарних типів не відстежуються, а екземпляри неатомарних типів (контейнери, об’єкти, визначені користувачем…) відстежуються. Проте деякі типи оптимізації можуть бути присутні, щоб придушити слід збирача сміття простих екземплярів (наприклад, dicts, що містять лише атомарні ключі та значення):

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

Added in version 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

Added in version 3.9.

gc.freeze()

Freeze all the objects tracked by the garbage collector; move them to a permanent generation and ignore them in all the future collections.

If a process will fork() without exec(), avoiding unnecessary copy-on-write in child processes will maximize memory sharing and reduce overall memory usage. This requires both avoiding creation of freed «holes» in memory pages in the parent process and ensuring that GC collections in child processes won’t touch the gc_refs counter of long-lived objects originating in the parent process. To accomplish both, call gc.disable() early in the parent process, gc.freeze() right before fork(), and gc.enable() early in child processes.

Added in version 3.7.

gc.unfreeze()

Розморозити об’єкти в постійному поколінні, повернути їх у найстаріше покоління.

Added in version 3.7.

gc.get_freeze_count()

Повертає кількість об’єктів у постійній генерації.

Added in version 3.7.

Наступні змінні надаються для доступу лише для читання (ви можете змінити значення, але не повинні їх повторно прив’язувати):

gc.garbage

Список об’єктів, які збирач виявив недоступними, але не міг звільнити (незбірні об’єкти). Починаючи з Python 3.4, цей список має бути порожнім більшу частину часу, за винятком випадків використання екземплярів типів розширень C із слотом tp_del, відмінним від NULL.

Якщо встановлено DEBUG_SAVEALL, усі недоступні об’єкти будуть додані до цього списку, а не звільнені.

Змінено в версії 3.2: Якщо цей список не порожній під час interpreter shutdown, видається ResourceWarning, яке за замовчуванням мовчить. Якщо встановлено DEBUG_UNCOLLECTABLE, додатково друкуються всі об’єкти, які неможливо зібрати.

Змінено в версії 3.4: Following PEP 442, objects with a __del__() method don’t end up in gc.garbage anymore.

gc.callbacks

Список зворотних викликів, які будуть викликані збирачем сміття до і після збирання. Зворотні виклики будуть викликані з двома аргументами, phase та info.

phase може бути одним із двох значень:

«start»: збирання сміття ось-ось розпочнеться.

«стоп»: збирання сміття завершено.

info — це dict, що надає більше інформації для зворотного виклику. Наразі визначено такі ключі:

«генерація»: збирається найстаріше покоління.

«collected»: коли phase має значення «stop», кількість успішно зібраних об’єктів.

«uncollectable»: коли phase має значення «stop», кількість об’єктів, які не вдалося зібрати та були поміщені в garbage.

Програми можуть додавати власні зворотні виклики до цього списку. Основні випадки використання:

Збір статистики щодо збирання сміття, наприклад, як часто збираються різні покоління та скільки часу займає збір.

Дозволяє програмам ідентифікувати та очищати власні типи, які не можна збирати, коли вони з’являються в garbage.

Added in version 3.3.

Наступні константи надаються для використання з set_debug():

gc.DEBUG_STATS

Роздрукувати статистику під час збору. Ця інформація може бути корисною під час налаштування частоти збору.

gc.DEBUG_COLLECTABLE

Роздрукуйте інформацію про знайдені предмети колекціонування.

gc.DEBUG_UNCOLLECTABLE

Друк інформації про знайдені об’єкти, які не можна збирати (об’єкти, які недоступні, але не можуть бути звільнені колекціонером). Ці об’єкти будуть додані до списку сміття.

Змінено в версії 3.2: Також вивести вміст списку garbage у interpreter shutdown, якщо він не порожній.

gc.DEBUG_SAVEALL

Якщо встановлено, усі знайдені недоступні об’єкти будуть додані до сміття, а не звільнені. Це може бути корисно для налагодження витоку програми.

gc.DEBUG_LEAK

Прапори налагодження, необхідні збирачеві для друку інформації про витік програми (рівні DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE | DEBUG_SAVEALL).