# `gc` — Garbage Collector interface

Цей модуль забезпечує інтерфейс для додаткового збирача сміття. Він надає можливість вимкнути збирач, налаштувати частоту збирання та встановити параметри налагодження. Він також надає доступ до недоступних об’єктів, які збирач знайшов, але не може звільнити. Оскільки збирач доповнює підрахунок посилань, який уже використовується в Python, ви можете вимкнути збирач, якщо ви впевнені, що ваша програма не створює цикли посилань. Автоматичний збір можна вимкнути, викликавши `gc.disable()`. Щоб налагодити витік програми, викличте `gc.set_debug(gc.DEBUG_LEAK)`. Зверніть увагу, що це включає `gc.DEBUG_SAVEALL`, змушуючи зібрані об’єкти сміття зберігатися в gc.garbage для перевірки.

The `gc` module provides the following functions:

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.14: `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.14)

  - 2: All objects in the old generation

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

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

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

gc.get_stats()

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

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

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

  - `uncollectable` is the total number of objects which were found to be uncollectable (and were therefore moved to the `garbage` list) inside this generation;

  - `candidates` is the total number of objects in this generation which were considered for collection and traversed;

  - `duration` is the total time in seconds spent in collections for this generation.

  Added in version 3.4.

  Змінено в версії 3.15: Add `duration` and `candidates`.

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.

  In the free-threaded build, the increase in process memory usage is also checked before running the collector. If the memory usage has not increased by 10% since the last collection and the net number of object allocations has not exceeded 40 times threshold0, the collection is not run.

  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.14: 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})
      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`.

  > «candidates»: When phase is «stop», the total number of objects in this generation which were considered for collection and traversed.

  > «duration»: When phase is «stop», the time in seconds spent in the collection.

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

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

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

  Added in version 3.3.

  Змінено в версії 3.15: Add «duration» and «candidates».

Наступні константи надаються для використання з `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`).