| 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="refcounts.html" /> |
| 13 | <link rel="parent" href="refcounts.html" /> |
| 14 | <link rel="next" href="types.html" /> |
| 15 | <meta name='aesop' content='information' /> |
| 16 | <title>1.2.1.1 Reference Count Details </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="1.2.1 Reference Counts" |
| 24 | href="refcounts.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="1.2.1 Reference Counts" |
| 27 | href="refcounts.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="1.2.2 Types" |
| 30 | href="types.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="refcounts.html">1.2.1 Reference Counts</A> |
| 45 | <b class="navlabel">Up:</b> |
| 46 | <a class="sectref" rel="parent" href="refcounts.html">1.2.1 Reference Counts</A> |
| 47 | <b class="navlabel">Next:</b> |
| 48 | <a class="sectref" rel="next" href="types.html">1.2.2 Types</A> |
| 49 | </div> |
| 50 | <hr /></div> |
| 51 | </DIV> |
| 52 | <!--End of Navigation Panel--> |
| 53 | |
| 54 | <H3><A NAME="SECTION003211000000000000000"></A><A NAME="refcountDetails"></A> |
| 55 | <BR> |
| 56 | 1.2.1.1 Reference Count Details |
| 57 | </H3> |
| 58 | |
| 59 | <P> |
| 60 | The reference count behavior of functions in the Python/C API is best |
| 61 | explained in terms of <em>ownership of references</em>. Ownership |
| 62 | pertains to references, never to objects (objects are not owned: they |
| 63 | are always shared). "Owning a reference" means being responsible for |
| 64 | calling Py_DECREF on it when the reference is no longer needed. |
| 65 | Ownership can also be transferred, meaning that the code that receives |
| 66 | ownership of the reference then becomes responsible for eventually |
| 67 | decref'ing it by calling <tt class="cfunction">Py_DECREF()</tt> or |
| 68 | <tt class="cfunction">Py_XDECREF()</tt> when it's no longer needed -or passing on |
| 69 | this responsibility (usually to its caller). |
| 70 | When a function passes ownership of a reference on to its caller, the |
| 71 | caller is said to receive a <em>new</em> reference. When no ownership |
| 72 | is transferred, the caller is said to <em>borrow</em> the reference. |
| 73 | Nothing needs to be done for a borrowed reference. |
| 74 | |
| 75 | <P> |
| 76 | Conversely, when a calling function passes it a reference to an |
| 77 | object, there are two possibilities: the function <em>steals</em> a |
| 78 | reference to the object, or it does not. Few functions steal |
| 79 | references; the two notable exceptions are |
| 80 | <tt class="cfunction">PyList_SetItem()</tt><a id='l2h-12' xml:id='l2h-12'></a> and |
| 81 | <tt class="cfunction">PyTuple_SetItem()</tt><a id='l2h-13' xml:id='l2h-13'></a>, which |
| 82 | steal a reference to the item (but not to the tuple or list into which |
| 83 | the item is put!). These functions were designed to steal a reference |
| 84 | because of a common idiom for populating a tuple or list with newly |
| 85 | created objects; for example, the code to create the tuple <code>(1, |
| 86 | 2, "three")</code> could look like this (forgetting about error handling for |
| 87 | the moment; a better way to code this is shown below): |
| 88 | |
| 89 | <P> |
| 90 | <div class="verbatim"><pre> |
| 91 | PyObject *t; |
| 92 | |
| 93 | t = PyTuple_New(3); |
| 94 | PyTuple_SetItem(t, 0, PyInt_FromLong(1L)); |
| 95 | PyTuple_SetItem(t, 1, PyInt_FromLong(2L)); |
| 96 | PyTuple_SetItem(t, 2, PyString_FromString("three")); |
| 97 | </pre></div> |
| 98 | |
| 99 | <P> |
| 100 | Incidentally, <tt class="cfunction">PyTuple_SetItem()</tt> is the <em>only</em> way to |
| 101 | set tuple items; <tt class="cfunction">PySequence_SetItem()</tt> and |
| 102 | <tt class="cfunction">PyObject_SetItem()</tt> refuse to do this since tuples are an |
| 103 | immutable data type. You should only use |
| 104 | <tt class="cfunction">PyTuple_SetItem()</tt> for tuples that you are creating |
| 105 | yourself. |
| 106 | |
| 107 | <P> |
| 108 | Equivalent code for populating a list can be written using |
| 109 | <tt class="cfunction">PyList_New()</tt> and <tt class="cfunction">PyList_SetItem()</tt>. Such code |
| 110 | can also use <tt class="cfunction">PySequence_SetItem()</tt>; this illustrates the |
| 111 | difference between the two (the extra <tt class="cfunction">Py_DECREF()</tt> calls): |
| 112 | |
| 113 | <P> |
| 114 | <div class="verbatim"><pre> |
| 115 | PyObject *l, *x; |
| 116 | |
| 117 | l = PyList_New(3); |
| 118 | x = PyInt_FromLong(1L); |
| 119 | PySequence_SetItem(l, 0, x); Py_DECREF(x); |
| 120 | x = PyInt_FromLong(2L); |
| 121 | PySequence_SetItem(l, 1, x); Py_DECREF(x); |
| 122 | x = PyString_FromString("three"); |
| 123 | PySequence_SetItem(l, 2, x); Py_DECREF(x); |
| 124 | </pre></div> |
| 125 | |
| 126 | <P> |
| 127 | You might find it strange that the ``recommended'' approach takes more |
| 128 | code. However, in practice, you will rarely use these ways of |
| 129 | creating and populating a tuple or list. There's a generic function, |
| 130 | <tt class="cfunction">Py_BuildValue()</tt>, that can create most common objects from |
| 131 | C values, directed by a <i class="dfn">format string</i>. For example, the |
| 132 | above two blocks of code could be replaced by the following (which |
| 133 | also takes care of the error checking): |
| 134 | |
| 135 | <P> |
| 136 | <div class="verbatim"><pre> |
| 137 | PyObject *t, *l; |
| 138 | |
| 139 | t = Py_BuildValue("(iis)", 1, 2, "three"); |
| 140 | l = Py_BuildValue("[iis]", 1, 2, "three"); |
| 141 | </pre></div> |
| 142 | |
| 143 | <P> |
| 144 | It is much more common to use <tt class="cfunction">PyObject_SetItem()</tt> and |
| 145 | friends with items whose references you are only borrowing, like |
| 146 | arguments that were passed in to the function you are writing. In |
| 147 | that case, their behaviour regarding reference counts is much saner, |
| 148 | since you don't have to increment a reference count so you can give a |
| 149 | reference away (``have it be stolen''). For example, this function |
| 150 | sets all items of a list (actually, any mutable sequence) to a given |
| 151 | item: |
| 152 | |
| 153 | <P> |
| 154 | <div class="verbatim"><pre> |
| 155 | int |
| 156 | set_all(PyObject *target, PyObject *item) |
| 157 | { |
| 158 | int i, n; |
| 159 | |
| 160 | n = PyObject_Length(target); |
| 161 | if (n < 0) |
| 162 | return -1; |
| 163 | for (i = 0; i < n; i++) { |
| 164 | if (PyObject_SetItem(target, i, item) < 0) |
| 165 | return -1; |
| 166 | } |
| 167 | return 0; |
| 168 | } |
| 169 | </pre></div> |
| 170 | |
| 171 | <P> |
| 172 | The situation is slightly different for function return values. |
| 173 | While passing a reference to most functions does not change your |
| 174 | ownership responsibilities for that reference, many functions that |
| 175 | return a reference to an object give you ownership of the reference. |
| 176 | The reason is simple: in many cases, the returned object is created |
| 177 | on the fly, and the reference you get is the only reference to the |
| 178 | object. Therefore, the generic functions that return object |
| 179 | references, like <tt class="cfunction">PyObject_GetItem()</tt> and |
| 180 | <tt class="cfunction">PySequence_GetItem()</tt>, always return a new reference (the |
| 181 | caller becomes the owner of the reference). |
| 182 | |
| 183 | <P> |
| 184 | It is important to realize that whether you own a reference returned |
| 185 | by a function depends on which function you call only -- <em>the |
| 186 | plumage</em> (the type of the object passed as an |
| 187 | argument to the function) <em>doesn't enter into it!</em> Thus, if you |
| 188 | extract an item from a list using <tt class="cfunction">PyList_GetItem()</tt>, you |
| 189 | don't own the reference -- but if you obtain the same item from the |
| 190 | same list using <tt class="cfunction">PySequence_GetItem()</tt> (which happens to |
| 191 | take exactly the same arguments), you do own a reference to the |
| 192 | returned object. |
| 193 | |
| 194 | <P> |
| 195 | Here is an example of how you could write a function that computes the |
| 196 | sum of the items in a list of integers; once using |
| 197 | <tt class="cfunction">PyList_GetItem()</tt><a id='l2h-14' xml:id='l2h-14'></a>, and once using |
| 198 | <tt class="cfunction">PySequence_GetItem()</tt><a id='l2h-15' xml:id='l2h-15'></a>. |
| 199 | |
| 200 | <P> |
| 201 | <div class="verbatim"><pre> |
| 202 | long |
| 203 | sum_list(PyObject *list) |
| 204 | { |
| 205 | int i, n; |
| 206 | long total = 0; |
| 207 | PyObject *item; |
| 208 | |
| 209 | n = PyList_Size(list); |
| 210 | if (n < 0) |
| 211 | return -1; /* Not a list */ |
| 212 | for (i = 0; i < n; i++) { |
| 213 | item = PyList_GetItem(list, i); /* Can't fail */ |
| 214 | if (!PyInt_Check(item)) continue; /* Skip non-integers */ |
| 215 | total += PyInt_AsLong(item); |
| 216 | } |
| 217 | return total; |
| 218 | } |
| 219 | </pre></div> |
| 220 | |
| 221 | <P> |
| 222 | <div class="verbatim"><pre> |
| 223 | long |
| 224 | sum_sequence(PyObject *sequence) |
| 225 | { |
| 226 | int i, n; |
| 227 | long total = 0; |
| 228 | PyObject *item; |
| 229 | n = PySequence_Length(sequence); |
| 230 | if (n < 0) |
| 231 | return -1; /* Has no length */ |
| 232 | for (i = 0; i < n; i++) { |
| 233 | item = PySequence_GetItem(sequence, i); |
| 234 | if (item == NULL) |
| 235 | return -1; /* Not a sequence, or other failure */ |
| 236 | if (PyInt_Check(item)) |
| 237 | total += PyInt_AsLong(item); |
| 238 | Py_DECREF(item); /* Discard reference ownership */ |
| 239 | } |
| 240 | return total; |
| 241 | } |
| 242 | </pre></div> |
| 243 | |
| 244 | <P> |
| 245 | |
| 246 | <DIV CLASS="navigation"> |
| 247 | <div class='online-navigation'> |
| 248 | <p></p><hr /> |
| 249 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 250 | <tr> |
| 251 | <td class='online-navigation'><a rel="prev" title="1.2.1 Reference Counts" |
| 252 | href="refcounts.html"><img src='../icons/previous.png' |
| 253 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 254 | <td class='online-navigation'><a rel="parent" title="1.2.1 Reference Counts" |
| 255 | href="refcounts.html"><img src='../icons/up.png' |
| 256 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 257 | <td class='online-navigation'><a rel="next" title="1.2.2 Types" |
| 258 | href="types.html"><img src='../icons/next.png' |
| 259 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 260 | <td align="center" width="100%">Python/C API Reference Manual</td> |
| 261 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 262 | href="contents.html"><img src='../icons/contents.png' |
| 263 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 264 | <td class='online-navigation'><img src='../icons/blank.png' |
| 265 | border='0' height='32' alt='' width='32' /></td> |
| 266 | <td class='online-navigation'><a rel="index" title="Index" |
| 267 | href="genindex.html"><img src='../icons/index.png' |
| 268 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 269 | </tr></table> |
| 270 | <div class='online-navigation'> |
| 271 | <b class="navlabel">Previous:</b> |
| 272 | <a class="sectref" rel="prev" href="refcounts.html">1.2.1 Reference Counts</A> |
| 273 | <b class="navlabel">Up:</b> |
| 274 | <a class="sectref" rel="parent" href="refcounts.html">1.2.1 Reference Counts</A> |
| 275 | <b class="navlabel">Next:</b> |
| 276 | <a class="sectref" rel="next" href="types.html">1.2.2 Types</A> |
| 277 | </div> |
| 278 | </div> |
| 279 | <hr /> |
| 280 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> |
| 281 | </DIV> |
| 282 | <!--End of Navigation Panel--> |
| 283 | <ADDRESS> |
| 284 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. |
| 285 | </ADDRESS> |
| 286 | </BODY> |
| 287 | </HTML> |