Debian Codegraph @

Doc/c-api/weakref.rst

raw
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