|
1 .. highlightlang:: 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 .. cfunction:: 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 .. cfunction:: int PyWeakref_CheckRef(ob) |
|
22 |
|
23 Return true if *ob* is a reference object. |
|
24 |
|
25 .. versionadded:: 2.2 |
|
26 |
|
27 |
|
28 .. cfunction:: int PyWeakref_CheckProxy(ob) |
|
29 |
|
30 Return true if *ob* is a proxy object. |
|
31 |
|
32 .. versionadded:: 2.2 |
|
33 |
|
34 |
|
35 .. cfunction:: 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 .. cfunction:: 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 .. cfunction:: 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 ``None``. |
|
67 |
|
68 .. versionadded:: 2.2 |
|
69 |
|
70 |
|
71 .. cfunction:: PyObject* PyWeakref_GET_OBJECT(PyObject *ref) |
|
72 |
|
73 Similar to :cfunc:`PyWeakref_GetObject`, but implemented as a macro that does no |
|
74 error checking. |
|
75 |
|
76 .. versionadded:: 2.2 |