Patches item #1473132, was opened at 2006-04-19 19:43 Message generated for change (Comment added) made by twouters 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: Thomas Wouters (twouters) Date: 2006-05-01 11:24 Message: 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 ;) ---------------------------------------------------------------------- Comment By: Collin Winter (collinwinter) Date: 2006-05-01 05:43 Message: Logged In: YES user_id=1344176 I've enhanced the patch per Tim Peters' comment. ---------------------------------------------------------------------- Comment By: Tim Peters (tim_one) Date: 2006-04-23 05: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 _______________________________________________ Patches mailing list [email protected] http://mail.python.org/mailman/listinfo/patches
