Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/gcsupport.rst @ 54294:dba767bc3155 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
remove mention of old ctypes version
author Benjamin Peterson <benjamin@python.org>
date Sat, 23 May 2009 20:59:09 +0000
parents 694daf8cdf99
children 5b1da32c9d4e
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 .. highlightlang:: c
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
2
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
3 .. _supporting-cycle-detection:
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
4
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 Supporting Cyclic Garbage Collection
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
6 ====================================
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
7
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
8 Python's support for detecting and collecting garbage which involves circular
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
9 references requires support from object types which are "containers" for other
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
10 objects which may also be containers. Types which do not store references to
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
11 other objects, or which only store references to atomic types (such as numbers
53423
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
12 or strings), do not need to provide any explicit support for garbage
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
13 collection.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
14
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
15 .. An example showing the use of these interfaces can be found in "Supporting the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
16 .. Cycle Collector (XXX not found: ../ext/example-cycle-support.html)".
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
17
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
18 To create a container type, the :attr:`tp_flags` field of the type object must
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
19 include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
20 :attr:`tp_traverse` handler. If instances of the type are mutable, a
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
21 :attr:`tp_clear` implementation must also be provided.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
22
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
23
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
24 .. data:: Py_TPFLAGS_HAVE_GC
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
25 :noindex:
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
26
53423
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
27 Objects with a type with this flag set must conform with the rules
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
28 documented here. For convenience these objects will be referred to as
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
29 container objects.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
30
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
31 Constructors for container types must conform to two rules:
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
32
53423
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
33 #. The memory for the object must be allocated using :cfunc:`PyObject_GC_New`
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
34 or :cfunc:`PyObject_GC_VarNew`.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
35
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
36 #. Once all the fields which may contain references to other containers are
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
37 initialized, it must call :cfunc:`PyObject_GC_Track`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
38
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
39
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
40 .. cfunction:: TYPE* PyObject_GC_New(TYPE, PyTypeObject *type)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
41
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
42 Analogous to :cfunc:`PyObject_New` but for container objects with the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
43 :const:`Py_TPFLAGS_HAVE_GC` flag set.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
44
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
45
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
46 .. cfunction:: TYPE* PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
47
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
48 Analogous to :cfunc:`PyObject_NewVar` but for container objects with the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
49 :const:`Py_TPFLAGS_HAVE_GC` flag set.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
50
53424
694daf8cdf99 Issue #4129: More documentation pointers about int -> Py_ssize_t.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53423
diff changeset
51 .. versionchanged:: 2.5
694daf8cdf99 Issue #4129: More documentation pointers about int -> Py_ssize_t.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53423
diff changeset
52 This function used an :ctype:`int` type for *size*. This might require
694daf8cdf99 Issue #4129: More documentation pointers about int -> Py_ssize_t.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53423
diff changeset
53 changes in your code for properly supporting 64-bit systems.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
54
53424
694daf8cdf99 Issue #4129: More documentation pointers about int -> Py_ssize_t.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53423
diff changeset
55
694daf8cdf99 Issue #4129: More documentation pointers about int -> Py_ssize_t.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53423
diff changeset
56 .. cfunction:: TYPE* PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
57
53423
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
58 Resize an object allocated by :cfunc:`PyObject_NewVar`. Returns the
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
59 resized object or *NULL* on failure.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
60
53424
694daf8cdf99 Issue #4129: More documentation pointers about int -> Py_ssize_t.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53423
diff changeset
61 .. versionchanged:: 2.5
694daf8cdf99 Issue #4129: More documentation pointers about int -> Py_ssize_t.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53423
diff changeset
62 This function used an :ctype:`int` type for *newsize*. This might
694daf8cdf99 Issue #4129: More documentation pointers about int -> Py_ssize_t.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53423
diff changeset
63 require changes in your code for properly supporting 64-bit systems.
694daf8cdf99 Issue #4129: More documentation pointers about int -> Py_ssize_t.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53423
diff changeset
64
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
65
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
66 .. cfunction:: void PyObject_GC_Track(PyObject *op)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
67
53423
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
68 Adds the object *op* to the set of container objects tracked by the
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
69 collector. The collector can run at unexpected times so objects must be
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
70 valid while being tracked. This should be called once all the fields
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
71 followed by the :attr:`tp_traverse` handler become valid, usually near the
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
72 end of the constructor.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
73
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
74
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
75 .. cfunction:: void _PyObject_GC_TRACK(PyObject *op)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
76
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
77 A macro version of :cfunc:`PyObject_GC_Track`. It should not be used for
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
78 extension modules.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
79
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
80 Similarly, the deallocator for the object must conform to a similar pair of
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
81 rules:
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
82
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
83 #. Before fields which refer to other containers are invalidated,
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
84 :cfunc:`PyObject_GC_UnTrack` must be called.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
85
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
86 #. The object's memory must be deallocated using :cfunc:`PyObject_GC_Del`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
87
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
88
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
89 .. cfunction:: void PyObject_GC_Del(void *op)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
90
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
91 Releases memory allocated to an object using :cfunc:`PyObject_GC_New` or
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
92 :cfunc:`PyObject_GC_NewVar`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
93
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
94
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
95 .. cfunction:: void PyObject_GC_UnTrack(void *op)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
96
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
97 Remove the object *op* from the set of container objects tracked by the
53423
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
98 collector. Note that :cfunc:`PyObject_GC_Track` can be called again on
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
99 this object to add it back to the set of tracked objects. The deallocator
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
100 (:attr:`tp_dealloc` handler) should call this for the object before any of
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
101 the fields used by the :attr:`tp_traverse` handler become invalid.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
102
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
103
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
104 .. cfunction:: void _PyObject_GC_UNTRACK(PyObject *op)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
105
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
106 A macro version of :cfunc:`PyObject_GC_UnTrack`. It should not be used for
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
107 extension modules.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
108
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
109 The :attr:`tp_traverse` handler accepts a function parameter of this type:
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
110
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
111
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
112 .. ctype:: int (*visitproc)(PyObject *object, void *arg)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
113
53423
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
114 Type of the visitor function passed to the :attr:`tp_traverse` handler.
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
115 The function should be called with an object to traverse as *object* and
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
116 the third parameter to the :attr:`tp_traverse` handler as *arg*. The
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
117 Python core uses several visitor functions to implement cyclic garbage
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
118 detection; it's not expected that users will need to write their own
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
119 visitor functions.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
120
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
121 The :attr:`tp_traverse` handler must have the following type:
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
122
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
123
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
124 .. ctype:: int (*traverseproc)(PyObject *self, visitproc visit, void *arg)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
125
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
126 Traversal function for a container object. Implementations must call the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
127 *visit* function for each object directly contained by *self*, with the
53423
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
128 parameters to *visit* being the contained object and the *arg* value passed
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
129 to the handler. The *visit* function must not be called with a *NULL*
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
130 object argument. If *visit* returns a non-zero value that value should be
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
131 returned immediately.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
132
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
133 To simplify writing :attr:`tp_traverse` handlers, a :cfunc:`Py_VISIT` macro is
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
134 provided. In order to use this macro, the :attr:`tp_traverse` implementation
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
135 must name its arguments exactly *visit* and *arg*:
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
136
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
137
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
138 .. cfunction:: void Py_VISIT(PyObject *o)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
139
53423
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
140 Call the *visit* callback, with arguments *o* and *arg*. If *visit* returns
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
141 a non-zero value, then return it. Using this macro, :attr:`tp_traverse`
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
142 handlers look like::
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
143
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
144 static int
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
145 my_traverse(Noddy *self, visitproc visit, void *arg)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
146 {
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
147 Py_VISIT(self->foo);
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
148 Py_VISIT(self->bar);
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
149 return 0;
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
150 }
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
151
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
152 .. versionadded:: 2.4
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
153
53423
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
154 The :attr:`tp_clear` handler must be of the :ctype:`inquiry` type, or *NULL*
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
155 if the object is immutable.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
156
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
157
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
158 .. ctype:: int (*inquiry)(PyObject *self)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
159
53423
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
160 Drop references that may have created reference cycles. Immutable objects
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
161 do not have to define this method since they can never directly create
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
162 reference cycles. Note that the object must still be valid after calling
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
163 this method (don't just call :cfunc:`Py_DECREF` on a reference). The
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
164 collector will call this method if it detects that this object is involved
2e297b1ec935 Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
165 in a reference cycle.