__init__(self)
(Constructor)

Create a cycle finder with empty root set.

chase_type(self, t, t_refs_func, t_tag_func)

t, t_refs_func, t_tag_func -> chase type t.

See module docstring for details.

clear(self)

Remove all internal references to external objects.

Empties the root set. Does not change the set of types this CycleFinder chases. Does not change the cycle filter in effect.

dont_chase_type(self, t)

t -> remove type t from the set of chased types.

See module docstring for details.

find_cycles(self, purge_dead_roots=0)

purge_dead_roots=0 -> look for cycles, return true if found.

Identify all cycles among objects reachable from the root set. Return true iff at least one cycle is found.

This should be called before any of the show_XXX methods. Note that it's OK to add more objects to the root set and call it again, or to change the set of chased types, etc. find_cycles starts over from scratch each time it's called.

If optional arg purge_dead_roots is true (default false), before searching for cycles the root set is purged of all objects that the preceding run of find_cycles determined had a true refcount of 0 (that is, the root set objects that are still alive only because they appear in the root set). Purging these allows their finalizers to get invoked, which may allow a cascade of other objects (including cycles) to go away too.

See also method install_cycle_filter.

get_chased_types(self)

Return the set of chased types, as a list.

get_rootset(self)

Return the root set, as a list of (rc, cyclic?, obj) tuples.

Should be called after find_cycles.  For each object in the
root set, returns a triple consisting of
refcount
    number of outstanding references less those due to
    CycleFinder internals; see show_obj docstring for more
    details; this will be None if find_cycles hasn't been
    run, or not since the last clear()
cyclic?
    true (1) iff obj is known to be in a cycle
obj
    the object

install_cycle_filter(self, filter_func=None)

filter_func=None -> a way to ignore "expected" cycles.

See module docstring for details. This is a callback function invoked whenever find_cycles() finds a cycle; the cycle is ignored unless the callback returns true.

register(self, obj)

obj -> add object obj to the root set.

run(self, func, args=(), kwargs={})

func, args=(), kwargs={} -> add objects to root set by magic.

Function func is invoked with arguments args and keyword arguments kwargs. For the duration of the call, each class instance initialized by an __init__ call is automatically added to the root set. The result of invoking func is returned.

show_arcs(self, compare=None)

compare=None -> print unique arc types in cycles.

See module docstring for details. Briefly, each arc in a cycle is categorized by the type of the source node, the kind of arc (how we got from the source to the destination), and the type of the destination node. Each line of output consists of those three pieces of info preceded by the count of arcs of that kind. By default, the rows are sorted first by column 2 (source node type), then by columns 3 and 4.

show_cycleobjs(self, compare=<function typename_address_cmp at 0x01F31C70>)

compare=typename_address_cmp -> print all objects in cycles.

Prints to stdout. Each distinct object find_cycles found in a cycle is displayed. The set of objects found in cycles is first sorted by the optional "compare" function. By default, objects are sorted using their type name as the primary key and their storage address (id) as the secondary key; among objects of instance type, sorts by the instances' class names; among objects of class type, sorts by the classes' names.

show_cycles(self)

Print all cycles to stdout.

show_obj(self, obj)

obj -> print short description of obj to sdtout.

This is of the form

<address> rc:<refcount> <typename>
    repr: <shortrepr>

where
<address>
    hex address of obj
<refcount>
    If find_cycles() has been run and obj is in the root set
    or was found in a cycle, this is the number of references
    outstanding less the number held internally by
    CycleFinder.  In most cases, this is what the true
    refcount would be had you not used CycleFinder at all.
    You can screw that up, e.g. by installing a cycle filter
    that holds on to references to one or more cycle elements.
    If find_cycles() has not been run, or has but obj wasn't
    found in a cycle and isn't in the root set, <refcount> is
    "?".
<typename>
    type(obj), as a string.  If obj.__class__ exists, also
    prints the class name.
<shortrepr>
    repr(obj), but using a variant of the std module repr.py
    that limits the number of characters displayed.

show_sccs(self, compare=<function typename_address_cmp at 0x01F31C70>)

compare=typename_address_cmp -> print SCCs.

Prints to stdout. Shows the objects in cycles partitioned into strongly connected components (that is, the largest groupings possible such that each object in an SCC is reachable from every other object in that SCC). Within each SCC, objects are sorted as for show_cycleobjs.

show_stats(self)

Print statistics for the last run of find_cycles.