This document is for an old version of Python that is no longer supported. You should upgrade, and read the Python documentation for the current stable release.

# `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 на нуль вимикає збір.

  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

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