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

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

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