> **Источник:** https://python-all.ru/3/c-api/refcounting.html > > «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor. --- # Подсчёт ссылок Функции и макросы в этом разделе предназначены для управления счётчиками ссылок объектов Python. #### `Py_ssize_t Py_REFCNT(PyObject *o)` *Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable) начиная с версии 3.14.* Возвращает счётчик ссылок объекта Python *o*. Обратите внимание, что возвращаемое значение может не отражать реальное количество ссылок на объект. Например, некоторые объекты являются [бессмертными](https://python-all.ru/3/glossary.html#term-immortal) и имеют очень высокий счётчик ссылок, который не отражает фактическое количество ссылок. Поэтому не полагайтесь на точность возвращаемого значения, за исключением случаев, когда оно равно 0 или 1. Используйте функцию [`Py_SET_REFCNT()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_SET_REFCNT) для установки счётчика ссылок объекта. > **Примечание** > > В [сборках Python со свободной многопоточностью](https://python-all.ru/3/glossary.html#term-free-threaded-build) возврата 1 недостаточно, чтобы определить, что *o* безопасно считать недоступным для других потоков. Вместо этого используйте [`PyUnstable_Object_IsUniquelyReferenced()`](https://python-all.ru/3/c-api/object.html#c.PyUnstable_Object_IsUniquelyReferenced). > > См. также функцию [`PyUnstable_Object_IsUniqueReferencedTemporary()`](https://python-all.ru/3/c-api/object.html#c.PyUnstable_Object_IsUniqueReferencedTemporary). Изменено в версии 3.10: [`Py_REFCNT()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_REFCNT) изменён на встраиваемую статическую функцию. Изменено в версии 3.11: Тип параметра больше не const [PyObject](https://python-all.ru/3/c-api/structures.html#c.PyObject)\*. #### `void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt)` Устанавливает счётчик ссылок объекта *o* в значение *refcnt*. В [сборке Python со свободной многопоточностью](https://python-all.ru/3/using/configure.html#free-threading-build), если *refcnt* больше `UINT32_MAX`, объект становится [бессмертным](https://python-all.ru/3/glossary.html#term-immortal). Эта функция не влияет на [бессмертные](https://python-all.ru/3/glossary.html#term-immortal) объекты. Добавлено в версии 3.9. Изменено в версии 3.12: Бессмертные объекты не изменяются. #### `void Py_INCREF(PyObject *o)` Указывает на создание новой [сильной ссылки](https://python-all.ru/3/glossary.html#term-strong-reference) на объект *o*, показывая, что он используется и не должен быть уничтожен. Эта функция не влияет на [бессмертные](https://python-all.ru/3/glossary.html#term-immortal) объекты. Эта функция обычно используется для преобразования [заёмной ссылки](https://python-all.ru/3/glossary.html#term-borrowed-reference) в [сильную ссылку](https://python-all.ru/3/glossary.html#term-strong-reference) на месте. Функцию [`Py_NewRef()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_NewRef) можно использовать для создания новой сильной ссылки. Когда объект больше не нужен, ссылку освобождают вызовом [`Py_DECREF()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_DECREF). Объект не должен быть `NULL`; если нет уверенности, что он не `NULL`, используйте [`Py_XINCREF()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_XINCREF). Не рассчитывайте, что эта функция действительно изменит *o*. По крайней мере для [**некоторых объектов**](https://python-all.ru/3/c-api/refcounting.html) эта функция не имеет эффекта. Изменено в версии 3.12: Бессмертные объекты не изменяются. #### `void Py_XINCREF(PyObject *o)` Аналогично [`Py_INCREF()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_INCREF), но объект *o* может быть `NULL`, в этом случае функция не действует. См. также [`Py_XNewRef()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_XNewRef). #### `PyObject *Py_NewRef(PyObject *o)` *Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable) начиная с версии 3.10.* Создаёт новую [сильную ссылку](https://python-all.ru/3/glossary.html#term-strong-reference) на объект: вызывает [`Py_INCREF()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_INCREF) для *o* и возвращает объект *o*. Когда [сильная ссылка](https://python-all.ru/3/glossary.html#term-strong-reference) больше не нужна, для её освобождения следует вызвать [`Py_DECREF()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_DECREF). Объект *o* не должен быть `NULL`; используйте [`Py_XNewRef()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_XNewRef), если *o* может быть `NULL`. Например: ```c Py_INCREF(obj); self->attr = obj; ``` можно записать как: ```c self->attr = Py_NewRef(obj); ``` См. также [`Py_INCREF()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_INCREF). Добавлено в версии 3.10. #### `PyObject *Py_XNewRef(PyObject *o)` *Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable) начиная с версии 3.10.* Аналогично [`Py_NewRef()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_NewRef), но объект *o* может быть NULL. Если объект *o* равен `NULL`, функция просто возвращает `NULL`. Добавлено в версии 3.10. #### `void Py_DECREF(PyObject *o)` Освобождает [сильную ссылку](https://python-all.ru/3/glossary.html#term-strong-reference) на объект *o*, показывая, что ссылка больше не используется. Эта функция не влияет на [бессмертные](https://python-all.ru/3/glossary.html#term-immortal) объекты. Когда последняя [сильная ссылка](https://python-all.ru/3/glossary.html#term-strong-reference) освобождена (т.е. счётчик ссылок объекта достигает 0), вызывается функция освобождения типа объекта (которая не должна быть `NULL`). Эта функция обычно используется для удаления [сильной ссылки](https://python-all.ru/3/glossary.html#term-strong-reference) перед выходом из области видимости. Объект не должен быть `NULL`; если нет уверенности, что он не `NULL`, используйте [`Py_XDECREF()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_XDECREF). Не рассчитывайте, что эта функция действительно изменит *o*. По крайней мере для [**некоторых объектов**](https://python-all.ru/3/c-api/refcounting.html) эта функция не имеет эффекта. > **Предупреждение** > > Функция освобождения может вызвать выполнение произвольного кода Python (например, при освобождении экземпляра класса с методом [`__del__()`](https://python-all.ru/3/reference/datamodel.html#object.__del__)). Хотя исключения в таком коде не распространяются, выполняемый код имеет свободный доступ ко всем глобальным переменным Python. Это означает, что любой объект, достижимый из глобальной переменной, должен находиться в согласованном состоянии перед вызовом [`Py_DECREF()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_DECREF). Например, код, удаляющий объект из списка, должен скопировать ссылку на удаляемый объект во временную переменную, обновить структуру данных списка, а затем вызвать `Py_DECREF()` для временной переменной. Изменено в версии 3.12: Бессмертные объекты не изменяются. #### `void Py_XDECREF(PyObject *o)` Аналогично [`Py_DECREF()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_DECREF), но объект *o* может быть `NULL`, в этом случае функция не имеет эффекта. Предупреждение из `Py_DECREF()` применимо и здесь. #### `void Py_CLEAR(PyObject *o)` Освобождает [сильную ссылку](https://python-all.ru/3/glossary.html#term-strong-reference) на объект *o*. Объект может быть `NULL`, в этом случае макрос не имеет эффекта; в противном случае эффект такой же, как для [`Py_DECREF()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_DECREF), за исключением того, что аргумент также устанавливается в `NULL`. Предупреждение для `Py_DECREF()` не применяется к переданному объекту, потому что макрос осторожно использует временную переменную и устанавливает аргумент в `NULL` перед освобождением ссылки. Рекомендуется использовать этот макрос всякий раз, когда освобождается ссылка на объект, который может быть обойдён во время сборки мусора. Изменено в версии 3.12: Аргумент макроса теперь вычисляется только один раз. Если аргумент имеет побочные эффекты, они больше не дублируются. #### `void Py_IncRef(PyObject *o)` *Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable).* Указывает на получение новой [сильной ссылки](https://python-all.ru/3/glossary.html#term-strong-reference) на объект *o*. Функциональная версия [`Py_XINCREF()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_XINCREF). Может использоваться для динамического встраивания Python во время выполнения. #### `void Py_DecRef(PyObject *o)` *Часть [Stable ABI](https://python-all.ru/3/c-api/stable.html#stable).* Освобождает [сильную ссылку](https://python-all.ru/3/glossary.html#term-strong-reference) на объект *o*. Функциональная версия [`Py_XDECREF()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_XDECREF). Может использоваться для динамического встраивания Python во время выполнения. #### `Py_SETREF(dst, src)` Макрос безопасно освобождает [сильную ссылку](https://python-all.ru/3/glossary.html#term-strong-reference) на объект *dst* и устанавливает *dst* в *src*. Как и в случае [`Py_CLEAR()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_CLEAR), «очевидный» код может быть смертельно опасен: ```c Py_DECREF(dst); dst = src; ``` Безопасный способ: ```c Py_SETREF(dst, src); ``` Это обеспечивает установку *dst* в *src* *до* освобождения ссылки на старое значение *dst*, так что любой код, запущенный как побочный эффект уничтожения *dst*, больше не будет считать, что *dst* указывает на допустимый объект. Добавлено в версии 3.6. Изменено в версии 3.12: Аргументы макроса теперь вычисляются только один раз. Если аргумент имеет побочные эффекты, они больше не дублируются. #### `Py_XSETREF(dst, src)` Вариант макроса [`Py_SETREF`](https://python-all.ru/3/c-api/refcounting.html#c.Py_SETREF), который использует [`Py_XDECREF()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_XDECREF) вместо [`Py_DECREF()`](https://python-all.ru/3/c-api/refcounting.html#c.Py_DECREF). Добавлено в версии 3.6. Изменено в версии 3.12: Аргументы макроса теперь вычисляются только один раз. Если аргумент имеет побочные эффекты, они больше не дублируются.