← Back to branch summary

~ubuntu-branches/ubuntu/maverick/python3.1/maverick

« back to all changes in this revision

Viewing changes to Doc/c-api/weakref.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-03-23 00:01:27 UTC
  • Revision ID: james.westby@ubuntu.com-20090323000127-5fstfxju4ufrhthq
Tags: upstream-3.1~a1+20090322
Import upstream version 3.1~a1+20090322

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/c-api/weakref.rst
 
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
 
 
19
.. cfunction:: int PyWeakref_CheckRef(ob)
 
20
 
 
21
   Return true if *ob* is a reference object.
 
22
 
 
23
 
 
24
.. cfunction:: int PyWeakref_CheckProxy(ob)
 
25
 
 
26
   Return true if *ob* is a proxy object.
 
27
 
 
28
 
 
29
.. cfunction:: PyObject* PyWeakref_NewRef(PyObject *ob, PyObject *callback)
 
30
 
 
31
   Return a weak reference object for the object *ob*.  This will always return
 
32
   a new reference, but is not guaranteed to create a new object; an existing
 
33
   reference object may be returned.  The second parameter, *callback*, can be a
 
34
   callable object that receives notification when *ob* is garbage collected; it
 
35
   should accept a single parameter, which will be the weak reference object
 
36
   itself. *callback* may also be ``None`` or *NULL*.  If *ob* is not a
 
37
   weakly-referencable object, or if *callback* is not callable, ``None``, or
 
38
   *NULL*, this will return *NULL* and raise :exc:`TypeError`.
 
39
 
 
40
 
 
41
.. cfunction:: PyObject* PyWeakref_NewProxy(PyObject *ob, PyObject *callback)
 
42
 
 
43
   Return a weak reference proxy object for the object *ob*.  This will always
 
44
   return a new reference, but is not guaranteed to create a new object; an
 
45
   existing proxy object may be returned.  The second parameter, *callback*, can
 
46
   be a callable object that receives notification when *ob* is garbage
 
47
   collected; it should accept a single parameter, which will be the weak
 
48
   reference object itself. *callback* may also be ``None`` or *NULL*.  If *ob*
 
49
   is not a weakly-referencable object, or if *callback* is not callable,
 
50
   ``None``, or *NULL*, this will return *NULL* and raise :exc:`TypeError`.
 
51
 
 
52
 
 
53
.. cfunction:: PyObject* PyWeakref_GetObject(PyObject *ref)
 
54
 
 
55
   Return the referenced object from a weak reference, *ref*.  If the referent is
 
56
   no longer live, returns ``None``.
 
57
 
 
58
 
 
59
.. cfunction:: PyObject* PyWeakref_GET_OBJECT(PyObject *ref)
 
60
 
 
61
   Similar to :cfunc:`PyWeakref_GetObject`, but implemented as a macro that does no
 
62
   error checking.