From: Jim Fulton <jim@zope.com>
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. */