49 lines
2.0 KiB
TeX
49 lines
2.0 KiB
TeX
|
\chapter{Reference Counting \label{countingRefs}}
|
||
|
|
|
||
|
|
|
||
|
|
The macros in this section are used for managing reference counts
|
||
|
|
of Python objects.
|
||
|
|
|
||
|
|
|
||
|
|
\begin{cfuncdesc}{void}{Py_INCREF}{PyObject *o}
|
||
|
|
Increment the reference count for object \var{o}. The object must
|
||
|
|
not be \NULL; if you aren't sure that it isn't \NULL, use
|
||
|
|
\cfunction{Py_XINCREF()}.
|
||
|
|
\end{cfuncdesc}
|
||
|
|
|
||
|
|
\begin{cfuncdesc}{void}{Py_XINCREF}{PyObject *o}
|
||
|
|
Increment the reference count for object \var{o}. The object may be
|
||
|
|
\NULL, in which case the macro has no effect.
|
||
|
|
\end{cfuncdesc}
|
||
|
|
|
||
|
|
\begin{cfuncdesc}{void}{Py_DECREF}{PyObject *o}
|
||
|
|
Decrement the reference count for object \var{o}. The object must
|
||
|
|
not be \NULL; if you aren't sure that it isn't \NULL, use
|
||
|
|
\cfunction{Py_XDECREF()}. If the reference count reaches zero, the
|
||
|
|
object's type's deallocation function (which must not be \NULL) is
|
||
|
|
invoked.
|
||
|
|
|
||
|
|
\warning{The deallocation function can cause arbitrary Python code
|
||
|
|
to be invoked (e.g. when a class instance with a \method{__del__()}
|
||
|
|
method is deallocated). While exceptions in such code are not
|
||
|
|
propagated, the executed code has free access to all Python global
|
||
|
|
variables. This means that any object that is reachable from a
|
||
|
|
global variable should be in a consistent state before
|
||
|
|
\cfunction{Py_DECREF()} is invoked. For example, code to delete an
|
||
|
|
object from a list should copy a reference to the deleted object in
|
||
|
|
a temporary variable, update the list data structure, and then call
|
||
|
|
\cfunction{Py_DECREF()} for the temporary variable.}
|
||
|
|
\end{cfuncdesc}
|
||
|
|
|
||
|
|
\begin{cfuncdesc}{void}{Py_XDECREF}{PyObject *o}
|
||
|
|
Decrement the reference count for object \var{o}. The object may be
|
||
|
|
\NULL, in which case the macro has no effect; otherwise the effect
|
||
|
|
is the same as for \cfunction{Py_DECREF()}, and the same warning
|
||
|
|
applies.
|
||
|
|
\end{cfuncdesc}
|
||
|
|
|
||
|
|
The following functions or macros are only for use within the
|
||
|
|
interpreter core: \cfunction{_Py_Dealloc()},
|
||
|
|
\cfunction{_Py_ForgetReference()}, \cfunction{_Py_NewReference()}, as
|
||
|
|
well as the global variable \cdata{_Py_RefTotal}.
|