From: Jim Fulton Date: Wed, 14 Jul 2004 19:08:17 +0000 (+0000) Subject: Documented the new Py_VISIT macro to simplify implementation of X-Git-Tag: v2.4a2~267 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=aa6389e13be460cce1f16f2a525ba8754737d30b;p=python Documented the new Py_VISIT macro to simplify implementation of tp_traverse handlers. (Tim made me do it. ;) --- diff --git a/Doc/api/newtypes.tex b/Doc/api/newtypes.tex index 036664e5ae..2b58cd90cd 100644 --- a/Doc/api/newtypes.tex +++ b/Doc/api/newtypes.tex @@ -1663,6 +1663,29 @@ The \member{tp_traverse} handler must have the following type: that value should be returned immediately. \end{ctypedesc} +To simplify writing \member{tp_traverse} handlers, a +\cfunction{Py_VISIT()} is provided: + +\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: + + +\begin{verbatim} +static int +my_traverse(Noddy *self, visitproc visit, void *arg) +{ + Py_VISIT(self->foo); + Py_VISIT(self->bar); + return 0; +} +\end{verbatim} + +\versionadded{2.4} +\end{cfuncdesc} + + The \member{tp_clear} handler must be of the \ctype{inquiry} type, or \NULL{} if the object is immutable. diff --git a/Include/objimpl.h b/Include/objimpl.h index 3679cbad1b..649d1bc8b3 100644 --- a/Include/objimpl.h +++ b/Include/objimpl.h @@ -302,6 +302,16 @@ PyAPI_FUNC(void) PyObject_GC_Del(void *); ( (type *) _PyObject_GC_NewVar((typeobj), (n)) ) +/* Utility macro to help write tp_traverse functions */ +#define Py_VISIT(op) \ + do { \ + if (op) { \ + int vret = visit((op), arg); \ + if (vret) \ + return vret; \ + } \ + } while (0) + /* This is here for the sake of backwards compatibility. Extensions that * use the old GC API will still compile but the objects will not be * tracked by the GC. */