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

Поддержка Python обнаружения и сбора мусора, связанного с циклическими ссылками, требует поддержки со стороны объектных типов, которые являются «контейнерами» для других объектов, которые также могут быть контейнерами. Типы, которые не хранят ссылок на другие объекты или хранят только ссылки на атомарные типы (например, числа или строки), не нуждаются в явной поддержке сборки мусора.

Чтобы создать контейнерный тип, поле tp_flags объекта типа должно содержать флаг Py_TPFLAGS_HAVE_GC, а также нужно предоставить реализацию обработчика tp_traverse. Если экземпляры типа изменяемы, необходимо также реализовать tp_clear.

Py_TPFLAGS_HAVE_GC: Объекты с типом, у которого установлен этот флаг, должны соответствовать правилам, описанным здесь. Для удобства такие объекты будут называться контейнерными объектами.

Конструкторы контейнерных типов должны соответствовать двум правилам:

Память для объекта должна выделяться с помощью PyObject_GC_New() или PyObject_GC_NewVar().
Как только все поля, которые могут содержать ссылки на другие контейнеры, будут инициализированы, необходимо вызвать PyObject_GC_Track().

TYPE* PyObject_GC_New(TYPE, PyTypeObject *type)¶: Аналог PyObject_New(), но для контейнерных объектов с установленным флагом Py_TPFLAGS_HAVE_GC.

TYPE* PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)¶: Аналог PyObject_NewVar(), но для контейнерных объектов с установленным флагом Py_TPFLAGS_HAVE_GC.

TYPE* PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize)¶: Изменяет размер объекта, выделенного функцией PyObject_NewVar(). Возвращает объект нового размера или NULL в случае ошибки.

void PyObject_GC_Track(PyObject *op)¶: Добавляет объект op в набор контейнерных объектов, отслеживаемых сборщиком. Сборщик может запускаться в неожиданные моменты, поэтому отслеживаемые объекты должны быть корректными. Этот вызов следует делать после того, как все поля, обрабатываемые обработчиком tp_traverse, станут корректными, обычно ближе к концу конструктора.

void _PyObject_GC_TRACK(PyObject *op)¶: Макроверсия PyObject_GC_Track(). Не предназначена для использования в модулях расширения.

Аналогично, деаллокатор объекта должен соответствовать такой же паре правил:

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

void PyObject_GC_Del(void *op)¶: Освобождает память, выделенную для объекта с помощью PyObject_GC_New() или PyObject_GC_NewVar().

void PyObject_GC_UnTrack(void *op)¶: Удаляет объект op из набора контейнерных объектов, отслеживаемых сборщиком. Обратите внимание, что PyObject_GC_Track() может быть вызвана снова для этого объекта, чтобы вернуть его в набор отслеживаемых. Деаллокатор (обработчик tp_dealloc) должен вызывать эту функцию для объекта до того, как какие-либо поля, используемые обработчиком tp_traverse, станут недействительными.

void _PyObject_GC_UNTRACK(PyObject *op)¶: Макроверсия PyObject_GC_UnTrack(). Не предназначена для использования в модулях расширения.

Обработчик tp_traverse принимает параметр-функцию следующего типа:

int (*visitproc)(PyObject *object, void *arg)¶: Тип функции посещения, передаваемой обработчику tp_traverse. Функцию следует вызывать с объектом для обхода в качестве object и третьим параметром обработчика tp_traverse в качестве arg. Ядро Python использует несколько функций посещения для обнаружения циклического мусора; не предполагается, что пользователям понадобится писать собственные функции посещения.

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

int (*traverseproc)(PyObject *self, visitproc visit, void *arg)¶: Функция обхода для контейнерного объекта. Реализации должны вызывать функцию visit для каждого объекта, непосредственно содержащегося в self, с параметрами visit: содержащийся объект и значение arg, переданное обработчику. Функция visit не должна вызываться с аргументом-объектом NULL. Если visit возвращает ненулевое значение, его следует немедленно вернуть.

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

void Py_VISIT(PyObject *o)¶

Вызывает колбэк visit с аргументами o и arg. Если visit возвращает ненулевое значение, возвращает его. С использованием этого макроса обработчики tp_traverse выглядят так:

static int
my_traverse(Noddy *self, visitproc visit, void *arg)
{
    Py_VISIT(self->foo);
    Py_VISIT(self->bar);
    return 0;
}

Обработчик tp_clear должен иметь тип inquiry или NULL, если объект неизменяем.

int (*inquiry)(PyObject *self)¶: Удаляет ссылки, которые могли создать циклические ссылки. Неизменяемые объекты могут не определять этот метод, так как они никогда не могут напрямую создавать циклические ссылки. Обратите внимание, что объект после вызова этого метода всё ещё должен быть корректным (нельзя просто вызвать Py_DECREF() на ссылку). Сборщик вызовет этот метод, если обнаружит, что этот объект вовлечён в циклическую ссылку.