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} \end{ctypedesc}
To simplify writing \member{tp_traverse} handlers, a 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} \begin{cfuncdesc}{void}{Py_VISIT}{PyObject *o}
Call the \var{visit} for \var{o} with \var{arg}. If \var{visit} Call the \var{visit} callback, with arguments \var{o} and \var{arg}.
returns a non-zero value, then return it. Using this macro, If \var{visit} returns a non-zero value, then return it. Using this
\member{tp_traverse} handlers look like: macro, \member{tp_traverse} handlers look like:
\begin{verbatim} \begin{verbatim}
static int 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. 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 Python 2.4 and higher provide a \cfunction{Py_VISIT()} macro that automates
calling visit functions. With \cfunction{Py_VISIT()}, the calling visit functions. With \cfunction{Py_VISIT()},
\cfunction{Noddy_traverse()} can be simplified: \cfunction{Noddy_traverse()} can be simplified:
@ -856,6 +856,11 @@ Noddy_traverse(Noddy *self, visitproc visit, void *arg)
} }
\end{verbatim} \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 We also need to provide a method for clearing any subobjects that can
participate in cycles. We implement the method and reimplement the participate in cycles. We implement the method and reimplement the
deallocator to use it: deallocator to use it:

View file

@ -302,7 +302,11 @@ PyAPI_FUNC(void) PyObject_GC_Del(void *);
( (type *) _PyObject_GC_NewVar((typeobj), (n)) ) ( (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) \ #define Py_VISIT(op) \
do { \ do { \
if (op) { \ if (op) { \