refcounting.md

1> **Источник:** https://python-all.ru/3.12/c-api/refcounting.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Подсчёт ссылок89Функции и макросы в этом разделе предназначены для управления счётчиками ссылок объектов Python.1011#### `Py_ssize_t Py_REFCNT(PyObject *o)`1213Возвращает счётчик ссылок объекта Python *o*.1415Обратите внимание, что возвращаемое значение может не отражать реальное количество ссылок на объект. Например, некоторые объекты являются «бессмертными» и имеют очень высокий счётчик ссылок, который не соответствует действительному числу ссылок. Поэтому не стоит полагаться на точность этого значения, за исключением случаев, когда оно равно 0 или 1.1617Используйте функцию [`Py_SET_REFCNT()`](https://python-all.ru/3.12/c-api/refcounting.html#c.Py_SET_REFCNT) для установки счётчика ссылок объекта.1819Изменено в версии 3.10: [`Py_REFCNT()`](https://python-all.ru/3.12/c-api/refcounting.html#c.Py_REFCNT) изменён на встраиваемую статическую функцию.2021Изменено в версии 3.11: Тип параметра больше не const [PyObject](https://python-all.ru/3.12/c-api/structures.html#c.PyObject)\*.2223#### `void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt)`2425Устанавливает счётчик ссылок объекта *o* в значение *refcnt*.2627Обратите внимание, что эта функция не влияет на [бессмертные](https://python-all.ru/3.12/c-api/refcounting.html) объекты.2829Добавлено в версии 3.9.3031Изменено в версии 3.12: Бессмертные объекты не изменяются.3233#### `void Py_INCREF(PyObject *o)`3435Указывает на создание новой [сильной ссылки](https://python-all.ru/3.12/glossary.html#term-strong-reference) на объект *o*, показывая, что он используется и не должен быть уничтожен.3637Эта функция обычно используется для преобразования [заимствованной ссылки](https://python-all.ru/3.12/glossary.html#term-borrowed-reference) в [сильную ссылку](https://python-all.ru/3.12/glossary.html#term-strong-reference) на месте. Функция [`Py_NewRef()`](https://python-all.ru/3.12/c-api/refcounting.html#c.Py_NewRef) может использоваться для создания новой [сильной ссылки](https://python-all.ru/3.12/glossary.html#term-strong-reference).3839Когда объект больше не нужен, освободите его, вызвав [`Py_DECREF()`](https://python-all.ru/3.12/c-api/refcounting.html#c.Py_DECREF).4041Объект не должен быть `NULL`; если нет уверенности, что он не `NULL`, используйте [`Py_XINCREF()`](https://python-all.ru/3.12/c-api/refcounting.html#c.Py_XINCREF).4243Не рассчитывайте, что эта функция действительно изменит *o*. По крайней мере для [**некоторых объектов**](https://python-all.ru/3.12/c-api/refcounting.html) эта функция не имеет эффекта.4445Изменено в версии 3.12: Бессмертные объекты не изменяются.4647#### `void Py_XINCREF(PyObject *o)`4849Аналогично [`Py_INCREF()`](https://python-all.ru/3.12/c-api/refcounting.html#c.Py_INCREF), но объект *o* может быть `NULL`, в этом случае функция не действует.5051См. также [`Py_XNewRef()`](https://python-all.ru/3.12/c-api/refcounting.html#c.Py_XNewRef).5253#### `PyObject *Py_NewRef(PyObject *o)`5455*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.10.*5657Создаёт новую [сильную ссылку](https://python-all.ru/3.12/glossary.html#term-strong-reference) на объект: вызывает [`Py_INCREF()`](https://python-all.ru/3.12/c-api/refcounting.html#c.Py_INCREF) для *o* и возвращает объект *o*.5859Когда [сильная ссылка](https://python-all.ru/3.12/glossary.html#term-strong-reference) больше не нужна, для её освобождения следует вызвать [`Py_DECREF()`](https://python-all.ru/3.12/c-api/refcounting.html#c.Py_DECREF).6061Объект *o* не должен быть `NULL`; используйте [`Py_XNewRef()`](https://python-all.ru/3.12/c-api/refcounting.html#c.Py_XNewRef), если *o* может быть `NULL`.6263Например:6465```c66Py_INCREF(obj);67self->attr = obj;68```6970можно записать как:7172```c73self->attr = Py_NewRef(obj);74```7576См. также [`Py_INCREF()`](https://python-all.ru/3.12/c-api/refcounting.html#c.Py_INCREF).7778Добавлено в версии 3.10.7980#### `PyObject *Py_XNewRef(PyObject *o)`8182*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable) начиная с версии 3.10.*8384Аналогично [`Py_NewRef()`](https://python-all.ru/3.12/c-api/refcounting.html#c.Py_NewRef), но объект *o* может быть NULL.8586Если объект *o* равен `NULL`, функция просто возвращает `NULL`.8788Добавлено в версии 3.10.8990#### `void Py_DECREF(PyObject *o)`9192Освобождает [сильную ссылку](https://python-all.ru/3.12/glossary.html#term-strong-reference) на объект *o*, показывая, что ссылка больше не используется.9394Когда последняя [сильная ссылка](https://python-all.ru/3.12/glossary.html#term-strong-reference) освобождена (т.е. счётчик ссылок объекта достигает 0), вызывается функция освобождения типа объекта (которая не должна быть `NULL`).9596Эта функция обычно используется для удаления [сильной ссылки](https://python-all.ru/3.12/glossary.html#term-strong-reference) перед выходом из области видимости.9798Объект не должен быть `NULL`; если нет уверенности, что он не `NULL`, используйте [`Py_XDECREF()`](https://python-all.ru/3.12/c-api/refcounting.html#c.Py_XDECREF).99100Не рассчитывайте, что эта функция действительно изменит *o*. По крайней мере для [**некоторых объектов**](https://python-all.ru/3.12/c-api/refcounting.html) эта функция не имеет эффекта.101102> **Предупреждение**103>104> Функция освобождения может вызвать выполнение произвольного кода Python (например, при освобождении экземпляра класса с методом [`__del__()`](https://python-all.ru/3.12/reference/datamodel.html#object.__del__)). Хотя исключения в таком коде не распространяются, выполняемый код имеет свободный доступ ко всем глобальным переменным Python. Это означает, что любой объект, достижимый из глобальной переменной, должен находиться в согласованном состоянии перед вызовом [`Py_DECREF()`](https://python-all.ru/3.12/c-api/refcounting.html#c.Py_DECREF). Например, код, удаляющий объект из списка, должен скопировать ссылку на удаляемый объект во временную переменную, обновить структуру данных списка, а затем вызвать [`Py_DECREF()`](https://python-all.ru/3.12/c-api/refcounting.html#c.Py_DECREF) для временной переменной.105106Изменено в версии 3.12: Бессмертные объекты не изменяются.107108#### `void Py_XDECREF(PyObject *o)`109110Аналогично [`Py_DECREF()`](https://python-all.ru/3.12/c-api/refcounting.html#c.Py_DECREF), но объект *o* может быть `NULL`, в этом случае функция не имеет эффекта. Предупреждение из [`Py_DECREF()`](https://python-all.ru/3.12/c-api/refcounting.html#c.Py_DECREF) применимо и здесь.111112#### `void Py_CLEAR(PyObject *o)`113114Освобождает [сильную ссылку](https://python-all.ru/3.12/glossary.html#term-strong-reference) на объект *o*. Объект может быть `NULL`, в этом случае макрос не имеет эффекта; в противном случае эффект такой же, как для [`Py_DECREF()`](https://python-all.ru/3.12/c-api/refcounting.html#c.Py_DECREF), за исключением того, что аргумент также устанавливается в `NULL`. Предупреждение для [`Py_DECREF()`](https://python-all.ru/3.12/c-api/refcounting.html#c.Py_DECREF) не применяется к переданному объекту, потому что макрос осторожно использует временную переменную и устанавливает аргумент в `NULL` перед освобождением ссылки.115116Рекомендуется использовать этот макрос всякий раз, когда освобождается ссылка на объект, который может быть обойдён во время сборки мусора.117118Изменено в версии 3.12: Аргумент макроса теперь вычисляется только один раз. Если аргумент имеет побочные эффекты, они больше не дублируются.119120#### `void Py_IncRef(PyObject *o)`121122*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*123124Указывает на получение новой [сильной ссылки](https://python-all.ru/3.12/glossary.html#term-strong-reference) на объект *o*. Функциональная версия [`Py_XINCREF()`](https://python-all.ru/3.12/c-api/refcounting.html#c.Py_XINCREF). Может использоваться для динамического встраивания Python во время выполнения.125126#### `void Py_DecRef(PyObject *o)`127128*Часть [Stable ABI](https://python-all.ru/3.12/c-api/stable.html#stable).*129130Освобождает [сильную ссылку](https://python-all.ru/3.12/glossary.html#term-strong-reference) на объект *o*. Функциональная версия [`Py_XDECREF()`](https://python-all.ru/3.12/c-api/refcounting.html#c.Py_XDECREF). Может использоваться для динамического встраивания Python во время выполнения.131132#### `Py_SETREF(dst, src)`133134Макрос безопасно освобождает [сильную ссылку](https://python-all.ru/3.12/glossary.html#term-strong-reference) на объект *dst* и устанавливает *dst* в *src*.135136Как и в случае [`Py_CLEAR()`](https://python-all.ru/3.12/c-api/refcounting.html#c.Py_CLEAR), «очевидный» код может быть смертельно опасен:137138```c139Py_DECREF(dst);140dst = src;141```142143Безопасный способ:144145```c146Py_SETREF(dst, src);147```148149Это гарантирует, что *dst* будет установлен в *src* \_до\_ освобождения ссылки на старое значение *dst*, чтобы любой код, срабатывающий как побочный эффект при уничтожении *dst*, больше не считал, что *dst* указывает на допустимый объект.150151Добавлено в версии 3.6.152153Изменено в версии 3.12: Аргументы макроса теперь вычисляются только один раз. Если аргумент имеет побочные эффекты, они больше не дублируются.154155#### `Py_XSETREF(dst, src)`156157Вариант макроса [`Py_SETREF`](https://python-all.ru/3.12/c-api/refcounting.html#c.Py_SETREF), который использует [`Py_XDECREF()`](https://python-all.ru/3.12/c-api/refcounting.html#c.Py_XDECREF) вместо [`Py_DECREF()`](https://python-all.ru/3.12/c-api/refcounting.html#c.Py_DECREF).158159Добавлено в версии 3.6.160161Изменено в версии 3.12: Аргументы макроса теперь вычисляются только один раз. Если аргумент имеет побочные эффекты, они больше не дублируются.162