[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / python / api / supporting-cycle-detection.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="api.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="api.html" title='Python/C API Reference Manual' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="prev" href="supporting-iteration.html" />
<link rel="parent" href="newTypes.html" />
<link rel="next" href="reporting-bugs.html" />
<meta name='aesop' content='information' />
<title>10.9 Supporting Cyclic Garbage Collection </title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="10.8 Supporting the Iterator"
  href="supporting-iteration.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="10. Object Implementation Support"
  href="newTypes.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="A. Reporting Bugs"
  href="reporting-bugs.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python/C API Reference Manual</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="supporting-iteration.html">10.8 Supporting the Iterator</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="newTypes.html">10. Object Implementation Support</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="reporting-bugs.html">A. Reporting Bugs</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION0012900000000000000000"></A><A NAME="supporting-cycle-detection"></A>
<BR>
10.9 Supporting Cyclic Garbage Collection
         
</H1>

<P>
Python's support for detecting and collecting garbage which involves
circular references requires support from object types which are
``containers'' for other objects which may also be containers.  Types
which do not store references to other objects, or which only store
references to atomic types (such as numbers or strings), do not need
to provide any explicit support for garbage collection.

<P>
An example showing the use of these interfaces can be found in
``<a class="ulink" href="../ext/example-cycle-support.html"
  >Supporting the Cycle
Collector</a>'' in
<em class="citetitle"><a
 href="../ext/ext.html"
 title="Extending and Embedding the Python
Interpreter"
 >Extending and Embedding the Python
Interpreter</a></em>.

<P>
To create a container type, the <tt class="member">tp_flags</tt> field of the type
object must include the <tt class="constant">Py_TPFLAGS_HAVE_GC</tt> and provide an
implementation of the <tt class="member">tp_traverse</tt> handler.  If instances of the
type are mutable, a <tt class="member">tp_clear</tt> implementation must also be
provided.

<P>
<dl><dt><b><tt id='l2h-1015' xml:id='l2h-1015'>Py_TPFLAGS_HAVE_GC</tt></b></dt>
<dd>
  Objects with a type with this flag set must conform with the rules
  documented here.  For convenience these objects will be referred to
  as container objects.
</dd></dl>

<P>
Constructors for container types must conform to two rules:

<P>

<OL>
<LI>The memory for the object must be allocated using
       <tt class="cfunction">PyObject_GC_New()</tt> or <tt class="cfunction">PyObject_GC_VarNew()</tt>.

<P>
</LI>
<LI>Once all the fields which may contain references to other
       containers are initialized, it must call
       <tt class="cfunction">PyObject_GC_Track()</tt>.
</LI>
</OL>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr><var>TYPE</var>*&nbsp;<b><tt id='l2h-1016' xml:id='l2h-1016' class="cfunction">PyObject_GC_New</tt></b>(</nobr></td><td>TYPE, PyTypeObject *<var>type</var>)</td></tr></table></dt>
<dd>
  Analogous to <tt class="cfunction">PyObject_New()</tt> but for container objects with
  the <tt class="constant">Py_TPFLAGS_HAVE_GC</tt> flag set.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr><var>TYPE</var>*&nbsp;<b><tt id='l2h-1017' xml:id='l2h-1017' class="cfunction">PyObject_GC_NewVar</tt></b>(</nobr></td><td>TYPE, PyTypeObject *<var>type</var>,
                                                   int <var>size</var>)</td></tr></table></dt>
<dd>
  Analogous to <tt class="cfunction">PyObject_NewVar()</tt> but for container objects
  with the <tt class="constant">Py_TPFLAGS_HAVE_GC</tt> flag set.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyVarObject *&nbsp;<b><tt id='l2h-1018' xml:id='l2h-1018' class="cfunction">PyObject_GC_Resize</tt></b>(</nobr></td><td>PyVarObject *<var>op</var>, <var>int</var>)</td></tr></table></dt>
<dd>
  Resize an object allocated by <tt class="cfunction">PyObject_NewVar()</tt>.  Returns
  the resized object or <tt class="constant">NULL</tt> on failure.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void&nbsp;<b><tt id='l2h-1019' xml:id='l2h-1019' class="cfunction">PyObject_GC_Track</tt></b>(</nobr></td><td>PyObject *<var>op</var>)</td></tr></table></dt>
<dd>
  Adds the object <var>op</var> to the set of container objects tracked by
  the collector.  The collector can run at unexpected times so objects
  must be valid while being tracked.  This should be called once all
  the fields followed by the <tt class="member">tp_traverse</tt> handler become valid,
  usually near the end of the constructor.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void&nbsp;<b><tt id='l2h-1020' xml:id='l2h-1020' class="cfunction">_PyObject_GC_TRACK</tt></b>(</nobr></td><td>PyObject *<var>op</var>)</td></tr></table></dt>
<dd>
  A macro version of <tt class="cfunction">PyObject_GC_Track()</tt>.  It should not be
  used for extension modules.
</dd></dl>

<P>
Similarly, the deallocator for the object must conform to a similar
pair of rules:

<P>

<OL>
<LI>Before fields which refer to other containers are invalidated,
       <tt class="cfunction">PyObject_GC_UnTrack()</tt> must be called.

<P>
</LI>
<LI>The object's memory must be deallocated using
       <tt class="cfunction">PyObject_GC_Del()</tt>.
</LI>
</OL>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void&nbsp;<b><tt id='l2h-1021' xml:id='l2h-1021' class="cfunction">PyObject_GC_Del</tt></b>(</nobr></td><td>PyObject *<var>op</var>)</td></tr></table></dt>
<dd>
  Releases memory allocated to an object using
  <tt class="cfunction">PyObject_GC_New()</tt> or <tt class="cfunction">PyObject_GC_NewVar()</tt>.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void&nbsp;<b><tt id='l2h-1022' xml:id='l2h-1022' class="cfunction">PyObject_GC_UnTrack</tt></b>(</nobr></td><td>PyObject *<var>op</var>)</td></tr></table></dt>
<dd>
  Remove the object <var>op</var> from the set of container objects tracked
  by the collector.  Note that <tt class="cfunction">PyObject_GC_Track()</tt> can be
  called again on this object to add it back to the set of tracked
  objects.  The deallocator (<tt class="member">tp_dealloc</tt> handler) should call
  this for the object before any of the fields used by the
  <tt class="member">tp_traverse</tt> handler become invalid.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void&nbsp;<b><tt id='l2h-1023' xml:id='l2h-1023' class="cfunction">_PyObject_GC_UNTRACK</tt></b>(</nobr></td><td>PyObject *<var>op</var>)</td></tr></table></dt>
<dd>
  A macro version of <tt class="cfunction">PyObject_GC_UnTrack()</tt>.  It should not be
  used for extension modules.
</dd></dl>

<P>
The <tt class="member">tp_traverse</tt> handler accepts a function parameter of this
type:

<P>
<dl><dt><b><tt class="ctype"><a id='l2h-1024' xml:id='l2h-1024'>int (*visitproc)(PyObject *object, void *arg)</a></tt></b></dt>
<dd>
  Type of the visitor function passed to the <tt class="member">tp_traverse</tt>
  handler.  The function should be called with an object to traverse
  as <var>object</var> and the third parameter to the <tt class="member">tp_traverse</tt>
  handler as <var>arg</var>.  The Python core uses several visitor functions
  to implement cyclic garbage detection; it's not expected that users will
  need to write their own visitor functions.
</dl>

<P>
The <tt class="member">tp_traverse</tt> handler must have the following type:

<P>
<dl><dt><b><tt class="ctype"><a id='l2h-1025' xml:id='l2h-1025'>int (*traverseproc)(PyObject *self,
                                visitproc visit, void *arg)</a></tt></b></dt>
<dd>
  Traversal function for a container object.  Implementations must
  call the <var>visit</var> function for each object directly contained by
  <var>self</var>, with the parameters to <var>visit</var> being the contained
  object and the <var>arg</var> value passed to the handler.  The <var>visit</var>
  function must not be called with a <tt class="constant">NULL</tt> object argument.  If
  <var>visit</var> returns a non-zero value
  that value should be returned immediately.
</dl>

<P>
To simplify writing <tt class="member">tp_traverse</tt> handlers, a
<tt class="cfunction">Py_VISIT()</tt> macro is provided.  In order to use this macro,
the <tt class="member">tp_traverse</tt> implementation must name its arguments
exactly <var>visit</var> and <var>arg</var>:

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void&nbsp;<b><tt id='l2h-1026' xml:id='l2h-1026' class="cfunction">Py_VISIT</tt></b>(</nobr></td><td>PyObject *<var>o</var>)</td></tr></table></dt>
<dd>
  Call the <var>visit</var> callback, with arguments <var>o</var> and <var>arg</var>.
  If <var>visit</var> returns a non-zero value, then return it.  Using this
  macro, <tt class="member">tp_traverse</tt> handlers look like:

<P>
<div class="verbatim"><pre>
static int
my_traverse(Noddy *self, visitproc visit, void *arg)
{
    Py_VISIT(self-&gt;foo);
    Py_VISIT(self-&gt;bar);
    return 0;
}
</pre></div>

<P>

<span class="versionnote">New in version 2.4.</span>

</dd></dl>

<P>
The <tt class="member">tp_clear</tt> handler must be of the <tt class="ctype">inquiry</tt> type, or
<tt class="constant">NULL</tt> if the object is immutable.

<P>
<dl><dt><b><tt class="ctype"><a id='l2h-1027' xml:id='l2h-1027'>int (*inquiry)(PyObject *self)</a></tt></b></dt>
<dd>
  Drop references that may have created reference cycles.  Immutable
  objects do not have to define this method since they can never
  directly create reference cycles.  Note that the object must still
  be valid after calling this method (don't just call
  <tt class="cfunction">Py_DECREF()</tt> on a reference).  The collector will call
  this method if it detects that this object is involved in a
  reference cycle.
</dl>

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="10.8 Supporting the Iterator"
  href="supporting-iteration.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="10. Object Implementation Support"
  href="newTypes.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="A. Reporting Bugs"
  href="reporting-bugs.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python/C API Reference Manual</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="supporting-iteration.html">10.8 Supporting the Iterator</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="newTypes.html">10. Object Implementation Support</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="reporting-bugs.html">A. Reporting Bugs</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>
Commit	Line	Data
86530b38 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="api.css" type='text/css' />
	5	<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
	6	<link rel='start' href='../index.html' title='Python Documentation Index' />
	7	<link rel="first" href="api.html" title='Python/C API Reference Manual' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	9	<link rel='index' href='genindex.html' title='Index' />
	10	<link rel='last' href='about.html' title='About this document...' />
	11	<link rel='help' href='about.html' title='About this document...' />
	12	<link rel="prev" href="supporting-iteration.html" />
	13	<link rel="parent" href="newTypes.html" />
	14	<link rel="next" href="reporting-bugs.html" />
	15	<meta name='aesop' content='information' />
	16	<title>10.9 Supporting Cyclic Garbage Collection </title>
	17	</head>
	18	<body>
	19	<DIV CLASS="navigation">
	20	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	21	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	22	<tr>
	23	<td class='online-navigation'><a rel="prev" title="10.8 Supporting the Iterator"
	24	href="supporting-iteration.html"><img src='../icons/previous.png'
	25	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	26	<td class='online-navigation'><a rel="parent" title="10. Object Implementation Support"
	27	href="newTypes.html"><img src='../icons/up.png'
	28	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	29	<td class='online-navigation'><a rel="next" title="A. Reporting Bugs"
	30	href="reporting-bugs.html"><img src='../icons/next.png'
	31	border='0' height='32' alt='Next Page' width='32' /></A></td>
	32	<td align="center" width="100%">Python/C API Reference Manual</td>
	33	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	34	href="contents.html"><img src='../icons/contents.png'
	35	border='0' height='32' alt='Contents' width='32' /></A></td>
	36	<td class='online-navigation'><img src='../icons/blank.png'
	37	border='0' height='32' alt='' width='32' /></td>
	38	<td class='online-navigation'><a rel="index" title="Index"
	39	href="genindex.html"><img src='../icons/index.png'
	40	border='0' height='32' alt='Index' width='32' /></A></td>
	41	</tr></table>
	42	<div class='online-navigation'>
	43	<b class="navlabel">Previous:</b>
	44	<a class="sectref" rel="prev" href="supporting-iteration.html">10.8 Supporting the Iterator</A>
	45	<b class="navlabel">Up:</b>
	46	<a class="sectref" rel="parent" href="newTypes.html">10. Object Implementation Support</A>
	47	<b class="navlabel">Next:</b>
	48	<a class="sectref" rel="next" href="reporting-bugs.html">A. Reporting Bugs</A>
	49	</div>
	50	<hr /></div>
	51	</DIV>
	52	<!--End of Navigation Panel-->
	53
	54	<H1><A NAME="SECTION0012900000000000000000"></A><A NAME="supporting-cycle-detection"></A>
	55	<BR>
	56	10.9 Supporting Cyclic Garbage Collection
	57
	58	</H1>
	59
	60	<P>
	61	Python's support for detecting and collecting garbage which involves
	62	circular references requires support from object types which are
	63	``containers'' for other objects which may also be containers. Types
	64	which do not store references to other objects, or which only store
65	references to atomic types (such as numbers or strings), do not need
66	to provide any explicit support for garbage collection.
67
68	<P>
69	An example showing the use of these interfaces can be found in
70	``<a class="ulink" href="../ext/example-cycle-support.html"
71	>Supporting the Cycle
72	Collector</a>'' in
73	<em class="citetitle"><a
74	href="../ext/ext.html"
75	title="Extending and Embedding the Python
76	Interpreter"
77	>Extending and Embedding the Python
78	Interpreter</a></em>.
79
80	<P>
81	To create a container type, the <tt class="member">tp_flags</tt> field of the type
82	object must include the <tt class="constant">Py_TPFLAGS_HAVE_GC</tt> and provide an
83	implementation of the <tt class="member">tp_traverse</tt> handler. If instances of the
84	type are mutable, a <tt class="member">tp_clear</tt> implementation must also be
85	provided.
86
87	<P>
88	<dl><dt><b><tt id='l2h-1015' xml:id='l2h-1015'>Py_TPFLAGS_HAVE_GC</tt></b></dt>
89	<dd>
90	Objects with a type with this flag set must conform with the rules
91	documented here. For convenience these objects will be referred to
92	as container objects.
93	</dd></dl>
94
95	<P>
96	Constructors for container types must conform to two rules:
97
98	<P>
99
100	<OL>
101	<LI>The memory for the object must be allocated using
102	<tt class="cfunction">PyObject_GC_New()</tt> or <tt class="cfunction">PyObject_GC_VarNew()</tt>.
103
104	<P>
105	</LI>
106	<LI>Once all the fields which may contain references to other
107	containers are initialized, it must call
108	<tt class="cfunction">PyObject_GC_Track()</tt>.
109	</LI>
110	</OL>
111
112	<P>
113	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr><var>TYPE</var>* <b><tt id='l2h-1016' xml:id='l2h-1016' class="cfunction">PyObject_GC_New</tt></b>(</nobr></td><td>TYPE, PyTypeObject *<var>type</var>)</td></tr></table></dt>
114	<dd>
115	Analogous to <tt class="cfunction">PyObject_New()</tt> but for container objects with
116	the <tt class="constant">Py_TPFLAGS_HAVE_GC</tt> flag set.
117	</dd></dl>
118
119	<P>
120	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr><var>TYPE</var>* <b><tt id='l2h-1017' xml:id='l2h-1017' class="cfunction">PyObject_GC_NewVar</tt></b>(</nobr></td><td>TYPE, PyTypeObject *<var>type</var>,
121	int <var>size</var>)</td></tr></table></dt>
122	<dd>
123	Analogous to <tt class="cfunction">PyObject_NewVar()</tt> but for container objects
124	with the <tt class="constant">Py_TPFLAGS_HAVE_GC</tt> flag set.
125	</dd></dl>
126
127	<P>
128	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyVarObject * <b><tt id='l2h-1018' xml:id='l2h-1018' class="cfunction">PyObject_GC_Resize</tt></b>(</nobr></td><td>PyVarObject *<var>op</var>, <var>int</var>)</td></tr></table></dt>
129	<dd>
130	Resize an object allocated by <tt class="cfunction">PyObject_NewVar()</tt>. Returns
131	the resized object or <tt class="constant">NULL</tt> on failure.
132	</dd></dl>
133
134	<P>
135	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-1019' xml:id='l2h-1019' class="cfunction">PyObject_GC_Track</tt></b>(</nobr></td><td>PyObject *<var>op</var>)</td></tr></table></dt>
136	<dd>
137	Adds the object <var>op</var> to the set of container objects tracked by
138	the collector. The collector can run at unexpected times so objects
139	must be valid while being tracked. This should be called once all
140	the fields followed by the <tt class="member">tp_traverse</tt> handler become valid,
141	usually near the end of the constructor.
142	</dd></dl>
143
144	<P>
145	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-1020' xml:id='l2h-1020' class="cfunction">_PyObject_GC_TRACK</tt></b>(</nobr></td><td>PyObject *<var>op</var>)</td></tr></table></dt>
146	<dd>
147	A macro version of <tt class="cfunction">PyObject_GC_Track()</tt>. It should not be
148	used for extension modules.
149	</dd></dl>
150
151	<P>
152	Similarly, the deallocator for the object must conform to a similar
153	pair of rules:
154
155	<P>
156
157	<OL>
158	<LI>Before fields which refer to other containers are invalidated,
159	<tt class="cfunction">PyObject_GC_UnTrack()</tt> must be called.
160
161	<P>
162	</LI>
163	<LI>The object's memory must be deallocated using
164	<tt class="cfunction">PyObject_GC_Del()</tt>.
165	</LI>
166	</OL>
167
168	<P>
169	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-1021' xml:id='l2h-1021' class="cfunction">PyObject_GC_Del</tt></b>(</nobr></td><td>PyObject *<var>op</var>)</td></tr></table></dt>
170	<dd>
171	Releases memory allocated to an object using
172	<tt class="cfunction">PyObject_GC_New()</tt> or <tt class="cfunction">PyObject_GC_NewVar()</tt>.
173	</dd></dl>
174
175	<P>
176	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-1022' xml:id='l2h-1022' class="cfunction">PyObject_GC_UnTrack</tt></b>(</nobr></td><td>PyObject *<var>op</var>)</td></tr></table></dt>
177	<dd>
178	Remove the object <var>op</var> from the set of container objects tracked
179	by the collector. Note that <tt class="cfunction">PyObject_GC_Track()</tt> can be
180	called again on this object to add it back to the set of tracked
181	objects. The deallocator (<tt class="member">tp_dealloc</tt> handler) should call
182	this for the object before any of the fields used by the
183	<tt class="member">tp_traverse</tt> handler become invalid.
184	</dd></dl>
185
186	<P>
187	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-1023' xml:id='l2h-1023' class="cfunction">_PyObject_GC_UNTRACK</tt></b>(</nobr></td><td>PyObject *<var>op</var>)</td></tr></table></dt>
188	<dd>
189	A macro version of <tt class="cfunction">PyObject_GC_UnTrack()</tt>. It should not be
190	used for extension modules.
191	</dd></dl>
192
193	<P>
194	The <tt class="member">tp_traverse</tt> handler accepts a function parameter of this
195	type:
196
197	<P>
198	<dl><dt><b><tt class="ctype"><a id='l2h-1024' xml:id='l2h-1024'>int (visitproc)(PyObject object, void *arg)</a></tt></b></dt>
199	<dd>
200	Type of the visitor function passed to the <tt class="member">tp_traverse</tt>
201	handler. The function should be called with an object to traverse
202	as <var>object</var> and the third parameter to the <tt class="member">tp_traverse</tt>
203	handler as <var>arg</var>. The Python core uses several visitor functions
204	to implement cyclic garbage detection; it's not expected that users will
205	need to write their own visitor functions.
206	</dl>
207
208	<P>
209	The <tt class="member">tp_traverse</tt> handler must have the following type:
210
211	<P>
212	<dl><dt><b><tt class="ctype"><a id='l2h-1025' xml:id='l2h-1025'>int (traverseproc)(PyObject self,
213	visitproc visit, void *arg)</a></tt></b></dt>
214	<dd>
215	Traversal function for a container object. Implementations must
216	call the <var>visit</var> function for each object directly contained by
217	<var>self</var>, with the parameters to <var>visit</var> being the contained
218	object and the <var>arg</var> value passed to the handler. The <var>visit</var>
219	function must not be called with a <tt class="constant">NULL</tt> object argument. If
220	<var>visit</var> returns a non-zero value
221	that value should be returned immediately.
222	</dl>
223
224	<P>
225	To simplify writing <tt class="member">tp_traverse</tt> handlers, a
226	<tt class="cfunction">Py_VISIT()</tt> macro is provided. In order to use this macro,
227	the <tt class="member">tp_traverse</tt> implementation must name its arguments
228	exactly <var>visit</var> and <var>arg</var>:
229
230	<P>
231	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-1026' xml:id='l2h-1026' class="cfunction">Py_VISIT</tt></b>(</nobr></td><td>PyObject *<var>o</var>)</td></tr></table></dt>
232	<dd>
233	Call the <var>visit</var> callback, with arguments <var>o</var> and <var>arg</var>.
234	If <var>visit</var> returns a non-zero value, then return it. Using this
235	macro, <tt class="member">tp_traverse</tt> handlers look like:
236
237	<P>
238	<div class="verbatim"><pre>
239	static int
240	my_traverse(Noddy self, visitproc visit, void arg)
241	{
242	Py_VISIT(self->foo);
243	Py_VISIT(self->bar);
244	return 0;
245	}
246	</pre></div>
247
248	<P>
249
250	<span class="versionnote">New in version 2.4.</span>
251
252	</dd></dl>
253
254	<P>
255	The <tt class="member">tp_clear</tt> handler must be of the <tt class="ctype">inquiry</tt> type, or
256	<tt class="constant">NULL</tt> if the object is immutable.
257
258	<P>
259	<dl><dt><b><tt class="ctype"><a id='l2h-1027' xml:id='l2h-1027'>int (inquiry)(PyObject self)</a></tt></b></dt>
260	<dd>
261	Drop references that may have created reference cycles. Immutable
262	objects do not have to define this method since they can never
263	directly create reference cycles. Note that the object must still
264	be valid after calling this method (don't just call
265	<tt class="cfunction">Py_DECREF()</tt> on a reference). The collector will call
266	this method if it detects that this object is involved in a
267	reference cycle.
268	</dl>
269
270	<P>
271
272	<DIV CLASS="navigation">
273	<div class='online-navigation'>
274	<p></p><hr />
275	<table align="center" width="100%" cellpadding="0" cellspacing="2">
276	<tr>
277	<td class='online-navigation'><a rel="prev" title="10.8 Supporting the Iterator"
278	href="supporting-iteration.html"><img src='../icons/previous.png'
279	border='0' height='32' alt='Previous Page' width='32' /></A></td>
280	<td class='online-navigation'><a rel="parent" title="10. Object Implementation Support"
281	href="newTypes.html"><img src='../icons/up.png'
282	border='0' height='32' alt='Up One Level' width='32' /></A></td>
283	<td class='online-navigation'><a rel="next" title="A. Reporting Bugs"
284	href="reporting-bugs.html"><img src='../icons/next.png'
285	border='0' height='32' alt='Next Page' width='32' /></A></td>
286	<td align="center" width="100%">Python/C API Reference Manual</td>
287	<td class='online-navigation'><a rel="contents" title="Table of Contents"
288	href="contents.html"><img src='../icons/contents.png'
289	border='0' height='32' alt='Contents' width='32' /></A></td>
290	<td class='online-navigation'><img src='../icons/blank.png'
291	border='0' height='32' alt='' width='32' /></td>
292	<td class='online-navigation'><a rel="index" title="Index"
293	href="genindex.html"><img src='../icons/index.png'
294	border='0' height='32' alt='Index' width='32' /></A></td>
295	</tr></table>
296	<div class='online-navigation'>
297	<b class="navlabel">Previous:</b>
298	<a class="sectref" rel="prev" href="supporting-iteration.html">10.8 Supporting the Iterator</A>
299	<b class="navlabel">Up:</b>
300	<a class="sectref" rel="parent" href="newTypes.html">10. Object Implementation Support</A>
301	<b class="navlabel">Next:</b>
302	<a class="sectref" rel="next" href="reporting-bugs.html">A. Reporting Bugs</A>
303	</div>
304	</div>
305	<hr />
306	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
307	</DIV>
308	<!--End of Navigation Panel-->
309	<ADDRESS>
310	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
311	</ADDRESS>
312	</BODY>
313	</HTML>