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

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

Py_ssize_t Py_REFCNT(PyObject *o)

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

Обратите внимание, что возвращаемое значение может не отражать реальное количество ссылок на объект. Например, некоторые объекты имеют значение immortal и очень высокое значение refcount, которое не отражает фактического количества ссылок. Следовательно, не стоит полагаться на точное возвращаемое значение, кроме значения 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 build with Free Threading, если refcnt больше UINT32_MAX, объект делается immortal.

Эта функция не влияет на объекты immortal.

Added in version 3.9.

Изменено в версии 3.12: Бессмертные предметы не подвергаются изменениям.

void Py_INCREF(PyObject *o)

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

Эта функция не влияет на объекты immortal.

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

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

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

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

Изменено в версии 3.12: Бессмертные предметы не подвергаются изменениям.

void Py_XINCREF(PyObject *o)

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

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

PyObject *Py_NewRef(PyObject *o)
Часть Стабильный ABI с версии 3.10.

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

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

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

Например:

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

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

self->attr = Py_NewRef(obj);

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

Added in version 3.10.

PyObject *Py_XNewRef(PyObject *o)
Часть Стабильный ABI с версии 3.10.

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

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

Added in version 3.10.

void Py_DECREF(PyObject *o)

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

Эта функция не влияет на объекты immortal.

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

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

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

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

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

Функция deallocation может вызвать произвольный код 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)

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

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

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

void Py_IncRef(PyObject *o)
Часть Стабильный ABI.

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

void Py_DecRef(PyObject *o)
Часть Стабильный ABI.

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

Py_SETREF(dst, src)

Макрос безопасно освобождает strong reference для объекта dst и устанавливает dst в src.

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

Py_DECREF(dst);
dst = src;

Безопасный способ:

Py_SETREF(dst, src);

Это позволяет установить dst в src _до_ освобождения ссылки на старое значение dst, так что любой код, срабатывающий как побочный эффект уничтожения dst, больше не считает, что dst указывает на действительный объект.

Added in version 3.6.

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

Py_XSETREF(dst, src)

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

Added in version 3.6.

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