Issue 1473132: Improve docs for tp_clear and tp_traverse (original) (raw)

Logged In: YES user_id=31435

I agree the additional info is helpful (thanks!).

Alas, there's more to it, and it's hard to know when to stop :-(.

For example, an author of a type may want to visit, e.g., contained strings in tp_traverse, because they want gc.get_referents() to return the contained strings (typically as a debugging aid).

The issues wrt to tp_clear are subtler. The real requirement is that the aggregate of all tp_clears called break all possible cycles. For one thing, that means there's no real reason for a tp_clear to touch a member that's known to be a Python string or integer (since such an object can't be in a cycle, clearing it can't help to break a cycle). It's only tp_dealloc that must drop references to all containees.

Subtler is that a gc'ed container type may choose not to implement tp_clear at all. If you look, you'll see that Python's tuple type in fact leaves its tp_clear slot empty. This isn't a problem because it's impossible to have a cycle composed solely of tuples (that may not be obvious, but it's true -- it derives from that tuples are immutable). Any cycle a tuple may be in will be broken if the non-tuple objects in the cycle clear their containees, so there's no actually need for tuples to have a tp_clear.

The possibility should be mentioned, although it's fine to recommend playing it safe. Indeed, I don't think it buys anything worth having for tuples not to have an obvious tp_clear implementation.

Logged In: YES user_id=34209

As Tim said, there is more to it :) I think this is a fine start, though. One minor point: the use of Py_CLEAR() can do with some extra explanation. It obviously isn't enough to just 'NULL out' members, since that would leak references, but the docs should also explain that it is in fact important to set the actual member to NULL before DECREFing the reference, and then point out that the Py_CLEAR macro is a convenient way of doing that. That kind of tweak can happen after it's checked in, though (preferably by someone who can build documentation and see that the result looks okay ;)