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.

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) у цьому поколінні.

Нове в версії 3.4.

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

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

The GC classifies objects into three generations depending on how many collection sweeps they have survived. New objects are placed in the youngest generation (generation 0). If an object survives a collection it is moved into the next older generation. Since generation 2 is the oldest generation, objects in that generation remain there after a collection. In order to decide when to run, the collector keeps track of the number object allocations and deallocations since the last collection. When the number of allocations minus the number of deallocations exceeds threshold0, collection starts. Initially only generation 0 is examined. If generation 0 has been examined more than threshold1 times since generation 1 has been examined, then generation 1 is examined as well. With the third generation, things are a bit more complicated, see Collecting the oldest generation for more information.

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

Нове в версії 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()

Freeze all the objects tracked by gc - move them to a permanent generation and ignore all the future collections. This can be used before a POSIX fork() call to make the gc copy-on-write friendly or to speed up collection. Also collection before a POSIX fork() call may free pages for future allocation which can cause copy-on-write too so it’s advised to disable gc in parent process and freeze before fork and enable gc in child process.

Нове в версії 3.7.

gc.unfreeze()

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

Нове в версії 3.7.

gc.get_freeze_count()

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

Нове в версії 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.

Нове в версії 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).