Подсчёт ссылок

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

Py_ssize_t Py_REFCNT(PyObject *o)

Входит в стабильный ABI начиная с версии 3.14.

Получить счётчик ссылок объекта Python o.

Обратите внимание, что возвращаемое значение может не отражать фактическое количество имеющихся ссылок на объект. Например, некоторые объекты являются бессмертными и имеют очень высокий счётчик ссылок, не отражающий фактическое количество ссылок. Поэтому не полагайтесь на точность возвращаемого значения, за исключением значений 0 и 1.

Для установки счётчика ссылок объекта используйте функцию Py_SET_REFCNT().

Примечание

В сборках Python со свободной обработкой потоков возвращаемого значения 1 недостаточно, чтобы определить, безопасно ли считать, что другие потоки не имеют доступа к o. Вместо этого используйте PyUnstable_Object_IsUniquelyReferenced().

См. также функцию PyUnstable_Object_IsUniqueReferencedTemporary().

Изменено в версии 3.10: Py_REFCNT() преобразована во встроенную статическую функцию.

Изменено в версии 3.11: Тип параметра больше не является const PyObject*.

void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt)

Установить счётчик ссылок объекта o в значение refcnt.

В сборке Python со свободной обработкой потоков, если значение refcnt больше UINT32_MAX, объект становится бессмертным.

Эта функция не действует на бессмертные объекты.

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

Изменено в версии 3.12: Бессмертные объекты не изменяются.

void Py_INCREF(PyObject *o)

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

Эта функция не действует на бессмертные объекты.

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

Закончив работу с объектом, освободите ссылку вызовом Py_DECREF().

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

Не следует рассчитывать, что эта функция каким-либо образом изменит o. Как минимум для некоторых объектов эта функция не действует.

Изменено в версии 3.12: Бессмертные объекты не изменяются.

void Py_XINCREF(PyObject *o)

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

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

PyObject *Py_NewRef(PyObject *o)

Входит в стабильный ABI начиная с версии 3.10.

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

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

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

Например:

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

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

self->attr = Py_NewRef(obj);

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

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

PyObject *Py_XNewRef(PyObject *o)

Входит в стабильный 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() для временной переменной.

Изменено в версии 3.12: Бессмертные объекты не изменяются.

void Py_XDECREF(PyObject *o)

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

void Py_CLEAR(PyObject *o)

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

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

Изменено в версии 3.12: Аргумент макроса теперь вычисляется только один раз. Если аргумент имеет побочные эффекты, они больше не дублируются.

void Py_IncRef(PyObject *o)

Входит в стабильный ABI.

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

void Py_DecRef(PyObject *o)

Входит в стабильный ABI.

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

Py_SETREF(dst, src)

Макрос безопасно освобождает сильную ссылку на объект dst и присваивает dst значение src.

Как и в случае с Py_CLEAR(), «очевидный» код может привести к катастрофическим последствиям:

Py_DECREF(dst);
dst = src;

Безопасный вариант:

Py_SETREF(dst, src);

Сначала dst присваивается значение src, и только после этого освобождается ссылка на старое значение dst. Поэтому код, выполняемый как побочный эффект уничтожения dst, больше не считает, что dst указывает на действительный объект.

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

Изменено в версии 3.12: Аргументы макроса теперь вычисляются только один раз. Если аргумент имеет побочные эффекты, они больше не дублируются.

Py_XSETREF(dst, src)

Вариант макроса Py_SETREF, который использует Py_XDECREF() вместо Py_DECREF().

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

Изменено в версии 3.12: Аргументы макроса теперь вычисляются только один раз. Если аргумент имеет побочные эффекты, они больше не дублируются.