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

Поддержка 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)¶

Часть Stable ABI.

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

int PyObject_IS_GC(PyObject *obj)¶

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

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

int PyObject_GC_IsTracked(PyObject *op)¶

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

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

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

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

int PyObject_GC_IsFinalized(PyObject *op)¶

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

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

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

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

void PyObject_GC_Del(void *op)¶

Часть Stable ABI.

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

void PyObject_GC_UnTrack(void *op)¶

Часть Stable ABI.

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

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

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

Часть Stable ABI.

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

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

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

Часть Stable ABI.

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

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

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

Py_VISIT(o)¶

Если объект PyObject* 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)¶

Часть Stable ABI.

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