mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-11-03 19:34:08 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 9

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

Browse source
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
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}} \subsubsection{Reference Count Details \label{refcountDetails}}
The reference count behavior of functions in the Python/C API is best The reference count behavior of functions in the Python/C API is best
explained in terms of \emph{ownership of references}. Note that we explained in terms of \emph{ownership of references}. Ownership
talk of owning references, never of owning objects; objects are always pertains to references, never to objects (objects are not owned: they
shared! When a function owns a reference, it has to dispose of it are always shared). "Owning a reference" means being responsible for
properly --- either by passing ownership on (usually to its caller) or calling Py_DECREF on it when the reference is no longer needed.
by calling \cfunction{Py_DECREF()} or \cfunction{Py_XDECREF()}. When Ownership can also be transferred, meaning that the code that receives
a function passes ownership of a reference on to its caller, the 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 caller is said to receive a \emph{new} reference. When no ownership
is transferred, the caller is said to \emph{borrow} the reference. is transferred, the caller is said to \emph{borrow} the reference.
Nothing needs to be done for a borrowed reference. Nothing needs to be done for a borrowed reference.