`refcounting.md`

176 строк · 14.8 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.16/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*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.14.*1415Возвращает счётчик ссылок объекта Python *o*.1617Обратите внимание, что возвращаемое значение может не отражать реальное количество ссылок на объект. Например, некоторые объекты являются [бессмертными](https://python-all.ru/3.16/glossary.html#term-immortal) и имеют очень высокий счётчик ссылок, который не отражает фактическое количество ссылок. Поэтому не полагайтесь на точность возвращаемого значения, за исключением случаев, когда оно равно 0 или 1.1819Используйте функцию [`Py_SET_REFCNT()`](https://python-all.ru/3.16/c-api/refcounting.html#c.Py_SET_REFCNT) для установки счётчика ссылок объекта.2021> **Примечание**22>23> В [сборках Python со свободной многопоточностью](https://python-all.ru/3.16/glossary.html#term-free-threaded-build) возврата 1 недостаточно, чтобы определить, что *o* безопасно считать недоступным для других потоков. Вместо этого используйте [`PyUnstable_Object_IsUniquelyReferenced()`](https://python-all.ru/3.16/c-api/object.html#c.PyUnstable_Object_IsUniquelyReferenced).24>25> См. также функцию [`PyUnstable_Object_IsUniqueReferencedTemporary()`](https://python-all.ru/3.16/c-api/object.html#c.PyUnstable_Object_IsUniqueReferencedTemporary).2627Изменено в версии 3.10: [`Py_REFCNT()`](https://python-all.ru/3.16/c-api/refcounting.html#c.Py_REFCNT) изменён на встраиваемую статическую функцию.2829Изменено в версии 3.11: Тип параметра больше не const [PyObject](https://python-all.ru/3.16/c-api/structures.html#c.PyObject)\*.3031#### `void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt)`3233Устанавливает счётчик ссылок объекта *o* в значение *refcnt*.3435В [сборке Python со свободной многопоточностью](https://python-all.ru/3.16/using/configure.html#free-threading-build), если *refcnt* больше `UINT32_MAX`, объект становится [бессмертным](https://python-all.ru/3.16/glossary.html#term-immortal).3637Эта функция не влияет на [бессмертные](https://python-all.ru/3.16/glossary.html#term-immortal) объекты.3839Добавлено в версии 3.9.4041Изменено в версии 3.12: Бессмертные объекты не изменяются.4243#### `void Py_INCREF(PyObject *o)`4445Указывает на создание новой [сильной ссылки](https://python-all.ru/3.16/glossary.html#term-strong-reference) на объект *o*, показывая, что он используется и не должен быть уничтожен.4647Эта функция не влияет на [бессмертные](https://python-all.ru/3.16/glossary.html#term-immortal) объекты.4849Эта функция обычно используется для преобразования [заёмной ссылки](https://python-all.ru/3.16/glossary.html#term-borrowed-reference) в [сильную ссылку](https://python-all.ru/3.16/glossary.html#term-strong-reference) на месте. Функцию [`Py_NewRef()`](https://python-all.ru/3.16/c-api/refcounting.html#c.Py_NewRef) можно использовать для создания новой сильной ссылки.5051Когда объект больше не нужен, ссылку освобождают вызовом [`Py_DECREF()`](https://python-all.ru/3.16/c-api/refcounting.html#c.Py_DECREF).5253Объект не должен быть `NULL`; если нет уверенности, что он не `NULL`, используйте [`Py_XINCREF()`](https://python-all.ru/3.16/c-api/refcounting.html#c.Py_XINCREF).5455Не ожидайте, что эта функция как-либо изменит *o*. По крайней мере для [**некоторых объектов**](https://python-all.ru/3.16/c-api/refcounting.html) эта функция не оказывает эффекта.5657Изменено в версии 3.12: Бессмертные объекты не изменяются.5859#### `void Py_XINCREF(PyObject *o)`6061Аналогично [`Py_INCREF()`](https://python-all.ru/3.16/c-api/refcounting.html#c.Py_INCREF), но объект *o* может быть `NULL`, в этом случае функция не действует.6263См. также [`Py_XNewRef()`](https://python-all.ru/3.16/c-api/refcounting.html#c.Py_XNewRef).6465#### `PyObject *Py_NewRef(PyObject *o)`6667*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.10.*6869Создаёт новую [сильную ссылку](https://python-all.ru/3.16/glossary.html#term-strong-reference) на объект: вызывает [`Py_INCREF()`](https://python-all.ru/3.16/c-api/refcounting.html#c.Py_INCREF) для *o* и возвращает объект *o*.7071Когда [сильная ссылка](https://python-all.ru/3.16/glossary.html#term-strong-reference) больше не нужна, для её освобождения следует вызвать [`Py_DECREF()`](https://python-all.ru/3.16/c-api/refcounting.html#c.Py_DECREF).7273Объект *o* не должен быть `NULL`; используйте [`Py_XNewRef()`](https://python-all.ru/3.16/c-api/refcounting.html#c.Py_XNewRef), если *o* может быть `NULL`.7475Например:7677```c78Py_INCREF(obj);79self->attr = obj;80```8182можно записать как:8384```c85self->attr = Py_NewRef(obj);86```8788См. также [`Py_INCREF()`](https://python-all.ru/3.16/c-api/refcounting.html#c.Py_INCREF).8990Добавлено в версии 3.10.9192#### `PyObject *Py_XNewRef(PyObject *o)`9394*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable) начиная с версии 3.10.*9596Аналогично [`Py_NewRef()`](https://python-all.ru/3.16/c-api/refcounting.html#c.Py_NewRef), но объект *o* может быть NULL.9798Если объект *o* равен `NULL`, функция просто возвращает `NULL`.99100Добавлено в версии 3.10.101102#### `void Py_DECREF(PyObject *o)`103104Освобождает [сильную ссылку](https://python-all.ru/3.16/glossary.html#term-strong-reference) на объект *o*, показывая, что ссылка больше не используется.105106Эта функция не влияет на [бессмертные](https://python-all.ru/3.16/glossary.html#term-immortal) объекты.107108Когда последняя [сильная ссылка](https://python-all.ru/3.16/glossary.html#term-strong-reference) освобождена (т.е. счётчик ссылок объекта достигает 0), вызывается функция освобождения типа объекта (которая не должна быть `NULL`).109110Эта функция обычно используется для удаления [сильной ссылки](https://python-all.ru/3.16/glossary.html#term-strong-reference) перед выходом из области видимости.111112Объект не должен быть `NULL`; если нет уверенности, что он не `NULL`, используйте [`Py_XDECREF()`](https://python-all.ru/3.16/c-api/refcounting.html#c.Py_XDECREF).113114Не рассчитывайте, что эта функция действительно изменит *o*. По крайней мере для [**некоторых объектов**](https://python-all.ru/3.16/c-api/refcounting.html) эта функция не имеет эффекта.115116> **Предупреждение**117>118> Функция освобождения может вызвать выполнение произвольного кода Python (например, при освобождении экземпляра класса с методом [`__del__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__del__)). Хотя исключения в таком коде не распространяются, выполняемый код имеет свободный доступ ко всем глобальным переменным Python. Это означает, что любой объект, достижимый из глобальной переменной, должен находиться в согласованном состоянии перед вызовом [`Py_DECREF()`](https://python-all.ru/3.16/c-api/refcounting.html#c.Py_DECREF). Например, код, удаляющий объект из списка, должен скопировать ссылку на удаляемый объект во временную переменную, обновить структуру данных списка, а затем вызвать `Py_DECREF()` для временной переменной.119120Изменено в версии 3.12: Бессмертные объекты не изменяются.121122#### `void Py_XDECREF(PyObject *o)`123124Аналогично [`Py_DECREF()`](https://python-all.ru/3.16/c-api/refcounting.html#c.Py_DECREF), но объект *o* может быть `NULL`, в этом случае функция не имеет эффекта. Предупреждение из `Py_DECREF()` применимо и здесь.125126#### `void Py_CLEAR(PyObject *o)`127128Освобождает [сильную ссылку](https://python-all.ru/3.16/glossary.html#term-strong-reference) на объект *o*. Объект может быть `NULL`, в этом случае макрос не имеет эффекта; в противном случае эффект такой же, как для [`Py_DECREF()`](https://python-all.ru/3.16/c-api/refcounting.html#c.Py_DECREF), за исключением того, что аргумент также устанавливается в `NULL`. Предупреждение для `Py_DECREF()` не применяется к переданному объекту, потому что макрос осторожно использует временную переменную и устанавливает аргумент в `NULL` перед освобождением ссылки.129130Рекомендуется использовать этот макрос всякий раз, когда освобождается ссылка на объект, который может быть обойдён во время сборки мусора.131132Изменено в версии 3.12: Аргумент макроса теперь вычисляется только один раз. Если аргумент имеет побочные эффекты, они больше не дублируются.133134#### `void Py_IncRef(PyObject *o)`135136*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*137138Указывает на получение новой [сильной ссылки](https://python-all.ru/3.16/glossary.html#term-strong-reference) на объект *o*. Функциональная версия [`Py_XINCREF()`](https://python-all.ru/3.16/c-api/refcounting.html#c.Py_XINCREF). Может использоваться для динамического встраивания Python во время выполнения.139140#### `void Py_DecRef(PyObject *o)`141142*Часть [Stable ABI](https://python-all.ru/3.16/c-api/stable.html#stable).*143144Освобождает [сильную ссылку](https://python-all.ru/3.16/glossary.html#term-strong-reference) на объект *o*. Функциональная версия [`Py_XDECREF()`](https://python-all.ru/3.16/c-api/refcounting.html#c.Py_XDECREF). Может использоваться для динамического встраивания Python во время выполнения.145146#### `Py_SETREF(dst, src)`147148Макрос безопасно освобождает [сильную ссылку](https://python-all.ru/3.16/glossary.html#term-strong-reference) на объект *dst* и устанавливает *dst* в *src*.149150Как и в случае [`Py_CLEAR()`](https://python-all.ru/3.16/c-api/refcounting.html#c.Py_CLEAR), «очевидный» код может быть смертельно опасен:151152```c153Py_DECREF(dst);154dst = src;155```156157Безопасный способ:158159```c160Py_SETREF(dst, src);161```162163Это обеспечивает установку *dst* в *src* *до* освобождения ссылки на старое значение *dst*, так что любой код, запущенный как побочный эффект уничтожения *dst*, больше не будет считать, что *dst* указывает на допустимый объект.164165Добавлено в версии 3.6.166167Изменено в версии 3.12: Аргументы макроса теперь вычисляются только один раз. Если аргумент имеет побочные эффекты, они больше не дублируются.168169#### `Py_XSETREF(dst, src)`170171Вариант макроса [`Py_SETREF`](https://python-all.ru/3.16/c-api/refcounting.html#c.Py_SETREF), который использует [`Py_XDECREF()`](https://python-all.ru/3.16/c-api/refcounting.html#c.Py_XDECREF) вместо [`Py_DECREF()`](https://python-all.ru/3.16/c-api/refcounting.html#c.Py_DECREF).172173Добавлено в версии 3.6.174175Изменено в версии 3.12: Аргументы макроса теперь вычисляются только один раз. Если аргумент имеет побочные эффекты, они больше не дублируются.176