`refcounting.md`

168 строк · 14.0 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.13/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Обратите внимание, что возвращаемое значение может не отражать реальное количество ссылок на объект. Например, некоторые объекты являются [бессмертными](https://python-all.ru/3.13/glossary.html#term-immortal) и имеют очень высокий счётчик ссылок, который не отражает фактическое количество ссылок. Поэтому не полагайтесь на точность возвращаемого значения, за исключением случаев, когда оно равно 0 или 1.1617Используйте функцию [`Py_SET_REFCNT()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_SET_REFCNT) для установки счётчика ссылок объекта.1819Изменено в версии 3.10: [`Py_REFCNT()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_REFCNT) изменён на встраиваемую статическую функцию.2021Изменено в версии 3.11: Тип параметра больше не const [PyObject](https://python-all.ru/3.13/c-api/structures.html#c.PyObject)\*.2223#### `void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt)`2425Устанавливает счётчик ссылок объекта *o* в значение *refcnt*.2627В [сборке Python со свободной многопоточностью](https://python-all.ru/3.13/using/configure.html#free-threading-build), если *refcnt* больше `UINT32_MAX`, объект становится [бессмертным](https://python-all.ru/3.13/glossary.html#term-immortal).2829Эта функция не влияет на [бессмертные](https://python-all.ru/3.13/glossary.html#term-immortal) объекты.3031Добавлено в версии 3.9.3233Изменено в версии 3.12: Бессмертные объекты не изменяются.3435#### `void Py_INCREF(PyObject *o)`3637Указывает на создание новой [сильной ссылки](https://python-all.ru/3.13/glossary.html#term-strong-reference) на объект *o*, показывая, что он используется и не должен быть уничтожен.3839Эта функция не влияет на [бессмертные](https://python-all.ru/3.13/glossary.html#term-immortal) объекты.4041Эта функция обычно используется для преобразования [заёмной ссылки](https://python-all.ru/3.13/glossary.html#term-borrowed-reference) в [сильную ссылку](https://python-all.ru/3.13/glossary.html#term-strong-reference) на месте. Функцию [`Py_NewRef()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_NewRef) можно использовать для создания новой сильной ссылки.4243Когда объект больше не нужен, ссылку освобождают вызовом [`Py_DECREF()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_DECREF).4445Объект не должен быть `NULL`; если нет уверенности, что он не `NULL`, используйте [`Py_XINCREF()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_XINCREF).4647Не рассчитывайте, что эта функция действительно изменит *o*. По крайней мере для [**некоторых объектов**](https://python-all.ru/3.13/c-api/refcounting.html) эта функция не имеет эффекта.4849Изменено в версии 3.12: Бессмертные объекты не изменяются.5051#### `void Py_XINCREF(PyObject *o)`5253Аналогично [`Py_INCREF()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_INCREF), но объект *o* может быть `NULL`, в этом случае функция не действует.5455См. также [`Py_XNewRef()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_XNewRef).5657#### `PyObject *Py_NewRef(PyObject *o)`5859*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.10.*6061Создаёт новую [сильную ссылку](https://python-all.ru/3.13/glossary.html#term-strong-reference) на объект: вызывает [`Py_INCREF()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_INCREF) для *o* и возвращает объект *o*.6263Когда [сильная ссылка](https://python-all.ru/3.13/glossary.html#term-strong-reference) больше не нужна, для её освобождения следует вызвать [`Py_DECREF()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_DECREF).6465Объект *o* не должен быть `NULL`; используйте [`Py_XNewRef()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_XNewRef), если *o* может быть `NULL`.6667Например:6869```c70Py_INCREF(obj);71self->attr = obj;72```7374можно записать как:7576```c77self->attr = Py_NewRef(obj);78```7980См. также [`Py_INCREF()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_INCREF).8182Добавлено в версии 3.10.8384#### `PyObject *Py_XNewRef(PyObject *o)`8586*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable) начиная с версии 3.10.*8788Аналогично [`Py_NewRef()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_NewRef), но объект *o* может быть NULL.8990Если объект *o* равен `NULL`, функция просто возвращает `NULL`.9192Добавлено в версии 3.10.9394#### `void Py_DECREF(PyObject *o)`9596Освобождает [сильную ссылку](https://python-all.ru/3.13/glossary.html#term-strong-reference) на объект *o*, показывая, что ссылка больше не используется.9798Эта функция не влияет на [бессмертные](https://python-all.ru/3.13/glossary.html#term-immortal) объекты.99100Когда последняя [сильная ссылка](https://python-all.ru/3.13/glossary.html#term-strong-reference) освобождена (т.е. счётчик ссылок объекта достигает 0), вызывается функция освобождения типа объекта (которая не должна быть `NULL`).101102Эта функция обычно используется для удаления [сильной ссылки](https://python-all.ru/3.13/glossary.html#term-strong-reference) перед выходом из области видимости.103104Объект не должен быть `NULL`; если нет уверенности, что он не `NULL`, используйте [`Py_XDECREF()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_XDECREF).105106Не рассчитывайте, что эта функция действительно изменит *o*. По крайней мере для [**некоторых объектов**](https://python-all.ru/3.13/c-api/refcounting.html) эта функция не имеет эффекта.107108> **Предупреждение**109>110> Функция освобождения может вызвать выполнение произвольного кода Python (например, при освобождении экземпляра класса с методом [`__del__()`](https://python-all.ru/3.13/reference/datamodel.html#object.__del__)). Хотя исключения в таком коде не распространяются, выполняемый код имеет свободный доступ ко всем глобальным переменным Python. Это означает, что любой объект, достижимый из глобальной переменной, должен находиться в согласованном состоянии перед вызовом [`Py_DECREF()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_DECREF). Например, код, удаляющий объект из списка, должен скопировать ссылку на удаляемый объект во временную переменную, обновить структуру данных списка, а затем вызвать `Py_DECREF()` для временной переменной.111112Изменено в версии 3.12: Бессмертные объекты не изменяются.113114#### `void Py_XDECREF(PyObject *o)`115116Аналогично [`Py_DECREF()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_DECREF), но объект *o* может быть `NULL`, в этом случае функция не имеет эффекта. Предупреждение из `Py_DECREF()` применимо и здесь.117118#### `void Py_CLEAR(PyObject *o)`119120Освобождает [сильную ссылку](https://python-all.ru/3.13/glossary.html#term-strong-reference) на объект *o*. Объект может быть `NULL`, в этом случае макрос не имеет эффекта; в противном случае эффект такой же, как для [`Py_DECREF()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_DECREF), за исключением того, что аргумент также устанавливается в `NULL`. Предупреждение для `Py_DECREF()` не применяется к переданному объекту, потому что макрос осторожно использует временную переменную и устанавливает аргумент в `NULL` перед освобождением ссылки.121122Рекомендуется использовать этот макрос всякий раз, когда освобождается ссылка на объект, который может быть обойдён во время сборки мусора.123124Изменено в версии 3.12: Аргумент макроса теперь вычисляется только один раз. Если аргумент имеет побочные эффекты, они больше не дублируются.125126#### `void Py_IncRef(PyObject *o)`127128*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*129130Указывает на получение новой [сильной ссылки](https://python-all.ru/3.13/glossary.html#term-strong-reference) на объект *o*. Функциональная версия [`Py_XINCREF()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_XINCREF). Может использоваться для динамического встраивания Python во время выполнения.131132#### `void Py_DecRef(PyObject *o)`133134*Часть [Stable ABI](https://python-all.ru/3.13/c-api/stable.html#stable).*135136Освобождает [сильную ссылку](https://python-all.ru/3.13/glossary.html#term-strong-reference) на объект *o*. Функциональная версия [`Py_XDECREF()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_XDECREF). Может использоваться для динамического встраивания Python во время выполнения.137138#### `Py_SETREF(dst, src)`139140Макрос безопасно освобождает [сильную ссылку](https://python-all.ru/3.13/glossary.html#term-strong-reference) на объект *dst* и устанавливает *dst* в *src*.141142Как и в случае [`Py_CLEAR()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_CLEAR), «очевидный» код может быть смертельно опасен:143144```c145Py_DECREF(dst);146dst = src;147```148149Безопасный способ:150151```c152Py_SETREF(dst, src);153```154155Это обеспечивает установку *dst* в *src* *до* освобождения ссылки на старое значение *dst*, так что любой код, запущенный как побочный эффект уничтожения *dst*, больше не будет считать, что *dst* указывает на допустимый объект.156157Добавлено в версии 3.6.158159Изменено в версии 3.12: Аргументы макроса теперь вычисляются только один раз. Если аргумент имеет побочные эффекты, они больше не дублируются.160161#### `Py_XSETREF(dst, src)`162163Вариант макроса [`Py_SETREF`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_SETREF), который использует [`Py_XDECREF()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_XDECREF) вместо [`Py_DECREF()`](https://python-all.ru/3.13/c-api/refcounting.html#c.Py_DECREF).164165Добавлено в версии 3.6.166167Изменено в версии 3.12: Аргументы макроса теперь вычисляются только один раз. Если аргумент имеет побочные эффекты, они больше не дублируются.168