gcsupport.md
1> **Источник:** https://python-all.ru/3.16/c-api/gcsupport.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Поддержка циклической сборки мусора89Поддержка Python обнаружения и сбора мусора, связанного с циклическими ссылками, требует поддержки со стороны объектных типов, которые являются «контейнерами» для других объектов, которые также могут быть контейнерами. Типы, которые не хранят ссылок на другие объекты или хранят только ссылки на атомарные типы (например, числа или строки), не нуждаются в явной поддержке сборки мусора.1011Чтобы создать контейнерный тип, поле [`tp_flags`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_flags) объекта типа должно включать [`Py_TPFLAGS_HAVE_GC`](https://python-all.ru/3.16/c-api/typeobj.html#c.Py_TPFLAGS_HAVE_GC) и предоставлять реализацию обработчика [`tp_traverse`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_traverse). Если экземпляры типа являются изменяемыми, также должна быть предоставлена реализация [`tp_clear`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_clear).1213**[`Py_TPFLAGS_HAVE_GC`](https://python-all.ru/3.16/c-api/typeobj.html#c.Py_TPFLAGS_HAVE_GC)**1415Объекты с типом, у которого установлен этот флаг, должны соответствовать правилам, описанным здесь. Для удобства такие объекты будут называться контейнерными объектами.1617Конструкторы контейнерных типов должны соответствовать двум правилам:18191. Память для объекта должна выделяться с помощью [`PyObject_GC_New`](https://python-all.ru/3.16/c-api/gcsupport.html#c.PyObject_GC_New) или [`PyObject_GC_NewVar`](https://python-all.ru/3.16/c-api/gcsupport.html#c.PyObject_GC_NewVar).202. Как только все поля, которые могут содержать ссылки на другие контейнеры, будут инициализированы, необходимо вызвать [`PyObject_GC_Track()`](https://python-all.ru/3.16/c-api/gcsupport.html#c.PyObject_GC_Track).2122Аналогично, деаллокатор объекта должен соответствовать такой же паре правил:23241. Перед тем как поля, ссылающиеся на другие контейнеры, станут недействительными, должен быть вызван [`PyObject_GC_UnTrack()`](https://python-all.ru/3.16/c-api/gcsupport.html#c.PyObject_GC_UnTrack).252. Память объекта должна быть освобождена с помощью [`PyObject_GC_Del()`](https://python-all.ru/3.16/c-api/gcsupport.html#c.PyObject_GC_Del).2627 > **Предупреждение**28 >29 > Если тип добавляет Py\_TPFLAGS\_HAVE\_GC, то он *должен* реализовать как минимум обработчик [`tp_traverse`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_traverse) или явно использовать его из своего подкласса или подклассов.30 >31 > При вызове [`PyType_Ready()`](https://python-all.ru/3.16/c-api/type.html#c.PyType_Ready) или некоторых API, которые вызывают его косвенно, таких как [`PyType_FromSpecWithBases()`](https://python-all.ru/3.16/c-api/type.html#c.PyType_FromSpecWithBases) или [`PyType_FromSpec()`](https://python-all.ru/3.16/c-api/type.html#c.PyType_FromSpec), интерпретатор автоматически заполнит поля [`tp_flags`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_flags), [`tp_traverse`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_traverse) и [`tp_clear`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_clear), если тип наследуется от класса, реализующего протокол сборщика мусора, и дочерний класс *не* включает флаг [`Py_TPFLAGS_HAVE_GC`](https://python-all.ru/3.16/c-api/typeobj.html#c.Py_TPFLAGS_HAVE_GC).3233#### `PyObject_GC_New(TYPE, typeobj)`3435Аналогично [`PyObject_New`](https://python-all.ru/3.16/c-api/allocation.html#c.PyObject_New), но для контейнерных объектов с установленным флагом [`Py_TPFLAGS_HAVE_GC`](https://python-all.ru/3.16/c-api/typeobj.html#c.Py_TPFLAGS_HAVE_GC).3637Не вызывайте это напрямую для выделения памяти под объект; вместо этого вызывайте слот [`tp_alloc`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_alloc) типа.3839При заполнении слота [`tp_alloc`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_alloc) типа предпочтительнее использовать [`PyType_GenericAlloc()`](https://python-all.ru/3.16/c-api/type.html#c.PyType_GenericAlloc), а не собственную функцию, которая просто вызывает этот макрос.4041Память, выделенная этим макросом, должна быть освобождена с помощью [`PyObject_GC_Del()`](https://python-all.ru/3.16/c-api/gcsupport.html#c.PyObject_GC_Del) (обычно вызывается через слот [`tp_free`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_free) объекта).4243> **См. также**44>45> - [`PyObject_GC_Del()`](https://python-all.ru/3.16/c-api/gcsupport.html#c.PyObject_GC_Del)46> - [`PyObject_New`](https://python-all.ru/3.16/c-api/allocation.html#c.PyObject_New)47> - [`PyType_GenericAlloc()`](https://python-all.ru/3.16/c-api/type.html#c.PyType_GenericAlloc)48> - [`tp_alloc`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_alloc)4950#### `PyObject_GC_NewVar(TYPE, typeobj, size)`5152Аналогично [`PyObject_NewVar`](https://python-all.ru/3.16/c-api/allocation.html#c.PyObject_NewVar), но для контейнерных объектов с установленным флагом [`Py_TPFLAGS_HAVE_GC`](https://python-all.ru/3.16/c-api/typeobj.html#c.Py_TPFLAGS_HAVE_GC).5354Не вызывайте это напрямую для выделения памяти под объект; вместо этого вызывайте слот [`tp_alloc`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_alloc) типа.5556При заполнении слота [`tp_alloc`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_alloc) типа предпочтительнее использовать [`PyType_GenericAlloc()`](https://python-all.ru/3.16/c-api/type.html#c.PyType_GenericAlloc), а не собственную функцию, которая просто вызывает этот макрос.5758Память, выделенная этим макросом, должна быть освобождена с помощью [`PyObject_GC_Del()`](https://python-all.ru/3.16/c-api/gcsupport.html#c.PyObject_GC_Del) (обычно вызывается через слот [`tp_free`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_free) объекта).5960> **См. также**61>62> - [`PyObject_GC_Del()`](https://python-all.ru/3.16/c-api/gcsupport.html#c.PyObject_GC_Del)63> - [`PyObject_NewVar`](https://python-all.ru/3.16/c-api/allocation.html#c.PyObject_NewVar)64> - [`PyType_GenericAlloc()`](https://python-all.ru/3.16/c-api/type.html#c.PyType_GenericAlloc)65> - [`tp_alloc`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_alloc)6667#### `PyObject *PyUnstable_Object_GC_NewWithExtraData(PyTypeObject *type, size_t extra_size)`6869> *Это [нестабильное API](https://python-all.ru/3.16/c-api/stable.html#unstable-c-api). Оно может меняться без предупреждения в минорных версиях.*7071Аналог [`PyObject_GC_New`](https://python-all.ru/3.16/c-api/gcsupport.html#c.PyObject_GC_New), но выделяет *extra\_size* байт в конце объекта (по смещению [`tp_basicsize`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_basicsize)). Выделенная память обнуляется, за исключением [`Python object header`](https://python-all.ru/3.16/c-api/structures.html#c.PyObject).7273Дополнительные данные будут освобождены вместе с объектом, но в остальном Python ими не управляет.7475Память, выделенная этой функцией, должна освобождаться через [`PyObject_GC_Del()`](https://python-all.ru/3.16/c-api/gcsupport.html#c.PyObject_GC_Del) (обычно вызывается через слот [`tp_free`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_free) объекта).7677> **Предупреждение**78>79> Функция помечена как нестабильная, потому что окончательный механизм резервирования дополнительных данных после экземпляра ещё не определён. Для выделения переменного числа полей предпочтительнее использовать [`PyVarObject`](https://python-all.ru/3.16/c-api/structures.html#c.PyVarObject) и [`tp_itemsize`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_itemsize).8081Добавлено в версии 3.12.8283#### `PyObject_GC_Resize(TYPE, op, newsize)`8485Изменяет размер объекта, выделенного через [`PyObject_NewVar`](https://python-all.ru/3.16/c-api/allocation.html#c.PyObject_NewVar). Возвращает объект нового размера типа `TYPE*` (ссылается на любой тип C) или `NULL` в случае ошибки.8687*op* должен иметь тип [PyVarObject](https://python-all.ru/3.16/c-api/structures.html#c.PyVarObject)\* и ещё не отслеживаться сборщиком. *newsize* должен иметь тип [`Py_ssize_t`](https://python-all.ru/3.16/c-api/intro.html#c.Py_ssize_t).8889#### `void PyObject_GC_Track(PyObject *op)`9091*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*9293Добавляет объект *op* в набор контейнерных объектов, отслеживаемых сборщиком. Сборщик может запускаться в неожиданные моменты, поэтому объекты должны быть корректны во время отслеживания. Эту функцию следует вызывать, когда все поля, за которыми следит обработчик [`tp_traverse`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_traverse), станут корректны, обычно ближе к концу конструктора.9495#### `int PyObject_IS_GC(PyObject *obj)`9697Возвращает ненулевое значение, если объект реализует протокол сборщика мусора, иначе возвращает 0.9899Объект не может отслеживаться сборщиком мусора, если эта функция возвращает 0.100101#### `int PyObject_GC_IsTracked(PyObject *op)`102103*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.9.*104105Возвращает 1, если тип объекта *op* реализует протокол GC и *op* в данный момент отслеживается сборщиком мусора, и 0 в противном случае.106107Это аналог функции Python [`gc.is_tracked()`](https://python-all.ru/3.16/library/gc.html#gc.is_tracked).108109Добавлено в версии 3.9.110111#### `int PyObject_GC_IsFinalized(PyObject *op)`112113*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.9.*114115Возвращает 1, если тип объекта *op* реализует протокол GC и *op* уже был финализирован сборщиком мусора, и 0 в противном случае.116117Это аналог функции Python [`gc.is_finalized()`](https://python-all.ru/3.16/library/gc.html#gc.is_finalized).118119Добавлено в версии 3.9.120121#### `void PyObject_GC_Del(void *op)`122123*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*124125Освобождает память, выделенную объекту через [`PyObject_GC_New`](https://python-all.ru/3.16/c-api/gcsupport.html#c.PyObject_GC_New) или [`PyObject_GC_NewVar`](https://python-all.ru/3.16/c-api/gcsupport.html#c.PyObject_GC_NewVar).126127Не вызывайте это напрямую для освобождения памяти объекта; вместо этого вызывайте слот [`tp_free`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_free) типа.128129Не используйте это для памяти, выделенной [`PyObject_New`](https://python-all.ru/3.16/c-api/allocation.html#c.PyObject_New), [`PyObject_NewVar`](https://python-all.ru/3.16/c-api/allocation.html#c.PyObject_NewVar) или связанными функциями выделения; используйте [`PyObject_Free()`](https://python-all.ru/3.16/c-api/memory.html#c.PyObject_Free).130131> **См. также**132>133> - [`PyObject_Free()`](https://python-all.ru/3.16/c-api/memory.html#c.PyObject_Free) – это эквивалент этой функции без GC.134> - [`PyObject_GC_New`](https://python-all.ru/3.16/c-api/gcsupport.html#c.PyObject_GC_New)135> - [`PyObject_GC_NewVar`](https://python-all.ru/3.16/c-api/gcsupport.html#c.PyObject_GC_NewVar)136> - [`PyType_GenericAlloc()`](https://python-all.ru/3.16/c-api/type.html#c.PyType_GenericAlloc)137> - [`tp_free`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_free)138139#### `void PyObject_GC_UnTrack(void *op)`140141*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*142143Удаляет объект *op* из набора контейнерных объектов, отслеживаемых сборщиком. Обратите внимание, что [`PyObject_GC_Track()`](https://python-all.ru/3.16/c-api/gcsupport.html#c.PyObject_GC_Track) можно снова вызвать для этого объекта, чтобы вернуть его в набор отслеживаемых объектов. Деструктор (обработчик [`tp_dealloc`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_dealloc)) должен вызывать это для объекта до того, как какие-либо поля, используемые обработчиком [`tp_traverse`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_traverse), станут недействительными.144145Изменено в версии 3.8: Макросы `_PyObject_GC_TRACK()` и `_PyObject_GC_UNTRACK()` были удалены из публичного C API.146147Обработчик [`tp_traverse`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_traverse) принимает параметр-функцию следующего типа:148149#### `typedef int (*visitproc)(PyObject *object, void *arg)`150151*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*152153Тип функции обхода, передаваемой обработчику [`tp_traverse`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_traverse). Функцию следует вызывать с объектом для обхода в качестве *object* и третьим параметром обработчика `tp_traverse` в качестве *arg*. Ядро Python использует несколько функций обхода для реализации обнаружения циклического мусора; не ожидается, что пользователям потребуется писать собственные функции обхода.154155Обработчик [`tp_clear`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_clear) должен иметь тип [`inquiry`](https://python-all.ru/3.16/c-api/gcsupport.html#c.inquiry) или `NULL`, если объект неизменяем.156157#### `typedef int (*inquiry)(PyObject *self)`158159*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*160161Удаляет ссылки, которые могли создать циклические ссылки. Неизменяемые объекты не обязаны определять этот метод, поскольку они никогда не могут напрямую создавать циклические ссылки. Обратите внимание, что объект после вызова этого метода должен оставаться корректным (нельзя просто вызвать [`Py_DECREF()`](https://python-all.ru/3.16/c-api/refcounting.html#c.Py_DECREF) для ссылки). Сборщик вызовет этот метод, если обнаружит, что этот объект участвует в циклической ссылке.162163## Обход164165Обработчик [`tp_traverse`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_traverse) должен иметь следующий тип:166167#### `typedef int (*traverseproc)(PyObject *self, visitproc visit, void *arg)`168169*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*170171Функция обхода для объекта, подлежащего сборке мусора, используется сборщиком мусора для обнаружения циклических ссылок. Реализации должны вызывать функцию *visit* для каждого объекта, непосредственно содержащегося в *self*, с параметрами *visit*: содержащийся объект и значение *arg*, переданное обработчику. Функция *visit* не должна вызываться с аргументом `NULL` объекта. Если *visit* возвращает ненулевое значение, это значение должно быть возвращено немедленно.172173Типичная функция `tp_traverse` вызывает удобный макрос [`Py_VISIT()`](https://python-all.ru/3.16/c-api/gcsupport.html#c.Py_VISIT) для каждого из членов экземпляра, которые являются объектами Python, которыми владеет экземпляр. Например, это (слегка устаревшая) функция обхода для класса [`threading.local`](https://python-all.ru/3.16/library/threading.html#threading.local):174175```c176static int177local_traverse(PyObject *op, visitproc visit, void *arg)178{179 localobject *self = (localobject *) op;180 Py_VISIT(Py_TYPE(self));181 Py_VISIT(self->args);182 Py_VISIT(self->kw);183 Py_VISIT(self->dict);184 return 0;185}186```187188> **Примечание**189>190> [`Py_VISIT()`](https://python-all.ru/3.16/c-api/gcsupport.html#c.Py_VISIT) требует, чтобы параметры *visit* и *arg* в `local_traverse()` имели именно эти имена; не называйте их произвольно.191192Экземпляры [типов, выделяемых в куче](https://python-all.ru/3.16/c-api/typeobj.html#heap-types), содержат ссылку на свой тип. Поэтому их функция обхода должна посетить тип:193194```c195Py_VISIT(Py_TYPE(self));196```197198В качестве альтернативы, тип может делегировать эту ответственность, вызывая `tp_traverse` суперкласса, выделенного в куче (или другого типа, выделенного в куче, если применимо). Если этого не сделать, объект типа может не быть собран сборщиком мусора.199200Если бит [`Py_TPFLAGS_MANAGED_DICT`](https://python-all.ru/3.16/c-api/typeobj.html#c.Py_TPFLAGS_MANAGED_DICT) установлен в поле [`tp_flags`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_flags), функция обхода должна вызвать [`PyObject_VisitManagedDict()`](https://python-all.ru/3.16/c-api/object.html#c.PyObject_VisitManagedDict) следующим образом:201202```c203int err = PyObject_VisitManagedDict((PyObject*)self, visit, arg);204if (err) {205 return err;206}207```208209Посещать нужно только те члены, которыми экземпляр *владеет* (имея на них [сильные ссылки](https://python-all.ru/3.16/glossary.html#term-strong-reference)). Например, если объект поддерживает слабые ссылки через слот [`tp_weaklist`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_weaklist), указатель, поддерживающий связный список (то, на что указывает *tp\_weaklist*), **не** должен посещаться, так как экземпляр не владеет напрямую слабыми ссылками на себя.210211Функция обхода имеет ограничение:212213> **Предупреждение**214>215> Функция обхода не должна иметь никаких побочных эффектов. Реализации не должны изменять счетчики ссылок каких-либо объектов Python, а также создавать или уничтожать какие-либо объекты Python прямо или косвенно.216217Это означает, что *большинство* функций Python C API нельзя использовать, поскольку они могут вызывать новое исключение, возвращать новую ссылку на объект-результат, иметь внутреннюю логику, использующую побочные эффекты. Кроме того, если не указано иное, функции, которые в настоящее время не имеют побочных эффектов, могут начать их иметь в будущих версиях без предупреждения.218219Список безопасных функций см. в [отдельном разделе](https://python-all.ru/3.16/c-api/gcsupport.html#duringgc-functions) ниже.220221> **Примечание**222>223> Вызов [`Py_VISIT()`](https://python-all.ru/3.16/c-api/gcsupport.html#c.Py_VISIT) можно пропустить для тех членов, которые заведомо не могут участвовать в циклических ссылках. В примере `local_traverse` выше также есть член `self->key`, но он может быть только `NULL` или строкой Python, и поэтому не может быть частью циклической ссылки.224>225> С другой стороны, даже если вы знаете, что член никогда не может быть частью цикла, в качестве средства отладки вы можете захотеть все равно посетить его, чтобы функция [`get_referents()`](https://python-all.ru/3.16/library/gc.html#gc.get_referents) модуля [`gc`](https://python-all.ru/3.16/library/gc.html#module-gc) включала его.226227> **Примечание**228>229> Функцию [`tp_traverse`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_traverse) можно вызывать из любого потока.230>231> **Деталь реализации CPython:** Сборка мусора – это операция «остановки мира»: даже в сборках [free threading](https://python-all.ru/3.16/glossary.html#term-free-threading), когда запускаются обработчики `tp_traverse`, прикреплено только одно состояние потока [attached](https://python-all.ru/3.16/glossary.html#term-attached-thread-state).232233Изменено в версии 3.9: Ожидается, что типы, выделяемые в куче, будут посещать `Py_TYPE(self)` в `tp_traverse`. В более ранних версиях Python из-за [ошибки 40217](https://python-all.ru/3.16/c-api/gcsupport.html) это могло приводить к сбоям в подклассах.234235Для упрощения написания обработчиков [`tp_traverse`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_traverse) предоставляется макрос [`Py_VISIT()`](https://python-all.ru/3.16/c-api/gcsupport.html#c.Py_VISIT). Чтобы использовать этот макрос, реализация `tp_traverse` должна называть свои аргументы именно *visit* и *arg*:236237#### `Py_VISIT(o)`238239Если [PyObject](https://python-all.ru/3.16/c-api/structures.html#c.PyObject)\* *o* не является `NULL`, вызвать колбэк *visit* с аргументами *o* и *arg*. Если *visit* возвращает ненулевое значение, вернуть его.240241Это примерно соответствует:242243```c244#define Py_VISIT(o) \245 if (op) { \246 int visit_result = visit(o, arg); \247 if (visit_result != 0) { \248 return visit_result; \249 } \250 }251```252253### Функции, безопасные для обхода254255Следующие функции и макросы безопасно использовать в обработчике [`tp_traverse`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_traverse):256257- функция *visit*, передаваемая в `tp_traverse`258- [`Py_VISIT()`](https://python-all.ru/3.16/c-api/gcsupport.html#c.Py_VISIT)259- [`Py_SIZE()`](https://python-all.ru/3.16/c-api/structures.html#c.Py_SIZE)260- [`Py_TYPE()`](https://python-all.ru/3.16/c-api/structures.html#c.Py_TYPE): если вызывается из обработчика `tp_traverse`, результат `Py_TYPE()` будет действителен в течение вызова обработчика261- [`PyObject_VisitManagedDict()`](https://python-all.ru/3.16/c-api/object.html#c.PyObject_VisitManagedDict)262- [`PyObject_TypeCheck()`](https://python-all.ru/3.16/c-api/object.html#c.PyObject_TypeCheck), [`PyType_IsSubtype()`](https://python-all.ru/3.16/c-api/type.html#c.PyType_IsSubtype), [`PyType_HasFeature()`](https://python-all.ru/3.16/c-api/type.html#c.PyType_HasFeature)263- `Py<type>_Check` и `Py<type>_CheckExact` – например, [`PyTuple_Check()`](https://python-all.ru/3.16/c-api/tuple.html#c.PyTuple_Check)264- [Функции «DuringGC»](https://python-all.ru/3.16/c-api/gcsupport.html#duringgc-functions)265266### Функции «DuringGC»267268Следующие функции следует использовать *только* в обработчике [`tp_traverse`](https://python-all.ru/3.16/c-api/typeobj.html#c.PyTypeObject.tp_traverse); вызов их в других контекстах может иметь непреднамеренные последствия.269270Эти функции действуют как их аналоги без суффикса `_DuringGC`, но гарантированно не имеют побочных эффектов, не устанавливают исключение при сбое и возвращают/устанавливают [заимствованные ссылки](https://python-all.ru/3.16/glossary.html#term-borrowed-reference), как описано в соответствующей документации.271272Обратите внимание, что эти функции могут завершиться ошибкой (вернуть `NULL` или `-1`), но поскольку они не устанавливают исключение, информация об ошибке недоступна. В некоторых случаях сбой невозможно отличить от успешного результата `NULL`.273274#### `void *PyObject_GetTypeData_DuringGC(PyObject *o, PyTypeObject *cls)`275276#### `void *PyObject_GetItemData_DuringGC(PyObject *o)`277278#### `void *PyType_GetModuleState_DuringGC(PyTypeObject *type)`279280#### `void *PyModule_GetState_DuringGC(PyObject *module)`281282#### `int PyModule_GetToken_DuringGC(PyObject *module, void **result)`283284*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.15.*285286Смотрите [функции “DuringGC”](https://python-all.ru/3.16/c-api/gcsupport.html#duringgc-functions) для общей информации.287288Добавлено в версии 3.15.289290> **См. также**291>292> [`PyObject_GetTypeData()`](https://python-all.ru/3.16/c-api/object.html#c.PyObject_GetTypeData), [`PyObject_GetItemData()`](https://python-all.ru/3.16/c-api/object.html#c.PyObject_GetItemData), [`PyType_GetModuleState()`](https://python-all.ru/3.16/c-api/type.html#c.PyType_GetModuleState), [`PyModule_GetState()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_GetState), [`PyModule_GetToken()`](https://python-all.ru/3.16/c-api/module.html#c.PyModule_GetToken), [`PyType_GetBaseByToken()`](https://python-all.ru/3.16/c-api/type.html#c.PyType_GetBaseByToken)293294#### `int PyType_GetBaseByToken_DuringGC(PyTypeObject *type, void *tp_token, PyTypeObject **result)`295296*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.15.*297298Смотрите [функции “DuringGC”](https://python-all.ru/3.16/c-api/gcsupport.html#duringgc-functions) для общей информации.299300Устанавливает *\*result* в [заимствованную ссылку](https://python-all.ru/3.16/glossary.html#term-borrowed-reference), а не сильную. Ссылка действительна на время вызова обработчика `tp_traverse`.301302Добавлено в версии 3.15.303304> **См. также**305>306> [`PyType_GetBaseByToken()`](https://python-all.ru/3.16/c-api/type.html#c.PyType_GetBaseByToken)307308#### `PyObject *PyType_GetModule_DuringGC(PyTypeObject *type)`309310#### `PyObject *PyType_GetModuleByToken_DuringGC(PyTypeObject *type, const void *mod_token)`311312*Возвращаемое значение: заимствованная ссылка.*313314*Часть [стабильного ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.15.*315316Смотрите [функции “DuringGC”](https://python-all.ru/3.16/c-api/gcsupport.html#duringgc-functions) для общей информации.317318Эти функции возвращают [заимствованную ссылку](https://python-all.ru/3.16/glossary.html#term-borrowed-reference), которая действительна на время вызова обработчика `tp_traverse`.319320Добавлено в версии 3.15.321322> **См. также**323>324> [`PyType_GetModule()`](https://python-all.ru/3.16/c-api/type.html#c.PyType_GetModule), [`PyType_GetModuleByToken()`](https://python-all.ru/3.16/c-api/type.html#c.PyType_GetModuleByToken)325326## Управление состоянием сборщика мусора327328C-API предоставляет следующие функции для управления запусками сборки мусора.329330#### `Py_ssize_t PyGC_Collect(void)`331332*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*333334Выполняет полную сборку мусора, если сборщик мусора включён. (Обратите внимание, что [`gc.collect()`](https://python-all.ru/3.16/library/gc.html#gc.collect) запускает её безусловно.)335336Возвращает количество собранных + недостижимых объектов, которые не могут быть собраны. Если сборщик мусора отключён или уже выполняет сборку, немедленно возвращает `0`. Ошибки во время сборки мусора передаются в [`sys.unraisablehook`](https://python-all.ru/3.16/library/sys.html#sys.unraisablehook). Эта функция не вызывает исключений.337338#### `int PyGC_Enable(void)`339340*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.10.*341342Включает сборщик мусора: аналогично [`gc.enable()`](https://python-all.ru/3.16/library/gc.html#gc.enable). Возвращает предыдущее состояние: 0 – отключён, 1 – включён.343344Добавлено в версии 3.10.345346#### `int PyGC_Disable(void)`347348*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.10.*349350Отключает сборщик мусора: аналогично [`gc.disable()`](https://python-all.ru/3.16/library/gc.html#gc.disable). Возвращает предыдущее состояние: 0 – отключён, 1 – включён.351352Добавлено в версии 3.10.353354#### `int PyGC_IsEnabled(void)`355356*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.10.*357358Запрашивает состояние сборщика мусора: аналогично [`gc.isenabled()`](https://python-all.ru/3.16/library/gc.html#gc.isenabled). Возвращает текущее состояние: 0 – отключён, 1 – включён.359360Добавлено в версии 3.10.361362## Запрос состояния сборщика мусора363364C-API предоставляет следующий интерфейс для запроса информации о сборщике мусора.365366#### `void PyUnstable_GC_VisitObjects(gcvisitobjects_t callback, void *arg)`367368> *Это [нестабильное API](https://python-all.ru/3.16/c-api/stable.html#unstable-c-api). Оно может меняться без предупреждения в минорных версиях.*369370Вызывает переданный *колбэк* для всех живых объектов, поддерживающих GC. *arg* передаётся во все вызовы *колбэк*.371372> **Предупреждение**373>374> Если колбэк выделяет или освобождает новые объекты, то не определено, будут ли они посещены.375>376> Во время работы сборка мусора отключена. Явный запуск сборки в колбэке может привести к неопределённому поведению, например, к посещению одних и тех же объектов несколько раз или ни разу.377378Добавлено в версии 3.12.379380#### `typedef int (*gcvisitobjects_t)(PyObject *object, void *arg)`381382Тип функции-посетителя, передаваемой в [`PyUnstable_GC_VisitObjects()`](https://python-all.ru/3.16/c-api/gcsupport.html#c.PyUnstable_GC_VisitObjects). Параметр *arg* – то же самое, что *arg*, переданный в `PyUnstable_GC_VisitObjects`. Возвращайте `1` для продолжения итерации, `0` – для остановки. Остальные возвращаемые значения пока зарезервированы, поэтому поведение при возврате чего-либо другого не определено.383384Добавлено в версии 3.12.385