Поддержка циклической сборки мусора¶Supporting Cyclic Garbage Collection

Обход¶Traversal

Обработчик tp_traverse должен иметь следующий тип:

typedef int (*traverseproc)(PyObject *self, visitproc visit, void *arg)¶

Часть Stable ABI.

Функция обхода для объекта, подлежащего сборке мусора, используется сборщиком мусора для обнаружения циклических ссылок. Реализации должны вызывать функцию visit для каждого объекта, непосредственно содержащегося в self, с параметрами visit: содержащийся объект и значение arg, переданное обработчику. Функция visit не должна вызываться с аргументом NULL объекта. Если visit возвращает ненулевое значение, это значение должно быть возвращено немедленно.

Типичная функция tp_traverse вызывает удобный макрос Py_VISIT() для каждого из членов экземпляра, которые являются объектами Python, которыми владеет экземпляр. Например, это (слегка устаревшая) функция обхода для класса threading.local:

static int
local_traverse(PyObject *op, visitproc visit, void *arg)
{
    localobject *self = (localobject *) op;
    Py_VISIT(Py_TYPE(self));
    Py_VISIT(self->args);
    Py_VISIT(self->kw);
    Py_VISIT(self->dict);
    return 0;
}

Примечание

Py_VISIT() требует, чтобы параметры visit и arg в local_traverse() имели именно эти имена; не называйте их произвольно.

Экземпляры типов, выделяемых в куче, содержат ссылку на свой тип. Поэтому их функция обхода должна посетить тип:

Py_VISIT(Py_TYPE(self));

В качестве альтернативы, тип может делегировать эту ответственность, вызывая tp_traverse суперкласса, выделенного в куче (или другого типа, выделенного в куче, если применимо). Если этого не сделать, объект типа может не быть собран сборщиком мусора.

Если бит Py_TPFLAGS_MANAGED_DICT установлен в поле tp_flags, функция обхода должна вызвать PyObject_VisitManagedDict() следующим образом:

int err = PyObject_VisitManagedDict((PyObject*)self, visit, arg);
if (err) {
    return err;
}

Посещать нужно только те члены, которыми экземпляр владеет (имея на них сильные ссылки). Например, если объект поддерживает слабые ссылки через слот tp_weaklist, указатель, поддерживающий связный список (то, на что указывает tp_weaklist), не должен посещаться, так как экземпляр не владеет напрямую слабыми ссылками на себя.

Функция обхода имеет ограничение:

Предупреждение

Функция обхода не должна иметь никаких побочных эффектов. Реализации не должны изменять счетчики ссылок каких-либо объектов Python, а также создавать или уничтожать какие-либо объекты Python прямо или косвенно.

Это означает, что большинство функций Python C API нельзя использовать, поскольку они могут вызывать новое исключение, возвращать новую ссылку на объект-результат, иметь внутреннюю логику, использующую побочные эффекты. Кроме того, если не указано иное, функции, которые в настоящее время не имеют побочных эффектов, могут начать их иметь в будущих версиях без предупреждения.

Список безопасных функций см. в отдельном разделе ниже.

Примечание

Вызов Py_VISIT() можно пропустить для тех членов, которые заведомо не могут участвовать в циклических ссылках. В примере local_traverse выше также есть член self->key, но он может быть только NULL или строкой Python, и поэтому не может быть частью циклической ссылки.

С другой стороны, даже если вы знаете, что член никогда не может быть частью цикла, в качестве средства отладки вы можете захотеть все равно посетить его, чтобы функция get_referents() модуля gc включала его.

Примечание

Функцию tp_traverse можно вызывать из любого потока.

Деталь реализации CPython: Сборка мусора – это операция «остановки мира»: даже в сборках free threading, когда запускаются обработчики tp_traverse, прикреплено только одно состояние потока attached.

Изменено в версии 3.9: Ожидается, что типы, выделяемые в куче, будут посещать Py_TYPE(self) в tp_traverse. В более ранних версиях Python из-за ошибки 40217 это могло приводить к сбоям в подклассах.

Для упрощения написания обработчиков tp_traverse предоставляется макрос Py_VISIT(). Чтобы использовать этот макрос, реализация tp_traverse должна называть свои аргументы именно visit и arg:

Py_VISIT(o)¶

Если PyObject* o не является NULL, вызвать колбэк visit с аргументами o и arg. Если visit возвращает ненулевое значение, вернуть его.

Это примерно соответствует:

#define Py_VISIT(o)                             \
   if (op) {                                    \
      int visit_result = visit(o, arg);         \
      if (visit_result != 0) {                  \
         return visit_result;                   \
      }                                         \
   }

Управление состоянием сборщика мусора¶Controlling the Garbage Collector State

C-API предоставляет следующие функции для управления запусками сборки мусора.

Py_ssize_t PyGC_Collect(void)¶

Часть Stable ABI.

Выполняет полную сборку мусора, если сборщик мусора включён. (Обратите внимание, что gc.collect() запускает её безусловно.)

Возвращает количество собранных + недостижимых объектов, которые не могут быть собраны. Если сборщик мусора отключён или уже выполняет сборку, немедленно возвращает 0. Ошибки во время сборки мусора передаются в sys.unraisablehook. Эта функция не вызывает исключений.

int PyGC_Enable(void)¶

Часть Stable ABI начиная с версии 3.10.

Включает сборщик мусора: аналогично gc.enable(). Возвращает предыдущее состояние: 0 – отключён, 1 – включён.

Добавлено в версии 3.10.

int PyGC_Disable(void)¶

Часть Stable ABI начиная с версии 3.10.

Отключает сборщик мусора: аналогично gc.disable(). Возвращает предыдущее состояние: 0 – отключён, 1 – включён.

Добавлено в версии 3.10.

int PyGC_IsEnabled(void)¶

Часть Stable ABI начиная с версии 3.10.

Запрашивает состояние сборщика мусора: аналогично gc.isenabled(). Возвращает текущее состояние: 0 – отключён, 1 – включён.

Добавлено в версии 3.10.

Запрос состояния сборщика мусора¶Querying Garbage Collector State

C-API предоставляет следующий интерфейс для запроса информации о сборщике мусора.

void PyUnstable_GC_VisitObjects(gcvisitobjects_t callback, void *arg)¶

Это нестабильное API. Оно может меняться без предупреждения в минорных версиях.

Вызывает переданный колбэк для всех живых объектов, поддерживающих GC. arg передаётся во все вызовы колбэк.

Предупреждение

Если колбэк выделяет или освобождает новые объекты, то не определено, будут ли они посещены.

Во время работы сборка мусора отключена. Явный запуск сборки в колбэке может привести к неопределённому поведению, например, к посещению одних и тех же объектов несколько раз или ни разу.

Добавлено в версии 3.12.

typedef int (*gcvisitobjects_t)(PyObject *object, void *arg)¶

Тип функции-посетителя, передаваемой в PyUnstable_GC_VisitObjects(). Параметр arg – то же самое, что arg, переданный в PyUnstable_GC_VisitObjects. Возвращайте 1 для продолжения итерации, 0 – для остановки. Остальные возвращаемые значения пока зарезервированы, поэтому поведение при возврате чего-либо другого не определено.

Добавлено в версии 3.12.