| 1 |
.. highlight:: c |
| 2 |
|
| 3 |
.. _weakrefobjects: |
| 4 |
|
| 5 |
Weak Reference Objects |
| 6 |
---------------------- |
| 7 |
|
| 8 |
Python supports *weak references* as first-class objects. There are two |
| 9 |
specific object types which directly implement weak references. The first is a |
| 10 |
simple reference object, and the second acts as a proxy for the original object |
| 11 |
as much as it can. |
| 12 |
|
| 13 |
|
| 14 |
.. c:function:: int PyWeakref_Check(PyObject *ob) |
| 15 |
|
| 16 |
Return non-zero if *ob* is either a reference or proxy object. This function |
| 17 |
always succeeds. |
| 18 |
|
| 19 |
|
| 20 |
.. c:function:: int PyWeakref_CheckRef(PyObject *ob) |
| 21 |
|
| 22 |
Return non-zero if *ob* is a reference object or a subclass of the reference |
| 23 |
type. This function always succeeds. |
| 24 |
|
| 25 |
|
| 26 |
.. c:function:: int PyWeakref_CheckRefExact(PyObject *ob) |
| 27 |
|
| 28 |
Return non-zero if *ob* is a reference object, but not a subclass of the |
| 29 |
reference type. This function always succeeds. |
| 30 |
|
| 31 |
|
| 32 |
.. c:function:: int PyWeakref_CheckProxy(PyObject *ob) |
| 33 |
|
| 34 |
Return non-zero if *ob* is a proxy object. This function always succeeds. |
| 35 |
|
| 36 |
|
| 37 |
.. c:function:: PyObject* PyWeakref_NewRef(PyObject *ob, PyObject *callback) |
| 38 |
|
| 39 |
Return a weak reference object for the object *ob*. This will always return |
| 40 |
a new reference, but is not guaranteed to create a new object; an existing |
| 41 |
reference object may be returned. The second parameter, *callback*, can be a |
| 42 |
callable object that receives notification when *ob* is garbage collected; it |
| 43 |
should accept a single parameter, which will be the weak reference object |
| 44 |
itself. *callback* may also be ``None`` or ``NULL``. If *ob* is not a |
| 45 |
weakly referenceable object, or if *callback* is not callable, ``None``, or |
| 46 |
``NULL``, this will return ``NULL`` and raise :exc:`TypeError`. |
| 47 |
|
| 48 |
.. seealso:: |
| 49 |
:c:func:`PyType_SUPPORTS_WEAKREFS` for checking if *ob* is weakly |
| 50 |
referenceable. |
| 51 |
|
| 52 |
|
| 53 |
.. c:function:: PyObject* PyWeakref_NewProxy(PyObject *ob, PyObject *callback) |
| 54 |
|
| 55 |
Return a weak reference proxy object for the object *ob*. This will always |
| 56 |
return a new reference, but is not guaranteed to create a new object; an |
| 57 |
existing proxy object may be returned. The second parameter, *callback*, can |
| 58 |
be a callable object that receives notification when *ob* is garbage |
| 59 |
collected; it should accept a single parameter, which will be the weak |
| 60 |
reference object itself. *callback* may also be ``None`` or ``NULL``. If *ob* |
| 61 |
is not a weakly referenceable object, or if *callback* is not callable, |
| 62 |
``None``, or ``NULL``, this will return ``NULL`` and raise :exc:`TypeError`. |
| 63 |
|
| 64 |
.. seealso:: |
| 65 |
:c:func:`PyType_SUPPORTS_WEAKREFS` for checking if *ob* is weakly |
| 66 |
referenceable. |
| 67 |
|
| 68 |
|
| 69 |
.. c:function:: int PyWeakref_GetRef(PyObject *ref, PyObject **pobj) |
| 70 |
|
| 71 |
Get a :term:`strong reference` to the referenced object from a weak |
| 72 |
reference, *ref*, into *\*pobj*. |
| 73 |
|
| 74 |
* On success, set *\*pobj* to a new :term:`strong reference` to the |
| 75 |
referenced object and return 1. |
| 76 |
* If the reference is dead, set *\*pobj* to ``NULL`` and return 0. |
| 77 |
* On error, raise an exception and return -1. |
| 78 |
|
| 79 |
.. versionadded:: 3.13 |
| 80 |
|
| 81 |
|
| 82 |
.. c:function:: PyObject* PyWeakref_GetObject(PyObject *ref) |
| 83 |
|
| 84 |
Return a :term:`borrowed reference` to the referenced object from a weak |
| 85 |
reference, *ref*. If the referent is no longer live, returns ``Py_None``. |
| 86 |
|
| 87 |
.. note:: |
| 88 |
|
| 89 |
This function returns a :term:`borrowed reference` to the referenced object. |
| 90 |
This means that you should always call :c:func:`Py_INCREF` on the object |
| 91 |
except when it cannot be destroyed before the last usage of the borrowed |
| 92 |
reference. |
| 93 |
|
| 94 |
.. deprecated-removed:: 3.13 3.15 |
| 95 |
Use :c:func:`PyWeakref_GetRef` instead. |
| 96 |
|
| 97 |
|
| 98 |
.. c:function:: PyObject* PyWeakref_GET_OBJECT(PyObject *ref) |
| 99 |
|
| 100 |
Similar to :c:func:`PyWeakref_GetObject`, but does no error checking. |
| 101 |
|
| 102 |
.. deprecated-removed:: 3.13 3.15 |
| 103 |
Use :c:func:`PyWeakref_GetRef` instead. |
| 104 |
|
| 105 |
|
| 106 |
.. c:function:: int PyWeakref_IsDead(PyObject *ref) |
| 107 |
|
| 108 |
Test if the weak reference *ref* is dead. Returns 1 if the reference is |
| 109 |
dead, 0 if it is alive, and -1 with an error set if *ref* is not a weak |
| 110 |
reference object. |
| 111 |
|
| 112 |
.. versionadded:: 3.14 |
| 113 |
|
| 114 |
|
| 115 |
.. c:function:: void PyObject_ClearWeakRefs(PyObject *object) |
| 116 |
|
| 117 |
This function is called by the :c:member:`~PyTypeObject.tp_dealloc` handler |
| 118 |
to clear weak references. |
| 119 |
|
| 120 |
This iterates through the weak references for *object* and calls callbacks |
| 121 |
for those references which have one. It returns when all callbacks have |
| 122 |
been attempted. |
| 123 |
|
| 124 |
|
| 125 |
.. c:function:: void PyUnstable_Object_ClearWeakRefsNoCallbacks(PyObject *object) |
| 126 |
|
| 127 |
Clears the weakrefs for *object* without calling the callbacks. |
| 128 |
|
| 129 |
This function is called by the :c:member:`~PyTypeObject.tp_dealloc` handler |
| 130 |
for types with finalizers (i.e., :meth:`~object.__del__`). The handler for |
| 131 |
those objects first calls :c:func:`PyObject_ClearWeakRefs` to clear weakrefs |
| 132 |
and call their callbacks, then the finalizer, and finally this function to |
| 133 |
clear any weakrefs that may have been created by the finalizer. |
| 134 |
|
| 135 |
In most circumstances, it's more appropriate to use |
| 136 |
:c:func:`PyObject_ClearWeakRefs` to clear weakrefs instead of this function. |
| 137 |
|
| 138 |
.. versionadded:: 3.13 |