← Back to branch summary

~dkuhlman/python-training-materials/Materials

« back to all changes in this revision

Viewing changes to python-2.7.11-docs-html/_sources/c-api/weakref.txt

  • Committer: Dave Kuhlman
  • Date: 2017-04-15 16:24:56 UTC
  • Revision ID: dkuhlman@davekuhlman.org-20170415162456-iav9vozzg4iwqwv3
Updated docs

Show diffs side-by-side

added added

removed removed

Lines of Context:
python-2.7.11-docs-html/_sources/c-api/weakref.txt
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
 
.. 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