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

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

При сборке 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; используйте Py_XNewRef(), если o может быть NULL.

Например:

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