<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!--Converted with LaTeX2HTML 98.2 beta6 (August 14th, 1998)
original version by:  Nikos Drakos, CBLU, University of Leeds
* revised and updated by:  Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
  Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>1.2.1.1 Reference Count Details </TITLE>
<META NAME="description" CONTENT="1.2.1.1 Reference Count Details ">
<META NAME="keywords" CONTENT="api">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<LINK REL="STYLESHEET" HREF="api.css">
<LINK REL="previous" HREF="refcounts.html">
<LINK REL="up" HREF="refcounts.html">
<LINK REL="next" HREF="types.html">
</HEAD>
<BODY bgcolor="#ffffff">
<div class=navigation>
<table align=center width="100%" cellpadding=0 cellspacing=2>
<tr>
<td><A HREF="types.html"><img width=32 height=32 align=bottom border=0 alt="next"
 src="../icons/next.gif"></A></td>
<td><A HREF="refcounts.html"><img width=32 height=32 align=bottom border=0 alt="up"
 src="../icons/up.gif"></A></td>
<td><A HREF="refcounts.html"><img width=32 height=32 align=bottom border=0 alt="previous"
 src="../icons/previous.gif"></A></td>
<td align=center bgcolor="#99CCFF" width="100%">
 <b class=title>Python/C API Reference Manual</b></td>
<td><A HREF="contents.html"><img width=32 height=32 align=bottom border=0 alt="contents"
 src="../icons/contents.gif"></A></td>
<td><img width=32 height=32 align=bottom border=0 alt=""
 src="../icons/blank.gif"></td>
<td><A HREF="genindex.html"><img width=32 height=32 align=bottom border=0 alt="index"
 src="../icons/index.gif"></A></td>
</tr></table><b class=navlabel>Next:</b> <span class=sectref><A HREF="types.html">1.2.2 Types</A></span>
<b class=navlabel>Up:</b> <span class=sectref><A HREF="refcounts.html">1.2.1 Reference Counts</A></span>
<b class=navlabel>Previous:</b> <span class=sectref><A HREF="refcounts.html">1.2.1 Reference Counts</A></span>
<br><hr></div>
<!--End of Navigation Panel-->

<H3><A NAME="SECTION003211000000000000000"></A>
<BR>
1.2.1.1 Reference Count Details 
</H3>

<P>
The reference count behavior of functions in the Python/C API is best 
expelained in terms of <i>ownership of references</i>.  Note that we 
talk of owning references, never of owning objects; objects are always 
shared!  When a function owns a reference, it has to dispose of it 
properly -- either by passing ownership on (usually to its caller) or 
by calling <tt class=cfunction>Py_DECREF()</tt> or <tt class=cfunction>Py_XDECREF()</tt>.  When
a function passes ownership of a reference on to its caller, the
caller is said to receive a <i>new</i> reference.  When no ownership
is transferred, the caller is said to <i>borrow</i> the reference.
Nothing needs to be done for a borrowed reference.

<P>
Conversely, when calling a function passes it a reference to an 
object, there are two possibilities: the function <i>steals</i> a 
reference to the object, or it does not.  Few functions steal 
references; the two notable exceptions are
<tt class=cfunction>PyList_SetItem()</tt> and <tt class=cfunction>PyTuple_SetItem()</tt>, which
steal a reference to the item (but not to the tuple or list into which
the item is put!).  These functions were designed to steal a reference
because of a common idiom for populating a tuple or list with newly
created objects; for example, the code to create the tuple <tt>(1,
2, "three")</tt> could look like this (forgetting about error handling for
the moment; a better way to code this is shown below anyway):

<P>
<dl><dd><pre class=verbatim>
PyObject *t;

t = PyTuple_New(3);
PyTuple_SetItem(t, 0, PyInt_FromLong(1L));
PyTuple_SetItem(t, 1, PyInt_FromLong(2L));
PyTuple_SetItem(t, 2, PyString_FromString("three"));
</pre></dl>

<P>
Incidentally, <tt class=cfunction>PyTuple_SetItem()</tt> is the <i>only</i> way to
set tuple items; <tt class=cfunction>PySequence_SetItem()</tt> and
<tt class=cfunction>PyObject_SetItem()</tt> refuse to do this since tuples are an
immutable data type.  You should only use
<tt class=cfunction>PyTuple_SetItem()</tt> for tuples that you are creating
yourself.

<P>
Equivalent code for populating a list can be written using 
<tt class=cfunction>PyList_New()</tt> and <tt class=cfunction>PyList_SetItem()</tt>.  Such code
can also use <tt class=cfunction>PySequence_SetItem()</tt>; this illustrates the
difference between the two (the extra <tt class=cfunction>Py_DECREF()</tt> calls):

<P>
<dl><dd><pre class=verbatim>
PyObject *l, *x;

l = PyList_New(3);
x = PyInt_FromLong(1L);
PySequence_SetItem(l, 0, x); Py_DECREF(x);
x = PyInt_FromLong(2L);
PySequence_SetItem(l, 1, x); Py_DECREF(x);
x = PyString_FromString("three");
PySequence_SetItem(l, 2, x); Py_DECREF(x);
</pre></dl>

<P>
You might find it strange that the ``recommended'' approach takes more
code.  However, in practice, you will rarely use these ways of
creating and populating a tuple or list.  There's a generic function,
<tt class=cfunction>Py_BuildValue()</tt>, that can create most common objects from
C values, directed by a <i class=dfn>format string</i>.  For example, the
above two blocks of code could be replaced by the following (which
also takes care of the error checking):

<P>
<dl><dd><pre class=verbatim>
PyObject *t, *l;

t = Py_BuildValue("(iis)", 1, 2, "three");
l = Py_BuildValue("[iis]", 1, 2, "three");
</pre></dl>

<P>
It is much more common to use <tt class=cfunction>PyObject_SetItem()</tt> and
friends with items whose references you are only borrowing, like
arguments that were passed in to the function you are writing.  In
that case, their behaviour regarding reference counts is much saner,
since you don't have to increment a reference count so you can give a
reference away (``have it be stolen'').  For example, this function
sets all items of a list (actually, any mutable sequence) to a given
item:

<P>
<dl><dd><pre class=verbatim>
int set_all(PyObject *target, PyObject *item)
{
    int i, n;

    n = PyObject_Length(target);
    if (n &lt; 0)
        return -1;
    for (i = 0; i &lt; n; i++) {
        if (PyObject_SetItem(target, i, item) &lt; 0)
            return -1;
    }
    return 0;
}
</pre></dl>

<P>
The situation is slightly different for function return values.  
While passing a reference to most functions does not change your 
ownership responsibilities for that reference, many functions that 
return a referece to an object give you ownership of the reference.
The reason is simple: in many cases, the returned object is created 
on the fly, and the reference you get is the only reference to the 
object.  Therefore, the generic functions that return object 
references, like <tt class=cfunction>PyObject_GetItem()</tt> and 
<tt class=cfunction>PySequence_GetItem()</tt>, always return a new reference (i.e.,
the  caller becomes the owner of the reference).

<P>
It is important to realize that whether you own a reference returned 
by a function depends on which function you call only -- <i>the
plumage</i> (i.e., the type of the type of the object passed as an
argument to the function) <i>doesn't enter into it!</i>  Thus, if you 
extract an item from a list using <tt class=cfunction>PyList_GetItem()</tt>, you
don't own the reference -- but if you obtain the same item from the
same list using <tt class=cfunction>PySequence_GetItem()</tt> (which happens to
take exactly the same arguments), you do own a reference to the
returned object.

<P>
Here is an example of how you could write a function that computes the
sum of the items in a list of integers; once using 
<tt class=cfunction>PyList_GetItem()</tt>, once using
<tt class=cfunction>PySequence_GetItem()</tt>.

<P>
<dl><dd><pre class=verbatim>
long sum_list(PyObject *list)
{
    int i, n;
    long total = 0;
    PyObject *item;

    n = PyList_Size(list);
    if (n &lt; 0)
        return -1; /* Not a list */
    for (i = 0; i &lt; n; i++) {
        item = PyList_GetItem(list, i); /* Can't fail */
        if (!PyInt_Check(item)) continue; /* Skip non-integers */
        total += PyInt_AsLong(item);
    }
    return total;
}
</pre></dl>

<P>
<dl><dd><pre class=verbatim>
long sum_sequence(PyObject *sequence)
{
    int i, n;
    long total = 0;
    PyObject *item;
    n = PyObject_Size(list);
    if (n &lt; 0)
        return -1; /* Has no length */
    for (i = 0; i &lt; n; i++) {
        item = PySequence_GetItem(list, i);
        if (item == NULL)
            return -1; /* Not a sequence, or other failure */
        if (PyInt_Check(item))
            total += PyInt_AsLong(item);
        Py_DECREF(item); /* Discard reference ownership */
    }
    return total;
}
</pre></dl>

<P>
<p>
<div class=navigation><hr><table align=center width="100%" cellpadding=0 cellspacing=2>
<tr>
<td><A HREF="types.html"><img width=32 height=32 align=bottom border=0 alt="next"
 src="../icons/next.gif"></A></td>
<td><A HREF="refcounts.html"><img width=32 height=32 align=bottom border=0 alt="up"
 src="../icons/up.gif"></A></td>
<td><A HREF="refcounts.html"><img width=32 height=32 align=bottom border=0 alt="previous"
 src="../icons/previous.gif"></A></td>
<td align=center bgcolor="#99CCFF" width="100%">
 <b class=title>Python/C API Reference Manual</b></td>
<td><A HREF="contents.html"><img width=32 height=32 align=bottom border=0 alt="contents"
 src="../icons/contents.gif"></A></td>
<td><img width=32 height=32 align=bottom border=0 alt=""
 src="../icons/blank.gif"></td>
<td><A HREF="genindex.html"><img width=32 height=32 align=bottom border=0 alt="index"
 src="../icons/index.gif"></A></td>
</tr></table><b class=navlabel>Next:</b> <span class=sectref><A HREF="types.html">1.2.2 Types</A></span>
<b class=navlabel>Up:</b> <span class=sectref><A HREF="refcounts.html">1.2.1 Reference Counts</A></span>
<b class=navlabel>Previous:</b> <span class=sectref><A HREF="refcounts.html">1.2.1 Reference Counts</A></span>
</div>
<!--End of Navigation Panel-->
<ADDRESS>
<hr>Send comments on this document to <a href="mailto:python-docs@python.org">python-docs@python.org</a>.
</ADDRESS>
</BODY>
</HTML>
