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

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

Py_ssize_t Py_REFCNT(PyObject *o)¶

Часть Stable 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)¶

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

Изменено в версии 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)¶

Часть Stable ABI.

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

void Py_DecRef(PyObject *o)¶

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