70 lines
2.9 KiB
TeX
70 lines
2.9 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}
|
|
|
|
\begin{cfuncdesc}{void}{Py_CLEAR}{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()}, except that the argument
|
|
is also set to \NULL. The warning for \cfunction{Py_DECREF()} does
|
|
not apply with respect to the object passed because the macro
|
|
carefully uses a temporary variable and sets the argument to \NULL
|
|
before decrementing its reference count.
|
|
|
|
It is a good idea to use this macro whenever decrementing the value
|
|
of a variable that might be traversed during garbage collection.
|
|
|
|
\versionadded{2.4}
|
|
\end{cfuncdesc}
|
|
|
|
|
|
The following functions are for runtime dynamic embedding of Python:
|
|
\cfunction{Py_IncRef(PyObject *o)}, \cfunction{Py_DecRef(PyObject *o)}.
|
|
They are simply exported function versions of \cfunction{Py_XINCREF()} and
|
|
\cfunction{Py_XDECREF()}, respectively.
|
|
|
|
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}.
|