1.. highlightlang:: c
2
3.. _weakrefobjects:
4
5Weak Reference Objects
6----------------------
7
8Python supports *weak references* as first-class objects.  There are two
9specific object types which directly implement weak references.  The first is a
10simple reference object, and the second acts as a proxy for the original object
11as much as it can.
12
13
14.. c:function:: int PyWeakref_Check(ob)
15
16   Return true if *ob* is either a reference or proxy object.
17
18   .. versionadded:: 2.2
19
20
21.. c:function:: int PyWeakref_CheckRef(ob)
22
23   Return true if *ob* is a reference object.
24
25   .. versionadded:: 2.2
26
27
28.. c:function:: int PyWeakref_CheckProxy(ob)
29
30   Return true if *ob* is a proxy object.
31
32   .. versionadded:: 2.2
33
34
35.. c:function:: PyObject* PyWeakref_NewRef(PyObject *ob, PyObject *callback)
36
37   Return a weak reference object for the object *ob*.  This will always return
38   a new reference, but is not guaranteed to create a new object; an existing
39   reference object may be returned.  The second parameter, *callback*, can be a
40   callable object that receives notification when *ob* is garbage collected; it
41   should accept a single parameter, which will be the weak reference object
42   itself. *callback* may also be ``None`` or *NULL*.  If *ob* is not a
43   weakly-referencable object, or if *callback* is not callable, ``None``, or
44   *NULL*, this will return *NULL* and raise :exc:`TypeError`.
45
46   .. versionadded:: 2.2
47
48
49.. c:function:: PyObject* PyWeakref_NewProxy(PyObject *ob, PyObject *callback)
50
51   Return a weak reference proxy object for the object *ob*.  This will always
52   return a new reference, but is not guaranteed to create a new object; an
53   existing proxy object may be returned.  The second parameter, *callback*, can
54   be a callable object that receives notification when *ob* is garbage
55   collected; it should accept a single parameter, which will be the weak
56   reference object itself. *callback* may also be ``None`` or *NULL*.  If *ob*
57   is not a weakly-referencable object, or if *callback* is not callable,
58   ``None``, or *NULL*, this will return *NULL* and raise :exc:`TypeError`.
59
60   .. versionadded:: 2.2
61
62
63.. c:function:: PyObject* PyWeakref_GetObject(PyObject *ref)
64
65   Return the referenced object from a weak reference, *ref*.  If the referent is
66   no longer live, returns :const:`Py_None`.
67
68   .. versionadded:: 2.2
69
70   .. warning::
71
72      This function returns a **borrowed reference** to the referenced object.
73      This means that you should always call :c:func:`Py_INCREF` on the object
74      except if you know that it cannot be destroyed while you are still
75      using it.
76
77
78.. c:function:: PyObject* PyWeakref_GET_OBJECT(PyObject *ref)
79
80   Similar to :c:func:`PyWeakref_GetObject`, but implemented as a macro that does no
81   error checking.
82
83   .. versionadded:: 2.2
84