Обращение к счетчику ссылок

Макросы в этом разделе используются для управления счетчиками ссылок объектов Python.

void Py_INCREF(PyObject *o)

Указывает на получение новой сильной ссылки на объект o, указывая, что он используется и не должен быть уничтожен.

Эта функция обычно используется для преобразования заимствованной ссылки в сильную ссылку на месте. Функция Py_NewRef() может использоваться для создания новой сильной ссылки.

После использования объекта освободите его, вызвав Py_DECREF().

Объект не должен быть NULL; если вы не уверены, что он не NULL, используйте Py_XINCREF().

Не ожидайте, что эта функция будет каким-либо образом изменять o.

void Py_XINCREF(PyObject *o)

Аналогично Py_INCREF(), но объект o может быть NULL, в этом случае функция не оказывает никакого влияния.

См. также Py_XNewRef().

PyObject *Py_NewRef(PyObject *o)

Часть Стабильной АБИ с версии 3.10.

Создайте новую сильную ссылку на объект: вызовите Py_INCREF() для o и верните объект o.

Когда сильная ссылка больше не нужна, вызов Py_DECREF() должен быть выполнен для освобождения ссылки.

Объект o не должен быть NULL; используйте Py_XNewRef(), если o может быть NULL.

Например:

Py_INCREF(obj);
self->attr = obj;

можно записать как:

self->attr = Py_NewRef(obj);

См. также Py_INCREF().

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

PyObject *Py_XNewRef(PyObject *o)

Часть Стабильной АБИ с версии 3.10.

Аналогично Py_NewRef(), но объект o может быть NULL.

Если объект o равен NULL, функция просто возвращает NULL.

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

void Py_DECREF(PyObject *o)

Освободите сильную ссылку на объект o, указав, что ссылка больше не используется.

Как только последняя сильная ссылка будет освобождена (т.е. счетчик ссылок объекта достигнет 0), вызывается функция освобождения типа объекта (которая не должна быть NULL).

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

Объект не должен быть NULL; если вы не уверены, что он не NULL, используйте Py_XDECREF().

Не ожидайте, что эта функция будет каким-либо образом изменять o.

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

Функция освобождения может вызвать произвольный код Python (например, при освобождении экземпляра класса с методом __del__()). Хотя исключения в таком коде не распространяются, исполняемый код имеет свободный доступ ко всем глобальным переменным Python. Это означает, что любой объект, доступный из глобальной переменной, должен быть в согласованном состоянии перед вызовом Py_DECREF(). Например, код для удаления объекта из списка должен скопировать ссылку на удаляемый объект во временную переменную, обновить структуру данных списка, а затем вызвать Py_DECREF() для временной переменной.

void Py_XDECREF(PyObject *o)

Аналогично Py_DECREF(), но объект o может быть NULL, в этом случае функция не оказывает никакого влияния. То же предупреждение из Py_DECREF() относится и здесь.

void Py_CLEAR(PyObject *o)

Освобождает сильную ссылку для объекта o. Объект может быть NULL, в этом случае макрос не оказывает никакого влияния; в противном случае эффект такой же, как и для Py_DECREF(), за исключением того, что аргумент также устанавливается в NULL. Предупреждение для Py_DECREF() не относится к переданному объекту, потому что макрос тщательно использует временную переменную и устанавливает аргумент в NULL перед освобождением ссылки.

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

void Py_IncRef(PyObject *o)

Часть Стабильной АБИ.

Указывает на получение новой сильной ссылки на объект o. Функциональная версия Py_XINCREF(). Может использоваться для динамической встраивания Python во время выполнения.

void Py_DecRef(PyObject *o)

Часть Стабильной АБИ.

Освобождает сильную ссылку на объект o. Функциональная версия Py_XDECREF(). Может использоваться для динамической встраивания Python во время выполнения.

Следующие функции или макросы предназначены только для использования в ядре интерпретатора: _Py_Dealloc(), _Py_ForgetReference(), _Py_NewReference(), а также глобальная переменная _Py_RefTotal.