Объекты слабых ссылок

Python поддерживает слабые ссылки как объекты первого класса. Существует два специальных типа объектов, непосредственно реализующих слабые ссылки. Первый — простой объект-ссылка, а второй действует, насколько это возможно, как прокси исходного объекта.

int PyWeakref_Check(PyObject *ob)

Возвращает ненулевое значение, если ob является объектом-ссылкой или объектом-прокси. Эта функция всегда завершается успешно.

int PyWeakref_CheckRef(PyObject *ob)

Возвращает ненулевое значение, если ob является объектом-ссылкой. Эта функция всегда завершается успешно.

int PyWeakref_CheckProxy(PyObject *ob)

Возвращает ненулевое значение, если ob является объектом-прокси. Эта функция всегда завершается успешно.

PyObject *PyWeakref_NewRef(PyObject *ob, PyObject *callback)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

Возвращает объект слабой ссылки на объект ob. Эта функция всегда возвращает новую ссылку, но не гарантирует создание нового объекта: может быть возвращён уже существующий объект-ссылка. Второй параметр, callback, может быть вызываемым объектом, который получает уведомление при сборке мусора для ob; он должен принимать один параметр — сам объект слабой ссылки. Значением callback также может быть None или NULL. Если на объект ob нельзя создать слабую ссылку или если callback не является вызываемым объектом, None или NULL, функция возвращает NULL и вызывает исключение TypeError.

PyObject *PyWeakref_NewProxy(PyObject *ob, PyObject *callback)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.

Возвращает объект-прокси слабой ссылки на объект ob. Эта функция всегда возвращает новую ссылку, но не гарантирует создание нового объекта: может быть возвращён уже существующий объект-прокси. Второй параметр, callback, может быть вызываемым объектом, который получает уведомление при сборке мусора для ob; он должен принимать один параметр — сам объект слабой ссылки. Значением callback также может быть None или NULL. Если на объект ob нельзя создать слабую ссылку или если callback не является вызываемым объектом, None или NULL, функция возвращает NULL и вызывает исключение TypeError.

int PyWeakref_GetRef(PyObject *ref, PyObject **pobj)

Часть стабильного ABI начиная с версии 3.13.

Получает сильную ссылку на объект, на который указывает слабая ссылка ref, и помещает её в *pobj.

• В случае успеха устанавливает *pobj в новую сильную ссылку на объект, на который указывает ссылка, и возвращает 1.
• Если ссылка мертва, устанавливает *pobj в NULL и возвращает 0.
• В случае ошибки вызывает исключение и возвращает -1.

Добавлено в версии 3.13.

PyObject *PyWeakref_GetObject(PyObject *ref)

Возвращаемое значение: заимствованная ссылка. Часть стабильного ABI.

Возвращает заимствованную ссылку на объект, на который указывает слабая ссылка ref. Если объект, на который указывает ссылка, больше не существует, возвращает Py_None.

Примечание

Эта функция возвращает заимствованную ссылку на объект, на который указывает ссылка. Это означает, что всегда следует вызывать для объекта Py_INCREF(), кроме случаев, когда объект не может быть уничтожен до последнего использования заимствованной ссылки.

Устарела с версии 3.13, будет удалена в версии 3.15: Вместо неё используйте PyWeakref_GetRef().

PyObject *PyWeakref_GET_OBJECT(PyObject *ref)

Возвращаемое значение: заимствованная ссылка.

Аналогична PyWeakref_GetObject(), но не выполняет проверку ошибок.

Устарела с версии 3.13, будет удалена в версии 3.15: Вместо неё используйте PyWeakref_GetRef().

void PyObject_ClearWeakRefs(PyObject *object)

Часть стабильного ABI.

Эта функция вызывается обработчиком tp_dealloc для очистки слабых ссылок.

Функция перебирает слабые ссылки на object и вызывает обратные вызовы для тех ссылок, у которых они есть. Она возвращает управление после попытки выполнить все обратные вызовы.

void PyUnstable_Object_ClearWeakRefsNoCallbacks(PyObject *object)

Это нестабильный API. Он может измениться без предупреждения в минорных выпусках.

Очищает слабые ссылки на object, не вызывая обратные вызовы.

Эта функция вызывается обработчиком tp_dealloc для типов с финализаторами (то есть __del__()). Обработчик таких объектов сначала вызывает PyObject_ClearWeakRefs() для очистки слабых ссылок и вызова их обратных вызовов, затем запускает финализатор и, наконец, вызывает эту функцию для очистки слабых ссылок, которые могли быть созданы финализатором.

В большинстве случаев для очистки слабых ссылок вместо этой функции уместнее использовать PyObject_ClearWeakRefs().

Добавлено в версии 3.13.