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

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

Py_ssize_t Py_REFCNT(PyObject *o)

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

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

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

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

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

void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt)

Задать счётчику ссылок объекта o значение refcnt.

Обратите внимание, что эта функция не влияет на бессмертные объекты.

Добавлено в версии 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: Аргументы макроса теперь вычисляются только один раз. Если аргумент имеет побочные эффекты, они больше не дублируются.