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

[Tim Peters]

[Jim Fulton, on non-zero return values from a visitproc]
> ...
> 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.

As you and I (but not python-dev) discussed in later email, the
non-zero return gimmick is used by two visitprocs in gcmodule.c after
all.  To match actual uses, instead of

    If visit returns a non-zero value then an error has occurred and
that value should
    be returned immediately

the docs should say

    If visit returns a non-zero value that value should be returned immediately

I believe the latter matches the original design intent too.

I doubt that anyone outside the core has written a visitproc.  If so,
all existing uses could just as well be met by

    If visit returns a non-zero value then 1 should be returned immediately

but that wouldn't really save any cycles.

Note that it's not expected that users will write visitproc.  The type
of visitproc has to be defined so that users can write tp_traverse
functions, not really so they can write their own visitprocs.  Any
visitproc spec "that works" for gcmodule's internal purposes (gcmodule
is the only known supplier of visitprocs) is good enough. 
User-supplied tp_traverse methods just have to play along.

Moving the first last:

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

Except VISIT is useful only inside a tp_traverse implementation, and
all such implementations look exactly the same (VISIT, VISIT, VISIT,
..., sometimes with a surrounding loop).  That's not an accident,
since the only purpose of a tp_traverse implementation is to VISIT
containees.  So it's a special-purpose macro for a highly specific and
uniform task, not a general-purpose macro that has to play well in
arbitrary contexts.