[OpenSPARC-T2-SAM] / sam-t2 / devtools / v9 / html / python / ext / refcounts.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="ext.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="ext.html" title='Extending and Embedding the Python Interpreter' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="cplusplus.html" />
<link rel="prev" href="buildValue.html" />
<link rel="parent" href="intro.html" />
<link rel="next" href="refcountsInPython.html" />
<meta name='aesop' content='information' />
<title>1.10 Reference Counts
</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="1.9 Building Arbitrary Values"
  href="buildValue.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="1. Extending Python with"
  href="intro.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="1.10.1 Reference Counting in"
  href="refcountsInPython.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Extending and Embedding the Python Interpreter</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'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="buildValue.html">1.9 Building Arbitrary Values</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="intro.html">1. Extending Python with</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="refcountsInPython.html">1.10.1 Reference Counting in</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION0031000000000000000000"></A><A NAME="refcounts"></A>
<BR>
1.10 Reference Counts
         
</H1>

<P>
In languages like C or C++, the programmer is responsible for
dynamic allocation and deallocation of memory on the heap.  In C,
this is done using the functions <tt class="cfunction">malloc()</tt> and
<tt class="cfunction">free()</tt>.  In C++, the operators <tt class="keyword">new</tt> and
<tt class="keyword">delete</tt> are used with essentially the same meaning and
we'll restrict the following discussion to the C case.

<P>
Every block of memory allocated with <tt class="cfunction">malloc()</tt> should
eventually be returned to the pool of available memory by exactly one
call to <tt class="cfunction">free()</tt>.  It is important to call
<tt class="cfunction">free()</tt> at the right time.  If a block's address is
forgotten but <tt class="cfunction">free()</tt> is not called for it, the memory it
occupies cannot be reused until the program terminates.  This is
called a <i class="dfn">memory leak</i>.  On the other hand, if a program calls
<tt class="cfunction">free()</tt> for a block and then continues to use the block, it
creates a conflict with re-use of the block through another
<tt class="cfunction">malloc()</tt> call.  This is called <i class="dfn">using freed memory</i>.
It has the same bad consequences as referencing uninitialized data --
core dumps, wrong results, mysterious crashes.

<P>
Common causes of memory leaks are unusual paths through the code.  For
instance, a function may allocate a block of memory, do some
calculation, and then free the block again.  Now a change in the
requirements for the function may add a test to the calculation that
detects an error condition and can return prematurely from the
function.  It's easy to forget to free the allocated memory block when
taking this premature exit, especially when it is added later to the
code.  Such leaks, once introduced, often go undetected for a long
time: the error exit is taken only in a small fraction of all calls,
and most modern machines have plenty of virtual memory, so the leak
only becomes apparent in a long-running process that uses the leaking
function frequently.  Therefore, it's important to prevent leaks from
happening by having a coding convention or strategy that minimizes
this kind of errors.

<P>
Since Python makes heavy use of <tt class="cfunction">malloc()</tt> and
<tt class="cfunction">free()</tt>, it needs a strategy to avoid memory leaks as well
as the use of freed memory.  The chosen method is called
<i class="dfn">reference counting</i>.  The principle is simple: every object
contains a counter, which is incremented when a reference to the
object is stored somewhere, and which is decremented when a reference
to it is deleted.  When the counter reaches zero, the last reference
to the object has been deleted and the object is freed.

<P>
An alternative strategy is called <i class="dfn">automatic garbage collection</i>.
(Sometimes, reference counting is also referred to as a garbage
collection strategy, hence my use of ``automatic'' to distinguish the
two.)  The big advantage of automatic garbage collection is that the
user doesn't need to call <tt class="cfunction">free()</tt> explicitly.  (Another claimed
advantage is an improvement in speed or memory usage -- this is no
hard fact however.)  The disadvantage is that for C, there is no
truly portable automatic garbage collector, while reference counting
can be implemented portably (as long as the functions <tt class="cfunction">malloc()</tt>
and <tt class="cfunction">free()</tt> are available -- which the C Standard guarantees).
Maybe some day a sufficiently portable automatic garbage collector
will be available for C.  Until then, we'll have to live with
reference counts.

<P>
While Python uses the traditional reference counting implementation,
it also offers a cycle detector that works to detect reference
cycles.  This allows applications to not worry about creating direct
or indirect circular references; these are the weakness of garbage
collection implemented using only reference counting.  Reference
cycles consist of objects which contain (possibly indirect) references
to themselves, so that each object in the cycle has a reference count
which is non-zero.  Typical reference counting implementations are not
able to reclaim the memory belonging to any objects in a reference
cycle, or referenced from the objects in the cycle, even though there
are no further references to the cycle itself.

<P>
The cycle detector is able to detect garbage cycles and can reclaim
them so long as there are no finalizers implemented in Python
(<tt class="method">__del__()</tt> methods).  When there are such finalizers, the
detector exposes the cycles through the <a class="ulink" href="../lib/module-gc.html"
  ><tt class="module">gc</tt>
module</a> (specifically, the <code>garbage</code>
variable in that module).  The <tt class="module">gc</tt> module also exposes a way
to run the detector (the <tt class="function">collect()</tt> function), as well as
configuration interfaces and the ability to disable the detector at
runtime.  The cycle detector is considered an optional component;
though it is included by default, it can be disabled at build time
using the <b class="programopt">--without-cycle-gc</b> option to the
<b class="program">configure</b> script on <span class="Unix">Unix</span> platforms (including Mac OS X)
or by removing the definition of <code>WITH_CYCLE_GC</code> in the
<span class="file">pyconfig.h</span> header on other platforms.  If the cycle detector is
disabled in this way, the <tt class="module">gc</tt> module will not be available.

<P>

<p><br /></p><hr class='online-navigation' />
<div class='online-navigation'>
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>

<UL CLASS="ChildLinks">
<LI><A href="refcountsInPython.html">1.10.1 Reference Counting in Python</a>
<LI><A href="ownershipRules.html">1.10.2 Ownership Rules</a>
<LI><A href="thinIce.html">1.10.3 Thin Ice</a>
<LI><A href="nullPointers.html">1.10.4 NULL Pointers</a>
</ul>
<!--End of Table of Child-Links-->
</div>

<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="1.9 Building Arbitrary Values"
  href="buildValue.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="1. Extending Python with"
  href="intro.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="1.10.1 Reference Counting in"
  href="refcountsInPython.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Extending and Embedding the Python Interpreter</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'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="buildValue.html">1.9 Building Arbitrary Values</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="intro.html">1. Extending Python with</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="refcountsInPython.html">1.10.1 Reference Counting in</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
920dae64 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="ext.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="ext.html" title='Extending and Embedding the Python Interpreter' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	9	<link rel='last' href='about.html' title='About this document...' />
	10	<link rel='help' href='about.html' title='About this document...' />
	11	<link rel="next" href="cplusplus.html" />
	12	<link rel="prev" href="buildValue.html" />
	13	<link rel="parent" href="intro.html" />
	14	<link rel="next" href="refcountsInPython.html" />
	15	<meta name='aesop' content='information' />
	16	<title>1.10 Reference Counts
	17	</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="1.9 Building Arbitrary Values"
	25	href="buildValue.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="1. Extending Python with"
	28	href="intro.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="1.10.1 Reference Counting in"
	31	href="refcountsInPython.html"><img src='../icons/next.png'
	32	border='0' height='32' alt='Next Page' width='32' /></A></td>
	33	<td align="center" width="100%">Extending and Embedding the Python Interpreter</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'><img src='../icons/blank.png'
	38	border='0' height='32' alt='' width='32' /></td>
	39	<td class='online-navigation'><img src='../icons/blank.png'
	40	border='0' height='32' alt='' width='32' /></td>
	41	</tr></table>
	42	<div class='online-navigation'>
	43	<b class="navlabel">Previous:</b>
	44	<a class="sectref" rel="prev" href="buildValue.html">1.9 Building Arbitrary Values</A>
	45	<b class="navlabel">Up:</b>
	46	<a class="sectref" rel="parent" href="intro.html">1. Extending Python with</A>
	47	<b class="navlabel">Next:</b>
	48	<a class="sectref" rel="next" href="refcountsInPython.html">1.10.1 Reference Counting in</A>
	49	</div>
	50	<hr /></div>
	51	</DIV>
	52	<!--End of Navigation Panel-->
	53
	54	<H1><A NAME="SECTION0031000000000000000000"></A><A NAME="refcounts"></A>
	55	<BR>
	56	1.10 Reference Counts
	57
	58	</H1>
	59
	60	<P>
	61	In languages like C or C++, the programmer is responsible for
	62	dynamic allocation and deallocation of memory on the heap. In C,
	63	this is done using the functions <tt class="cfunction">malloc()</tt> and
	64	<tt class="cfunction">free()</tt>. In C++, the operators <tt class="keyword">new</tt> and
65	<tt class="keyword">delete</tt> are used with essentially the same meaning and
66	we'll restrict the following discussion to the C case.
67
68	<P>
69	Every block of memory allocated with <tt class="cfunction">malloc()</tt> should
70	eventually be returned to the pool of available memory by exactly one
71	call to <tt class="cfunction">free()</tt>. It is important to call
72	<tt class="cfunction">free()</tt> at the right time. If a block's address is
73	forgotten but <tt class="cfunction">free()</tt> is not called for it, the memory it
74	occupies cannot be reused until the program terminates. This is
75	called a <i class="dfn">memory leak</i>. On the other hand, if a program calls
76	<tt class="cfunction">free()</tt> for a block and then continues to use the block, it
77	creates a conflict with re-use of the block through another
78	<tt class="cfunction">malloc()</tt> call. This is called <i class="dfn">using freed memory</i>.
79	It has the same bad consequences as referencing uninitialized data --
80	core dumps, wrong results, mysterious crashes.
81
82	<P>
83	Common causes of memory leaks are unusual paths through the code. For
84	instance, a function may allocate a block of memory, do some
85	calculation, and then free the block again. Now a change in the
86	requirements for the function may add a test to the calculation that
87	detects an error condition and can return prematurely from the
88	function. It's easy to forget to free the allocated memory block when
89	taking this premature exit, especially when it is added later to the
90	code. Such leaks, once introduced, often go undetected for a long
91	time: the error exit is taken only in a small fraction of all calls,
92	and most modern machines have plenty of virtual memory, so the leak
93	only becomes apparent in a long-running process that uses the leaking
94	function frequently. Therefore, it's important to prevent leaks from
95	happening by having a coding convention or strategy that minimizes
96	this kind of errors.
97
98	<P>
99	Since Python makes heavy use of <tt class="cfunction">malloc()</tt> and
100	<tt class="cfunction">free()</tt>, it needs a strategy to avoid memory leaks as well
101	as the use of freed memory. The chosen method is called
102	<i class="dfn">reference counting</i>. The principle is simple: every object
103	contains a counter, which is incremented when a reference to the
104	object is stored somewhere, and which is decremented when a reference
105	to it is deleted. When the counter reaches zero, the last reference
106	to the object has been deleted and the object is freed.
107
108	<P>
109	An alternative strategy is called <i class="dfn">automatic garbage collection</i>.
110	(Sometimes, reference counting is also referred to as a garbage
111	collection strategy, hence my use of ``automatic'' to distinguish the
112	two.) The big advantage of automatic garbage collection is that the
113	user doesn't need to call <tt class="cfunction">free()</tt> explicitly. (Another claimed
114	advantage is an improvement in speed or memory usage -- this is no
115	hard fact however.) The disadvantage is that for C, there is no
116	truly portable automatic garbage collector, while reference counting
117	can be implemented portably (as long as the functions <tt class="cfunction">malloc()</tt>
118	and <tt class="cfunction">free()</tt> are available -- which the C Standard guarantees).
119	Maybe some day a sufficiently portable automatic garbage collector
120	will be available for C. Until then, we'll have to live with
121	reference counts.
122
123	<P>
124	While Python uses the traditional reference counting implementation,
125	it also offers a cycle detector that works to detect reference
126	cycles. This allows applications to not worry about creating direct
127	or indirect circular references; these are the weakness of garbage
128	collection implemented using only reference counting. Reference
129	cycles consist of objects which contain (possibly indirect) references
130	to themselves, so that each object in the cycle has a reference count
131	which is non-zero. Typical reference counting implementations are not
132	able to reclaim the memory belonging to any objects in a reference
133	cycle, or referenced from the objects in the cycle, even though there
134	are no further references to the cycle itself.
135
136	<P>
137	The cycle detector is able to detect garbage cycles and can reclaim
138	them so long as there are no finalizers implemented in Python
139	(<tt class="method">__del__()</tt> methods). When there are such finalizers, the
140	detector exposes the cycles through the <a class="ulink" href="../lib/module-gc.html"
141	><tt class="module">gc</tt>
142	module</a> (specifically, the <code>garbage</code>
143	variable in that module). The <tt class="module">gc</tt> module also exposes a way
144	to run the detector (the <tt class="function">collect()</tt> function), as well as
145	configuration interfaces and the ability to disable the detector at
146	runtime. The cycle detector is considered an optional component;
147	though it is included by default, it can be disabled at build time
148	using the <b class="programopt">--without-cycle-gc</b> option to the
149	<b class="program">configure</b> script on <span class="Unix">Unix</span> platforms (including Mac OS X)
150	or by removing the definition of <code>WITH_CYCLE_GC</code> in the
151	<span class="file">pyconfig.h</span> header on other platforms. If the cycle detector is
152	disabled in this way, the <tt class="module">gc</tt> module will not be available.
153
154	<P>
155
156	<p><br /></p><hr class='online-navigation' />
157	<div class='online-navigation'>
158	<!--Table of Child-Links-->
159	<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
160
161	<UL CLASS="ChildLinks">
162	<LI><A href="refcountsInPython.html">1.10.1 Reference Counting in Python</a>
163	<LI><A href="ownershipRules.html">1.10.2 Ownership Rules</a>
164	<LI><A href="thinIce.html">1.10.3 Thin Ice</a>
165	<LI><A href="nullPointers.html">1.10.4 NULL Pointers</a>
166	</ul>
167	<!--End of Table of Child-Links-->
168	</div>
169
170	<DIV CLASS="navigation">
171	<div class='online-navigation'>
172	<p></p><hr />
173	<table align="center" width="100%" cellpadding="0" cellspacing="2">
174	<tr>
175	<td class='online-navigation'><a rel="prev" title="1.9 Building Arbitrary Values"
176	href="buildValue.html"><img src='../icons/previous.png'
177	border='0' height='32' alt='Previous Page' width='32' /></A></td>
178	<td class='online-navigation'><a rel="parent" title="1. Extending Python with"
179	href="intro.html"><img src='../icons/up.png'
180	border='0' height='32' alt='Up One Level' width='32' /></A></td>
181	<td class='online-navigation'><a rel="next" title="1.10.1 Reference Counting in"
182	href="refcountsInPython.html"><img src='../icons/next.png'
183	border='0' height='32' alt='Next Page' width='32' /></A></td>
184	<td align="center" width="100%">Extending and Embedding the Python Interpreter</td>
185	<td class='online-navigation'><a rel="contents" title="Table of Contents"
186	href="contents.html"><img src='../icons/contents.png'
187	border='0' height='32' alt='Contents' width='32' /></A></td>
188	<td class='online-navigation'><img src='../icons/blank.png'
189	border='0' height='32' alt='' width='32' /></td>
190	<td class='online-navigation'><img src='../icons/blank.png'
191	border='0' height='32' alt='' width='32' /></td>
192	</tr></table>
193	<div class='online-navigation'>
194	<b class="navlabel">Previous:</b>
195	<a class="sectref" rel="prev" href="buildValue.html">1.9 Building Arbitrary Values</A>
196	<b class="navlabel">Up:</b>
197	<a class="sectref" rel="parent" href="intro.html">1. Extending Python with</A>
198	<b class="navlabel">Next:</b>
199	<a class="sectref" rel="next" href="refcountsInPython.html">1.10.1 Reference Counting in</A>
200	</div>
201	</div>
202	<hr />
203	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
204	</DIV>
205	<!--End of Navigation Panel-->
206	<ADDRESS>
207	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
208	</ADDRESS>
209	</BODY>
210	</HTML>