Подсчёт ссылок¶Reference Counting

Макросы в этом разделе используются для управления счётчиками ссылок на объекты 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)¶

Часть Stable ABI начиная с версии 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)¶

Часть Stable ABI начиная с версии 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)¶

Часть Stable ABI.

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

void Py_DecRef(PyObject *o)¶

Часть Stable ABI.

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

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