| 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> |