Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

Patch #837322: Clarify owning, borrowing, stealing. Backported to 2.3.

This commit is contained in:
Martin v. Löwis 2003-11-06 21:08:11 +00:00
parent d2171d2ba4
commit 5ce2fecf8e
1 changed files with 10 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
Doc/api/intro.tex
View File

@ -169,12 +169,16 @@ becomes second nature.
\subsubsection{Reference Count Details \label{refcountDetails}}
The reference count behavior of functions in the Python/C API is best
explained in terms of \emph{ownership of references}. 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 \cfunction{Py_DECREF()} or \cfunction{Py_XDECREF()}. When
a function passes ownership of a reference on to its caller, the
explained in terms of \emph{ownership of references}. Ownership
pertains to references, never to objects (objects are not owned: they
are always shared). "Owning a reference" means being responsible for
calling Py_DECREF on it when the reference is no longer needed.
Ownership can also be transferred, meaning that the code that receives
ownership of the reference then becomes responsible for eventually
decref'ing it by calling \cfunction{Py_DECREF()} or
\cfunction{Py_XDECREF()} when it's no longer needed --or passing on
this responsibility (usually to its caller).
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
is transferred, the caller is said to \emph{borrow} the reference.
Nothing needs to be done for a borrowed reference.