traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Patch #1415507: clarify docs on reference stealing

This commit is contained in:
Georg Brandl 2006-02-18 22:55:59 +00:00
parent f4f4415a18
commit 4caeff9867
1 changed files with 13 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
Doc/api/intro.tex
View File

@ -179,7 +179,7 @@ calling Py_DECREF on it when the reference is no longer needed.
Ownership can also be transferred, meaning that the code that receives Ownership can also be transferred, meaning that the code that receives
ownership of the reference then becomes responsible for eventually ownership of the reference then becomes responsible for eventually
decref'ing it by calling \cfunction{Py_DECREF()} or decref'ing it by calling \cfunction{Py_DECREF()} or
\cfunction{Py_XDECREF()} when it's no longer needed --or passing on \cfunction{Py_XDECREF()} when it's no longer needed---or passing on
this responsibility (usually to its caller). this responsibility (usually to its caller).
When a function passes ownership of a reference on to its caller, the When a function passes ownership of a reference on to its caller, the
caller is said to receive a \emph{new} reference. When no ownership caller is said to receive a \emph{new} reference. When no ownership
@ -188,8 +188,12 @@ Nothing needs to be done for a borrowed reference.
Conversely, when a calling function passes it a reference to an Conversely, when a calling function passes it a reference to an
object, there are two possibilities: the function \emph{steals} a object, there are two possibilities: the function \emph{steals} a
reference to the object, or it does not. Few functions steal reference to the object, or it does not. \emph{Stealing a reference}
references; the two notable exceptions are means that when you pass a reference to a function, that function
assumes that it now owns that reference, and you are not responsible
for it any longer.
Few functions steal references; the two notable exceptions are
\cfunction{PyList_SetItem()}\ttindex{PyList_SetItem()} and \cfunction{PyList_SetItem()}\ttindex{PyList_SetItem()} and
\cfunction{PyTuple_SetItem()}\ttindex{PyTuple_SetItem()}, which \cfunction{PyTuple_SetItem()}\ttindex{PyTuple_SetItem()}, which
steal a reference to the item (but not to the tuple or list into which steal a reference to the item (but not to the tuple or list into which
@ -208,6 +212,12 @@ PyTuple_SetItem(t, 1, PyInt_FromLong(2L));
PyTuple_SetItem(t, 2, PyString_FromString("three")); PyTuple_SetItem(t, 2, PyString_FromString("three"));
\end{verbatim} \end{verbatim}
Here, \cfunction{PyInt_FromLong()} returns a new reference which is
immediately stolen by \cfunction{PyTuple_SetItem()}. When you want to
keep using an object although the reference to it will be stolen,
use \cfunction{Py_INCREF()} to grab another reference before calling the
reference-stealing function.
Incidentally, \cfunction{PyTuple_SetItem()} is the \emph{only} way to Incidentally, \cfunction{PyTuple_SetItem()} is the \emph{only} way to
set tuple items; \cfunction{PySequence_SetItem()} and set tuple items; \cfunction{PySequence_SetItem()} and
\cfunction{PyObject_SetItem()} refuse to do this since tuples are an \cfunction{PyObject_SetItem()} refuse to do this since tuples are an