Счётчик ссылок

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