Обработка ссылок

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

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