[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / python / lib / module-gc.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.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="lib.html" title='Python Library Reference' />
<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="next" href="module-weakref.html" />
<link rel="prev" href="module-sys.html" />
<link rel="parent" href="python.html" />
<link rel="next" href="module-weakref.html" />
<meta name='aesop' content='information' />
<title>3.2 gc -- Garbage Collector interface</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="3.1 sys  "
  href="module-sys.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="3. Python Runtime Services"
  href="python.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="3.3 weakref  "
  href="module-weakref.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</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'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></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="module-sys.html">3.1 sys  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="python.html">3. Python Runtime Services</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-weakref.html">3.3 weakref  </A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION005200000000000000000">
3.2 <tt class="module">gc</tt> --
         Garbage Collector interface</A>
</H1>

<P>
<A NAME="module-gc"></A>

<P>
This module provides an interface to the optional garbage collector.  It
provides the ability to disable the collector, tune the collection
frequency, and set debugging options.  It also provides access to
unreachable objects that the collector found but cannot free.  Since the
collector supplements the reference counting already used in Python, you
can disable the collector if you are sure your program does not create
reference cycles.  Automatic collection can be disabled by calling
<code>gc.disable()</code>.  To debug a leaking program call
<code>gc.set_debug(gc.DEBUG_LEAK)</code>. Notice that this includes 
<code>gc.DEBUG_SAVEALL</code>, causing garbage-collected objects to be
saved in gc.garbage for inspection.

<P>
The <tt class="module">gc</tt> module provides the following functions:

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-399' xml:id='l2h-399' class="function">enable</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Enable automatic garbage collection.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-400' xml:id='l2h-400' class="function">disable</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Disable automatic garbage collection.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-401' xml:id='l2h-401' class="function">isenabled</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Returns true if automatic collection is enabled.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-402' xml:id='l2h-402' class="function">collect</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Run a full collection.  All generations are examined and the
number of unreachable objects found is returned.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-403' xml:id='l2h-403' class="function">set_debug</tt></b>(</nobr></td>
  <td><var>flags</var>)</td></tr></table></dt>
<dd>
Set the garbage collection debugging flags.
Debugging information will be written to <code>sys.stderr</code>.  See below
for a list of debugging flags which can be combined using bit
operations to control debugging.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-404' xml:id='l2h-404' class="function">get_debug</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the debugging flags currently set.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-405' xml:id='l2h-405' class="function">get_objects</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Returns a list of all objects tracked by the collector, excluding the
list returned.

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

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-406' xml:id='l2h-406' class="function">set_threshold</tt></b>(</nobr></td>
  <td><var>threshold0</var><big>[</big><var>,
                                threshold1</var><big>[</big><var>, threshold2</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Set the garbage collection thresholds (the collection frequency).
Setting <var>threshold0</var> to zero disables collection.

<P>
The GC classifies objects into three generations depending on how many
collection sweeps they have survived.  New objects are placed in the
youngest generation (generation <code>0</code>).  If an object survives a
collection it is moved into the next older generation.  Since
generation <code>2</code> is the oldest generation, objects in that
generation remain there after a collection.  In order to decide when
to run, the collector keeps track of the number object allocations and
deallocations since the last collection.  When the number of
allocations minus the number of deallocations exceeds
<var>threshold0</var>, collection starts.  Initially only generation
<code>0</code> is examined.  If generation <code>0</code> has been examined more
than <var>threshold1</var> times since generation <code>1</code> has been
examined, then generation <code>1</code> is examined as well.  Similarly,
<var>threshold2</var> controls the number of collections of generation
<code>1</code> before collecting generation <code>2</code>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-407' xml:id='l2h-407' class="function">get_threshold</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the current collection thresholds as a tuple of
<code>(<var>threshold0</var>, <var>threshold1</var>, <var>threshold2</var>)</code>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-408' xml:id='l2h-408' class="function">get_referrers</tt></b>(</nobr></td>
  <td><var>*objs</var>)</td></tr></table></dt>
<dd>
Return the list of objects that directly refer to any of objs. This
function will only locate those containers which support garbage
collection; extension types which do refer to other objects but do not
support garbage collection will not be found.

<P>
Note that objects which have already been dereferenced, but which live
in cycles and have not yet been collected by the garbage collector can
be listed among the resulting referrers.  To get only currently live
objects, call <tt class="function">collect()</tt> before calling
<tt class="function">get_referrers()</tt>.

<P>
Care must be taken when using objects returned by
<tt class="function">get_referrers()</tt> because some of them could still be under
construction and hence in a temporarily invalid state. Avoid using
<tt class="function">get_referrers()</tt> for any purpose other than debugging.

<P>

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

</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-409' xml:id='l2h-409' class="function">get_referents</tt></b>(</nobr></td>
  <td><var>*objs</var>)</td></tr></table></dt>
<dd>
Return a list of objects directly referred to by any of the arguments.
The referents returned are those objects visited by the arguments'
C-level <tt class="member">tp_traverse</tt> methods (if any), and may not be all
objects actually directly reachable.  <tt class="member">tp_traverse</tt> methods
are supported only by objects that support garbage collection, and are
only required to visit objects that may be involved in a cycle.  So,
for example, if an integer is directly reachable from an argument, that
integer object may or may not appear in the result list.

<P>

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

</dl>

<P>
The following variable is provided for read-only access (you can
mutate its value but should not rebind it):

<P>
<dl><dt><b><tt id='l2h-410' xml:id='l2h-410'>garbage</tt></b></dt>
<dd>
A list of objects which the collector found to be unreachable
but could not be freed (uncollectable objects).  By default, this list
contains only objects with <tt class="method">__del__()</tt> methods.<A NAME="tex2html13"
  HREF="#foot5795"><SUP>3.1</SUP></A>Objects that have
<tt class="method">__del__()</tt> methods and are part of a reference cycle cause
the entire reference cycle to be uncollectable, including objects
not necessarily in the cycle but reachable only from it.  Python doesn't
collect such cycles automatically because, in general, it isn't possible
for Python to guess a safe order in which to run the <tt class="method">__del__()</tt>
methods.  If you know a safe order, you can force the issue by examining
the <var>garbage</var> list, and explicitly breaking cycles due to your
objects within the list.  Note that these objects are kept alive even
so by virtue of being in the <var>garbage</var> list, so they should be
removed from <var>garbage</var> too.  For example, after breaking cycles, do
<code>del gc.garbage[:]</code> to empty the list.  It's generally better
to avoid the issue by not creating cycles containing objects with
<tt class="method">__del__()</tt> methods, and <var>garbage</var> can be examined in that
case to verify that no such cycles are being created.

<P>
If <tt class="constant">DEBUG_SAVEALL</tt> is set, then all unreachable objects will
be added to this list rather than freed.
</dd></dl>

<P>
The following constants are provided for use with
<tt class="function">set_debug()</tt>:

<P>
<dl><dt><b><tt id='l2h-411' xml:id='l2h-411'>DEBUG_STATS</tt></b></dt>
<dd>
Print statistics during collection.  This information can
be useful when tuning the collection frequency.
</dd></dl>

<P>
<dl><dt><b><tt id='l2h-412' xml:id='l2h-412'>DEBUG_COLLECTABLE</tt></b></dt>
<dd>
Print information on collectable objects found.
</dd></dl>

<P>
<dl><dt><b><tt id='l2h-413' xml:id='l2h-413'>DEBUG_UNCOLLECTABLE</tt></b></dt>
<dd>
Print information of uncollectable objects found (objects which are
not reachable but cannot be freed by the collector).  These objects
will be added to the <code>garbage</code> list.
</dd></dl>

<P>
<dl><dt><b><tt id='l2h-414' xml:id='l2h-414'>DEBUG_INSTANCES</tt></b></dt>
<dd>
When <tt class="constant">DEBUG_COLLECTABLE</tt> or <tt class="constant">DEBUG_UNCOLLECTABLE</tt> is
set, print information about instance objects found.
</dd></dl>

<P>
<dl><dt><b><tt id='l2h-415' xml:id='l2h-415'>DEBUG_OBJECTS</tt></b></dt>
<dd>
When <tt class="constant">DEBUG_COLLECTABLE</tt> or <tt class="constant">DEBUG_UNCOLLECTABLE</tt> is
set, print information about objects other than instance objects found.
</dd></dl>

<P>
<dl><dt><b><tt id='l2h-416' xml:id='l2h-416'>DEBUG_SAVEALL</tt></b></dt>
<dd>
When set, all unreachable objects found will be appended to
<var>garbage</var> rather than being freed.  This can be useful for debugging
a leaking program.
</dd></dl>

<P>
<dl><dt><b><tt id='l2h-417' xml:id='l2h-417'>DEBUG_LEAK</tt></b></dt>
<dd>
The debugging flags necessary for the collector to print
information about a leaking program (equal to <code>DEBUG_COLLECTABLE |
DEBUG_UNCOLLECTABLE | DEBUG_INSTANCES | DEBUG_OBJECTS | DEBUG_SAVEALL</code>).
</dd></dl>
<BR><HR><H4>Footnotes</H4>
<DL>
<DT><A NAME="foot5795">... methods.</A><A
 href="module-gc.html#tex2html13"><SUP>3.1</SUP></A></DT>
<DD>Prior to
  Python 2.2, the list contained all instance objects in unreachable
  cycles,  not only those with <tt class="method">__del__()</tt> methods.

</DD>
</DL>
<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="3.1 sys  "
  href="module-sys.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="3. Python Runtime Services"
  href="python.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="3.3 weakref  "
  href="module-weakref.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</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'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></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="module-sys.html">3.1 sys  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="python.html">3. Python Runtime Services</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-weakref.html">3.3 weakref  </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="lib.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="lib.html" title='Python Library Reference' />
	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="next" href="module-weakref.html" />
	13	<link rel="prev" href="module-sys.html" />
	14	<link rel="parent" href="python.html" />
	15	<link rel="next" href="module-weakref.html" />
	16	<meta name='aesop' content='information' />
	17	<title>3.2 gc -- Garbage Collector interface</title>
	18	</head>
	19	<body>
	20	<DIV CLASS="navigation">
	21	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	22	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	23	<tr>
	24	<td class='online-navigation'><a rel="prev" title="3.1 sys "
	25	href="module-sys.html"><img src='../icons/previous.png'
	26	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	27	<td class='online-navigation'><a rel="parent" title="3. Python Runtime Services"
	28	href="python.html"><img src='../icons/up.png'
	29	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	30	<td class='online-navigation'><a rel="next" title="3.3 weakref "
	31	href="module-weakref.html"><img src='../icons/next.png'
	32	border='0' height='32' alt='Next Page' width='32' /></A></td>
	33	<td align="center" width="100%">Python Library Reference</td>
	34	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	35	href="contents.html"><img src='../icons/contents.png'
	36	border='0' height='32' alt='Contents' width='32' /></A></td>
	37	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
	38	border='0' height='32' alt='Module Index' width='32' /></a></td>
	39	<td class='online-navigation'><a rel="index" title="Index"
	40	href="genindex.html"><img src='../icons/index.png'
	41	border='0' height='32' alt='Index' width='32' /></A></td>
	42	</tr></table>
	43	<div class='online-navigation'>
	44	<b class="navlabel">Previous:</b>
	45	<a class="sectref" rel="prev" href="module-sys.html">3.1 sys </A>
	46	<b class="navlabel">Up:</b>
	47	<a class="sectref" rel="parent" href="python.html">3. Python Runtime Services</A>
	48	<b class="navlabel">Next:</b>
	49	<a class="sectref" rel="next" href="module-weakref.html">3.3 weakref </A>
	50	</div>
	51	<hr /></div>
	52	</DIV>
	53	<!--End of Navigation Panel-->
	54
	55	<H1><A NAME="SECTION005200000000000000000">
	56	3.2 <tt class="module">gc</tt> --
	57	Garbage Collector interface</A>
	58	</H1>
	59
	60	<P>
	61	<A NAME="module-gc"></A>
	62
	63	<P>
	64	This module provides an interface to the optional garbage collector. It
65	provides the ability to disable the collector, tune the collection
66	frequency, and set debugging options. It also provides access to
67	unreachable objects that the collector found but cannot free. Since the
68	collector supplements the reference counting already used in Python, you
69	can disable the collector if you are sure your program does not create
70	reference cycles. Automatic collection can be disabled by calling
71	<code>gc.disable()</code>. To debug a leaking program call
72	<code>gc.set_debug(gc.DEBUG_LEAK)</code>. Notice that this includes
73	<code>gc.DEBUG_SAVEALL</code>, causing garbage-collected objects to be
74	saved in gc.garbage for inspection.
75
76	<P>
77	The <tt class="module">gc</tt> module provides the following functions:
78
79	<P>
80	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
81	<td><nobr><b><tt id='l2h-399' xml:id='l2h-399' class="function">enable</tt></b>(</nobr></td>
82	<td><var></var>)</td></tr></table></dt>
83	<dd>
84	Enable automatic garbage collection.
85	</dl>
86
87	<P>
88	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
89	<td><nobr><b><tt id='l2h-400' xml:id='l2h-400' class="function">disable</tt></b>(</nobr></td>
90	<td><var></var>)</td></tr></table></dt>
91	<dd>
92	Disable automatic garbage collection.
93	</dl>
94
95	<P>
96	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
97	<td><nobr><b><tt id='l2h-401' xml:id='l2h-401' class="function">isenabled</tt></b>(</nobr></td>
98	<td><var></var>)</td></tr></table></dt>
99	<dd>
100	Returns true if automatic collection is enabled.
101	</dl>
102
103	<P>
104	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
105	<td><nobr><b><tt id='l2h-402' xml:id='l2h-402' class="function">collect</tt></b>(</nobr></td>
106	<td><var></var>)</td></tr></table></dt>
107	<dd>
108	Run a full collection. All generations are examined and the
109	number of unreachable objects found is returned.
110	</dl>
111
112	<P>
113	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
114	<td><nobr><b><tt id='l2h-403' xml:id='l2h-403' class="function">set_debug</tt></b>(</nobr></td>
115	<td><var>flags</var>)</td></tr></table></dt>
116	<dd>
117	Set the garbage collection debugging flags.
118	Debugging information will be written to <code>sys.stderr</code>. See below
119	for a list of debugging flags which can be combined using bit
120	operations to control debugging.
121	</dl>
122
123	<P>
124	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
125	<td><nobr><b><tt id='l2h-404' xml:id='l2h-404' class="function">get_debug</tt></b>(</nobr></td>
126	<td><var></var>)</td></tr></table></dt>
127	<dd>
128	Return the debugging flags currently set.
129	</dl>
130
131	<P>
132	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
133	<td><nobr><b><tt id='l2h-405' xml:id='l2h-405' class="function">get_objects</tt></b>(</nobr></td>
134	<td><var></var>)</td></tr></table></dt>
135	<dd>
136	Returns a list of all objects tracked by the collector, excluding the
137	list returned.
138
139	<span class="versionnote">New in version 2.2.</span>
140
141	</dl>
142
143	<P>
144	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
145	<td><nobr><b><tt id='l2h-406' xml:id='l2h-406' class="function">set_threshold</tt></b>(</nobr></td>
146	<td><var>threshold0</var><big>[</big><var>,
147	threshold1</var><big>[</big><var>, threshold2</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
148	<dd>
149	Set the garbage collection thresholds (the collection frequency).
150	Setting <var>threshold0</var> to zero disables collection.
151
152	<P>
153	The GC classifies objects into three generations depending on how many
154	collection sweeps they have survived. New objects are placed in the
155	youngest generation (generation <code>0</code>). If an object survives a
156	collection it is moved into the next older generation. Since
157	generation <code>2</code> is the oldest generation, objects in that
158	generation remain there after a collection. In order to decide when
159	to run, the collector keeps track of the number object allocations and
160	deallocations since the last collection. When the number of
161	allocations minus the number of deallocations exceeds
162	<var>threshold0</var>, collection starts. Initially only generation
163	<code>0</code> is examined. If generation <code>0</code> has been examined more
164	than <var>threshold1</var> times since generation <code>1</code> has been
165	examined, then generation <code>1</code> is examined as well. Similarly,
166	<var>threshold2</var> controls the number of collections of generation
167	<code>1</code> before collecting generation <code>2</code>.
168	</dl>
169
170	<P>
171	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
172	<td><nobr><b><tt id='l2h-407' xml:id='l2h-407' class="function">get_threshold</tt></b>(</nobr></td>
173	<td><var></var>)</td></tr></table></dt>
174	<dd>
175	Return the current collection thresholds as a tuple of
176	<code>(<var>threshold0</var>, <var>threshold1</var>, <var>threshold2</var>)</code>.
177	</dl>
178
179	<P>
180	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
181	<td><nobr><b><tt id='l2h-408' xml:id='l2h-408' class="function">get_referrers</tt></b>(</nobr></td>
182	<td><var>*objs</var>)</td></tr></table></dt>
183	<dd>
184	Return the list of objects that directly refer to any of objs. This
185	function will only locate those containers which support garbage
186	collection; extension types which do refer to other objects but do not
187	support garbage collection will not be found.
188
189	<P>
190	Note that objects which have already been dereferenced, but which live
191	in cycles and have not yet been collected by the garbage collector can
192	be listed among the resulting referrers. To get only currently live
193	objects, call <tt class="function">collect()</tt> before calling
194	<tt class="function">get_referrers()</tt>.
195
196	<P>
197	Care must be taken when using objects returned by
198	<tt class="function">get_referrers()</tt> because some of them could still be under
199	construction and hence in a temporarily invalid state. Avoid using
200	<tt class="function">get_referrers()</tt> for any purpose other than debugging.
201
202	<P>
203
204	<span class="versionnote">New in version 2.2.</span>
205
206	</dl>
207
208	<P>
209	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
210	<td><nobr><b><tt id='l2h-409' xml:id='l2h-409' class="function">get_referents</tt></b>(</nobr></td>
211	<td><var>*objs</var>)</td></tr></table></dt>
212	<dd>
213	Return a list of objects directly referred to by any of the arguments.
214	The referents returned are those objects visited by the arguments'
215	C-level <tt class="member">tp_traverse</tt> methods (if any), and may not be all
216	objects actually directly reachable. <tt class="member">tp_traverse</tt> methods
217	are supported only by objects that support garbage collection, and are
218	only required to visit objects that may be involved in a cycle. So,
219	for example, if an integer is directly reachable from an argument, that
220	integer object may or may not appear in the result list.
221
222	<P>
223
224	<span class="versionnote">New in version 2.3.</span>
225
226	</dl>
227
228	<P>
229	The following variable is provided for read-only access (you can
230	mutate its value but should not rebind it):
231
232	<P>
233	<dl><dt><b><tt id='l2h-410' xml:id='l2h-410'>garbage</tt></b></dt>
234	<dd>
235	A list of objects which the collector found to be unreachable
236	but could not be freed (uncollectable objects). By default, this list
237	contains only objects with <tt class="method">__del__()</tt> methods.<A NAME="tex2html13"
238	HREF="#foot5795"><SUP>3.1</SUP></A>Objects that have
239	<tt class="method">__del__()</tt> methods and are part of a reference cycle cause
240	the entire reference cycle to be uncollectable, including objects
241	not necessarily in the cycle but reachable only from it. Python doesn't
242	collect such cycles automatically because, in general, it isn't possible
243	for Python to guess a safe order in which to run the <tt class="method">__del__()</tt>
244	methods. If you know a safe order, you can force the issue by examining
245	the <var>garbage</var> list, and explicitly breaking cycles due to your
246	objects within the list. Note that these objects are kept alive even
247	so by virtue of being in the <var>garbage</var> list, so they should be
248	removed from <var>garbage</var> too. For example, after breaking cycles, do
249	<code>del gc.garbage[:]</code> to empty the list. It's generally better
250	to avoid the issue by not creating cycles containing objects with
251	<tt class="method">__del__()</tt> methods, and <var>garbage</var> can be examined in that
252	case to verify that no such cycles are being created.
253
254	<P>
255	If <tt class="constant">DEBUG_SAVEALL</tt> is set, then all unreachable objects will
256	be added to this list rather than freed.
257	</dd></dl>
258
259	<P>
260	The following constants are provided for use with
261	<tt class="function">set_debug()</tt>:
262
263	<P>
264	<dl><dt><b><tt id='l2h-411' xml:id='l2h-411'>DEBUG_STATS</tt></b></dt>
265	<dd>
266	Print statistics during collection. This information can
267	be useful when tuning the collection frequency.
268	</dd></dl>
269
270	<P>
271	<dl><dt><b><tt id='l2h-412' xml:id='l2h-412'>DEBUG_COLLECTABLE</tt></b></dt>
272	<dd>
273	Print information on collectable objects found.
274	</dd></dl>
275
276	<P>
277	<dl><dt><b><tt id='l2h-413' xml:id='l2h-413'>DEBUG_UNCOLLECTABLE</tt></b></dt>
278	<dd>
279	Print information of uncollectable objects found (objects which are
280	not reachable but cannot be freed by the collector). These objects
281	will be added to the <code>garbage</code> list.
282	</dd></dl>
283
284	<P>
285	<dl><dt><b><tt id='l2h-414' xml:id='l2h-414'>DEBUG_INSTANCES</tt></b></dt>
286	<dd>
287	When <tt class="constant">DEBUG_COLLECTABLE</tt> or <tt class="constant">DEBUG_UNCOLLECTABLE</tt> is
288	set, print information about instance objects found.
289	</dd></dl>
290
291	<P>
292	<dl><dt><b><tt id='l2h-415' xml:id='l2h-415'>DEBUG_OBJECTS</tt></b></dt>
293	<dd>
294	When <tt class="constant">DEBUG_COLLECTABLE</tt> or <tt class="constant">DEBUG_UNCOLLECTABLE</tt> is
295	set, print information about objects other than instance objects found.
296	</dd></dl>
297
298	<P>
299	<dl><dt><b><tt id='l2h-416' xml:id='l2h-416'>DEBUG_SAVEALL</tt></b></dt>
300	<dd>
301	When set, all unreachable objects found will be appended to
302	<var>garbage</var> rather than being freed. This can be useful for debugging
303	a leaking program.
304	</dd></dl>
305
306	<P>
307	<dl><dt><b><tt id='l2h-417' xml:id='l2h-417'>DEBUG_LEAK</tt></b></dt>
308	<dd>
309	The debugging flags necessary for the collector to print
310	information about a leaking program (equal to <code>DEBUG_COLLECTABLE \|
311	DEBUG_UNCOLLECTABLE \| DEBUG_INSTANCES \| DEBUG_OBJECTS \| DEBUG_SAVEALL</code>).
312	</dd></dl>
313	<BR><HR><H4>Footnotes</H4>
314	<DL>
315	<DT><A NAME="foot5795">... methods.</A><A
316	href="module-gc.html#tex2html13"><SUP>3.1</SUP></A></DT>
317	<DD>Prior to
318	Python 2.2, the list contained all instance objects in unreachable
319	cycles, not only those with <tt class="method">__del__()</tt> methods.
320
321	</DD>
322	</DL>
323	<DIV CLASS="navigation">
324	<div class='online-navigation'>
325	<p></p><hr />
326	<table align="center" width="100%" cellpadding="0" cellspacing="2">
327	<tr>
328	<td class='online-navigation'><a rel="prev" title="3.1 sys "
329	href="module-sys.html"><img src='../icons/previous.png'
330	border='0' height='32' alt='Previous Page' width='32' /></A></td>
331	<td class='online-navigation'><a rel="parent" title="3. Python Runtime Services"
332	href="python.html"><img src='../icons/up.png'
333	border='0' height='32' alt='Up One Level' width='32' /></A></td>
334	<td class='online-navigation'><a rel="next" title="3.3 weakref "
335	href="module-weakref.html"><img src='../icons/next.png'
336	border='0' height='32' alt='Next Page' width='32' /></A></td>
337	<td align="center" width="100%">Python Library Reference</td>
338	<td class='online-navigation'><a rel="contents" title="Table of Contents"
339	href="contents.html"><img src='../icons/contents.png'
340	border='0' height='32' alt='Contents' width='32' /></A></td>
341	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
342	border='0' height='32' alt='Module Index' width='32' /></a></td>
343	<td class='online-navigation'><a rel="index" title="Index"
344	href="genindex.html"><img src='../icons/index.png'
345	border='0' height='32' alt='Index' width='32' /></A></td>
346	</tr></table>
347	<div class='online-navigation'>
348	<b class="navlabel">Previous:</b>
349	<a class="sectref" rel="prev" href="module-sys.html">3.1 sys </A>
350	<b class="navlabel">Up:</b>
351	<a class="sectref" rel="parent" href="python.html">3. Python Runtime Services</A>
352	<b class="navlabel">Next:</b>
353	<a class="sectref" rel="next" href="module-weakref.html">3.3 weakref </A>
354	</div>
355	</div>
356	<hr />
357	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
358	</DIV>
359	<!--End of Navigation Panel-->
360	<ADDRESS>
361	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
362	</ADDRESS>
363	</BODY>
364	</HTML>