WHUI! (was Re: [Python-Dev] Proposal: C API Macro to decref and set to NULL)

[Jim Fulton]

Tim Peters wrote:
> [Jim Fulton]
> ...
> 

...

> BTW, re-invented at least as often is a VISIT macro for use in
> tp_traverse slots, like typeobject.c's (and several other files')
> 
> #define VISIT(SLOT) \
> 	if (SLOT) { \
> 		err = visit((PyObject *)(SLOT), arg); \
> 		if (err) \
> 			return err; \
> 	}

First, I don't like this macro, based on my own experience writing macros
that hide returns. :)

Second, Aaargh!  I missunderstood the use of the visit function
passed to traverse.  The source of my missunderstanding was

   1) visit is an int function and I normally expect int functions to
      return a negative value to indicate an error and

   2) The documentation for the traversal slot says:
      "If visit returns a non-zero value then an error has occurred
      and that value should be returned immediately."
      That is, the documentation says that the return value is an
      error indicator.  I missed the bit about a non-zero return value
      and needing to return it. My bad.

Last night, Tim explained to me that a non-zero return value is not an
error indicator.  In fact, the GC system doesn't really allow errors.
Rather, a non-zero return value provides a way for a visit proc to
short-circuit the traversal process.  As far as Tim knows, this feature
has never been used.  All visit functions in the core always return 0.

Alas, all my extensions that implement tp_traverse and the documentation
I wrote on writing types is wrong and has to be changed. Sigh.

Should we call WHUI (we haven't used it!) on this feature that has been around
for 4 versions of Python, that complicates tp_traverse implementations and
hasn't been used? It would be simpler if we said that the return value could
be ignored.

Jim

-- 
Jim Fulton           mailto:jim at zope.com       Python Powered!
CTO                  (540) 361-1714            http://www.python.org
Zope Corporation     http://www.zope.com       http://www.zope.org