[Python-checkins] python/dist/src/Doc/api refcounting.tex,1.2,1.3

Wed Jul 14 21:07:42 CEST 2004

Update of /cvsroot/python/python/dist/src/Doc/api
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv15507/Doc/api
Modified Files:
	refcounting.tex 
Log Message:
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
Index: refcounting.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/api/refcounting.tex,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** refcounting.tex	22 Apr 2004 17:23:21 -0000	1.2
--- refcounting.tex	14 Jul 2004 19:07:35 -0000	1.3
***************
*** 43,46 ****
--- 43,62 ----
 \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)}.