[Patches] [ python-Patches-1473132 ] Improve docs for tp_clear and tp_traverse

[SourceForge.net]

Patches item #1473132, was opened at 2006-04-19 13:43
Message generated for change (Comment added) made by tim_one
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=305470&aid=1473132&group_id=5470

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: Documentation
Group: Python 2.5
Status: Open
Resolution: None
Priority: 5
Submitted By: Collin Winter (collinwinter)
Assigned to: Nobody/Anonymous (nobody)
Summary: Improve docs for tp_clear and tp_traverse

Initial Comment:
The attached patch greatly enhances the documentation
for the tp_clear and tp_traverse functions. The patch
is against Doc/api/newtypes.tex, r45562.

----------------------------------------------------------------------

>Comment By: Tim Peters (tim_one)
Date: 2006-04-22 23:30

Message:
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.

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=305470&aid=1473132&group_id=5470