Implemented a new Py_CLEAR macro. This macro should be used when

decrementing the refcount of variables that might be accessed as a
result of calling Python

1 files changed, 16 insertions, 0 deletions

diff --git a/Doc/api/refcounting.tex b/Doc/api/refcounting.tex
index 42b9e6a..add5d65 100644
--- a/Doc/api/refcounting.tex
+++ b/Doc/api/refcounting.tex
@@ -42,6 +42,22 @@ of Python objects.
   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 it's 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