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)

With no arguments, run a full 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 number of unreachable objects found is returned.

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

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

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 tracked by the collector that are in that generation.

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

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

gc.get_stats()

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

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

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

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

Added in version 3.4.

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

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

GC класифікує об’єкти за трьома поколіннями залежно від того, скільки циклів збирання вони пережили. Нові об’єкти поміщаються в наймолодше покоління (генерація 0). Якщо об’єкт переживає колекцію, він переміщується до наступного старшого покоління. Оскільки покоління 2 є найстарішим поколінням, об’єкти цього покоління залишаються там після колекції. Щоб вирішити, коли запускати, збирач відстежує кількість виділень і звільнень об’єктів з моменту останнього збору. Коли кількість виділень мінус кількість звільнень перевищує поріг0, починається збір. Спочатку перевіряється лише покоління 0. Якщо покоління 0 перевірялося більше ніж threshold1 разів після перевірки покоління 1, тоді також перевіряється покоління 1. З третім поколінням все трохи складніше, див. Збір найстарішого покоління для отримання додаткової інформації.

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