Formalize that the Py_VISIT macro requires that the tp_traverse

implementation it's used in must give its arguments specific names.
This commit is contained in:
Tim Peters 2004-07-15 04:05:59 +00:00
parent 89ba1fff17
commit eda29306b3
3 changed files with 49 additions and 39 deletions

View File

@ -1664,13 +1664,14 @@ The \member{tp_traverse} handler must have the following type:
\end{ctypedesc}
To simplify writing \member{tp_traverse} handlers, a
\cfunction{Py_VISIT()} is provided:
\cfunction{Py_VISIT()} macro is provided. In order to use this macro,
the \member{tp_traverse} implementation must name its arguments
exactly \var{visit} and \var{arg}:
\begin{cfuncdesc}{void}{Py_VISIT}{PyObject *o}
Call the \var{visit} for \var{o} with \var{arg}. If \var{visit}
returns a non-zero value, then return it. Using this macro,
\member{tp_traverse} handlers look like:
Call the \var{visit} callback, with arguments \var{o} and \var{arg}.
If \var{visit} returns a non-zero value, then return it. Using this
macro, \member{tp_traverse} handlers look like:
\begin{verbatim}
static int

View File

@ -841,8 +841,8 @@ the extra argument \var{arg} passed to the traversal method. It
returns an integer value that must be returned if it is non-zero.
Python 2.4 and higher provide a \cfunction{Py_VISIT()} that automates
calling visit functions. With \cfunction{Py_VISIT()}, the
Python 2.4 and higher provide a \cfunction{Py_VISIT()} macro that automates
calling visit functions. With \cfunction{Py_VISIT()},
\cfunction{Noddy_traverse()} can be simplified:
@ -856,6 +856,11 @@ Noddy_traverse(Noddy *self, visitproc visit, void *arg)
}
\end{verbatim}
\note{Note that the \member{tp_traverse} implementation must name its
arguments exactly \var{visit} and \var{arg} in order to use
\cfunction{Py_VISIT()}. This is to encourage uniformity
across these boring implementations.}
We also need to provide a method for clearing any subobjects that can
participate in cycles. We implement the method and reimplement the
deallocator to use it:

View File

@ -302,7 +302,11 @@ PyAPI_FUNC(void) PyObject_GC_Del(void *);
( (type *) _PyObject_GC_NewVar((typeobj), (n)) )
/* Utility macro to help write tp_traverse functions */
/* Utility macro to help write tp_traverse functions.
* To use this macro, the tp_traverse function must name its arguments
* "visit" and "arg". This is intended to keep tp_traverse functions
* looking as much alike as possible.
*/
#define Py_VISIT(op) \
do { \
if (op) { \