projects / OpenSPARC-T2-SAM / blame
? search:
summary | tags | clone url | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Initial commit of OpenSPARC T2 architecture model.
[OpenSPARC-T2-SAM] / sam-t2 / devtools / amd64 / html / python / api / refcounts.html
CommitLineData
920dae64
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="next" href="types.html" />
13<link rel="prev" href="objects.html" />
14<link rel="parent" href="objects.html" />
15<link rel="next" href="refcountDetails.html" />
16<meta name='aesop' content='information' />
17<title>1.2.1 Reference Counts </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.2 Objects, Types and"
25 href="objects.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.2 Objects, Types and"
28 href="objects.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.2.1.1 Reference Count Details"
31 href="refcountDetails.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/C API Reference Manual</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'><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="objects.html">1.2 Objects, Types and</A>
46<b class="navlabel">Up:</b>
47<a class="sectref" rel="parent" href="objects.html">1.2 Objects, Types and</A>
48<b class="navlabel">Next:</b>
49<a class="sectref" rel="next" href="refcountDetails.html">1.2.1.1 Reference Count Details</A>
50</div>
51<hr /></div>
52</DIV>
53<!--End of Navigation Panel-->
54
55<H2><A NAME="SECTION003210000000000000000"></A><A NAME="refcounts"></A>
56<BR>
571.2.1 Reference Counts
58</H2>
59
60<P>
61The reference count is important because today's computers have a
62finite (and often severely limited) memory size; it counts how many
63different places there are that have a reference to an object. Such a
64place could be another object, or a global (or static) C variable, or
65a local variable in some C function. When an object's reference count
66becomes zero, the object is deallocated. If it contains references to
67other objects, their reference count is decremented. Those other
68objects may be deallocated in turn, if this decrement makes their
69reference count become zero, and so on. (There's an obvious problem
70with objects that reference each other here; for now, the solution is
71``don't do that.'')
72
73<P>
74Reference counts are always manipulated explicitly. The normal way is
75to use the macro <tt class="cfunction">Py_INCREF()</tt><a id='l2h-10' xml:id='l2h-10'></a> to
76increment an object's reference count by one, and
77<tt class="cfunction">Py_DECREF()</tt><a id='l2h-11' xml:id='l2h-11'></a> to decrement it by
78one. The <tt class="cfunction">Py_DECREF()</tt> macro is considerably more complex
79than the incref one, since it must check whether the reference count
80becomes zero and then cause the object's deallocator to be called.
81The deallocator is a function pointer contained in the object's type
82structure. The type-specific deallocator takes care of decrementing
83the reference counts for other objects contained in the object if this
84is a compound object type, such as a list, as well as performing any
85additional finalization that's needed. There's no chance that the
86reference count can overflow; at least as many bits are used to hold
87the reference count as there are distinct memory locations in virtual
88memory (assuming <code>sizeof(long) &gt;= sizeof(char*)</code>). Thus, the
89reference count increment is a simple operation.
90
91<P>
92It is not necessary to increment an object's reference count for every
93local variable that contains a pointer to an object. In theory, the
94object's reference count goes up by one when the variable is made to
95point to it and it goes down by one when the variable goes out of
96scope. However, these two cancel each other out, so at the end the
97reference count hasn't changed. The only real reason to use the
98reference count is to prevent the object from being deallocated as
99long as our variable is pointing to it. If we know that there is at
100least one other reference to the object that lives at least as long as
101our variable, there is no need to increment the reference count
102temporarily. An important situation where this arises is in objects
103that are passed as arguments to C functions in an extension module
104that are called from Python; the call mechanism guarantees to hold a
105reference to every argument for the duration of the call.
106
107<P>
108However, a common pitfall is to extract an object from a list and
109hold on to it for a while without incrementing its reference count.
110Some other operation might conceivably remove the object from the
111list, decrementing its reference count and possible deallocating it.
112The real danger is that innocent-looking operations may invoke
113arbitrary Python code which could do this; there is a code path which
114allows control to flow back to the user from a <tt class="cfunction">Py_DECREF()</tt>,
115so almost any operation is potentially dangerous.
116
117<P>
118A safe approach is to always use the generic operations (functions
119whose name begins with "<tt class="samp">PyObject_</tt>", "<tt class="samp">PyNumber_</tt>",
120"<tt class="samp">PySequence_</tt>" or "<tt class="samp">PyMapping_</tt>"). These operations always
121increment the reference count of the object they return. This leaves
122the caller with the responsibility to call
123<tt class="cfunction">Py_DECREF()</tt> when they are done with the result; this soon
124becomes second nature.
125
126<P>
127
128<p><br /></p><hr class='online-navigation' />
129<div class='online-navigation'>
130<!--Table of Child-Links-->
131<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
132
133<UL CLASS="ChildLinks">
134<LI><A href="refcountDetails.html">1.2.1.1 Reference Count Details</a>
135</ul>
136<!--End of Table of Child-Links-->
137</div>
138
139<DIV CLASS="navigation">
140<div class='online-navigation'>
141<p></p><hr />
142<table align="center" width="100%" cellpadding="0" cellspacing="2">
143<tr>
144<td class='online-navigation'><a rel="prev" title="1.2 Objects, Types and"
145 href="objects.html"><img src='../icons/previous.png'
146 border='0' height='32' alt='Previous Page' width='32' /></A></td>
147<td class='online-navigation'><a rel="parent" title="1.2 Objects, Types and"
148 href="objects.html"><img src='../icons/up.png'
149 border='0' height='32' alt='Up One Level' width='32' /></A></td>
150<td class='online-navigation'><a rel="next" title="1.2.1.1 Reference Count Details"
151 href="refcountDetails.html"><img src='../icons/next.png'
152 border='0' height='32' alt='Next Page' width='32' /></A></td>
153<td align="center" width="100%">Python/C API Reference Manual</td>
154<td class='online-navigation'><a rel="contents" title="Table of Contents"
155 href="contents.html"><img src='../icons/contents.png'
156 border='0' height='32' alt='Contents' width='32' /></A></td>
157<td class='online-navigation'><img src='../icons/blank.png'
158 border='0' height='32' alt='' width='32' /></td>
159<td class='online-navigation'><a rel="index" title="Index"
160 href="genindex.html"><img src='../icons/index.png'
161 border='0' height='32' alt='Index' width='32' /></A></td>
162</tr></table>
163<div class='online-navigation'>
164<b class="navlabel">Previous:</b>
165<a class="sectref" rel="prev" href="objects.html">1.2 Objects, Types and</A>
166<b class="navlabel">Up:</b>
167<a class="sectref" rel="parent" href="objects.html">1.2 Objects, Types and</A>
168<b class="navlabel">Next:</b>
169<a class="sectref" rel="next" href="refcountDetails.html">1.2.1.1 Reference Count Details</A>
170</div>
171</div>
172<hr />
173<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
174</DIV>
175<!--End of Navigation Panel-->
176<ADDRESS>
177See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
178</ADDRESS>
179</BODY>
180</HTML>
Full OpenSPARC architecture tarball including simulator, hypervisor, and OBP.