Поддержка циклического сбора мусора

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

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

Py_TPFLAGS_HAVE_GC

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

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

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

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

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

2. Память объекта должна быть освобождена с использованием PyObject_GC_Del().

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

   Если тип добавляет Py_TPFLAGS_HAVE_GC, то он обязан реализовать по крайней мере обработчик tp_traverse или явно использовать обработчик из своего подкласса или подклассов.

   При вызове PyType_Ready() или некоторых API, которые косвенно вызывают его, таких как PyType_FromSpecWithBases() или PyType_FromSpec(), интерпретатор автоматически заполнит поля tp_flags, tp_traverse и tp_clear, если тип наследуется от класса, реализующего протокол сбора мусора, и дочерний класс не включает флаг Py_TPFLAGS_HAVE_GC.

PyObject_GC_New(TYPE, typeobj)

Аналогично PyObject_New, но для объектов-контейнеров с установленным флагом Py_TPFLAGS_HAVE_GC.

PyObject_GC_NewVar(TYPE, typeobj, size)

Аналогично PyObject_NewVar, но для объектов-контейнеров с установленным флагом Py_TPFLAGS_HAVE_GC.

PyObject *PyUnstable_Object_GC_NewWithExtraData(PyTypeObject *type, size_t extra_size)

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

Аналогично PyObject_GC_New, но выделяет extra_size байтов в конце объекта (по смещению tp_basicsize). Выделенная память инициализируется нулями, за исключением Python object header.

Дополнительные данные будут освобождены вместе с объектом, но в остальном они не управляются Python.

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

Функция помечена как нестабильная, потому что окончательный механизм резервирования дополнительных данных после создания экземпляра еще не определен. Для выделения переменного количества полей предпочтительнее использовать PyVarObject и tp_itemsize.

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

PyObject_GC_Resize(TYPE, op, newsize)

Изменение размера объекта, выделенного с помощью PyObject_NewVar. Возвращает измененный объект типа TYPE* (ссылается на любой тип C) или NULL при ошибке.

op должен быть типа PyVarObject* и пока не должен отслеживаться коллектором. newsize должен быть типа Py_ssize_t.

void PyObject_GC_Track(PyObject *op)

Часть Стабильной ABI.

Добавляет объект op в множество отслеживаемых объектами-контейнерами коллектором. Коллектор может выполняться в неожиданные моменты, поэтому объекты должны быть валидными во время отслеживания. Это должно быть вызвано после того, как все поля, за которыми следует обработчик tp_traverse, станут валидными, обычно в конце конструктора.

int PyObject_IS_GC(PyObject *obj)

Возвращает ненулевое значение, если объект реализует протокол сбора мусора, в противном случае возвращает 0.

Объект не может быть отслеживаем коллектором мусора, если эта функция возвращает 0.

int PyObject_GC_IsTracked(PyObject *op)

Часть Стабильной ABI с версии 3.9.

Возвращает 1, если тип объекта op реализует протокол GC и op в настоящее время отслеживается сборщиком мусора, и 0 в противном случае.

Это аналогично функции Python gc.is_tracked().

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

int PyObject_GC_IsFinalized(PyObject *op)

Часть Стабильной ABI с версии 3.9.

Возвращает 1, если тип объекта op реализует протокол GC и op уже был завершен сборщиком мусора, и 0 в противном случае.

Это аналогично функции Python gc.is_finalized().

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

void PyObject_GC_Del(void *op)

Часть Стабильной ABI.

Освобождает память, выделенную для объекта с помощью PyObject_GC_New или PyObject_GC_NewVar.

void PyObject_GC_UnTrack(void *op)

Часть Стабильной ABI.

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

Обработчик tp_traverse принимает параметр функции этого типа:

typedef int (*visitproc)(PyObject *object, void *arg)

Часть Стабильного API.

Тип функции-визитора, передаваемой обработчику tp_traverse. Функция должна вызываться с объектом для обхода в качестве параметра object и третьим параметром обработчика tp_traverse в качестве параметра arg. Ядро Python использует несколько функций-визиторов для реализации обнаружения циклических ссылок; не ожидается, что пользователям потребуется писать свои собственные функции-визиторы.

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

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

Часть Стабильного API.

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

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

void Py_VISIT(PyObject *o)

Если o не NULL, вызовите обратный вызов 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, если объект неизменяемый.

typedef int (*inquiry)(PyObject *self)

Часть Стабильного API.

Освободить ссылки, которые могут создать циклические ссылки. Неизменяемые объекты не должны определять этот метод, так как они никогда не могут непосредственно создавать циклические ссылки. Обратите внимание, что объект должен оставаться действительным после вызова этого метода (не просто вызывайте Py_DECREF() на ссылке). Коллектор вызовет этот метод, если обнаружит, что этот объект участвует в циклической ссылке.