1Devel::Cycle(3) User Contributed Perl Documentation Devel::Cycle(3)
2
6 Devel::Cycle - Find memory cycles in objects
7
9 #!/usr/bin/perl
10 use Devel::Cycle;
11 my $test = {fred => [qw(a b c d e)],
12 ethel => [qw(1 2 3 4 5)],
13 george => {martha => 23,
14 agnes => 19}
15 };
16 $test->{george}{phyllis} = $test;
17 $test->{fred}[3] = $test->{george};
18 $test->{george}{mary} = $test->{fred};
19 find_cycle($test);
20 exit 0;
21 # output:
23 Cycle (1):
25 $A->{'george'} => \%B
26 $B->{'phyllis'} => \%A
27 Cycle (2):
29 $A->{'george'} => \%B
30 $B->{'mary'} => \@A
31 $A->[3] => \%B
32 Cycle (3):
34 $A->{'fred'} => \@A
35 $A->[3] => \%B
36 $B->{'phyllis'} => \%A
37 Cycle (4):
39 $A->{'fred'} => \@A
40 $A->[3] => \%B
41 $B->{'mary'} => \@A
42 # you can also check weakened references
44 weaken($test->{george}->{phyllis});
45 find_weakened_cycle($test);
46 exit 0;
47 # output:
49 Cycle (1):
51 $A->{'george'} => \%B
52 $B->{'mary'} => \@C
53 $C->[3] => \%B
54 Cycle (2):
56 $A->{'george'} => \%B
57 w-> $B->{'phyllis'} => \%A
58 Cycle (3):
60 $A->{'fred'} => \@C
61 $C->[3] => \%B
62 $B->{'mary'} => \@C
63 Cycle (4):
65 $A->{'fred'} => \@C
66 $C->[3] => \%B
67 w-> $B->{'phyllis'} => \%A
68
70 This is a simple developer's tool for finding circular references in
71 objects and other types of references. Because of Perl's reference-
72 count based memory management, circular references will cause memory
73 leaks.
74 EXPORT
76 The find_cycle() and find_weakened_cycle() subroutine are exported by
78 default.
79 find_cycle($object_reference,[$callback])
81 The find_cycle() function will traverse the object reference and
82 print a report to STDOUT identifying any memory cycles it finds.
83 If an optional callback code reference is provided, then this call‐
85 back will be invoked on each cycle that is found. The callback
86 will be passed an array reference pointing to a list of lists with
87 the following format:
88 $arg = [ ['REFTYPE',$index,$reference,$reference_value],
90 ['REFTYPE',$index,$reference,$reference_value],
91 ['REFTYPE',$index,$reference,$reference_value],
92 ...
93 ]
94 Each element in the array reference describes one edge in the mem‐
96 ory cycle. 'REFTYPE' describes the type of the reference and is
97 one of 'SCALAR','ARRAY' or 'HASH'. $index is the index affected by
98 the reference, and is undef for a scalar, an integer for an array
99 reference, or a hash key for a hash. $reference is the memory ref‐
100 erence, and $reference_value is its dereferenced value. For exam‐
101 ple, if the edge is an ARRAY, then the following relationship
102 holds:
103 $reference->[$index] eq $reference_value
105 The first element of the array reference is the $object_reference
107 that you pased to find_cycle() and may not be directly involved in
108 the cycle.
109 If a reference is a weak ref produced using Scalar::Util's weaken()
111 function then it won't contribute to cycles.
112 find_weakened_cycle($object_reference,[$callback])
114 The find_weakened_cycle() function will traverse the object refer‐
115 ence and print a report to STDOUT identifying any memory cycles it
116 finds, including any weakened cycles produced using Scalar::Util's
117 weaken().
118 If an optional callback code reference is provided, then this call‐
120 back will be invoked on each cycle that is found. The callback
121 will be passed an array reference pointing to a list of lists with
122 the following format:
123 $arg = [ ['REFTYPE',$index,$reference,$reference_value,$is_weakened],
125 ['REFTYPE',$index,$reference,$reference_value,$is_weakened],
126 ['REFTYPE',$index,$reference,$reference_value,$is_weakened],
127 ...
128 ]
129 Each element in the array reference describes one edge in the mem‐
131 ory cycle. 'REFTYPE' describes the type of the reference and is
132 one of 'SCALAR','ARRAY' or 'HASH'. $index is the index affected by
133 the reference, and is undef for a scalar, an integer for an array
134 reference, or a hash key for a hash. $reference is the memory ref‐
135 erence, and $reference_value is its dereferenced value. $is_weak‐
136 ened is a boolean specifying if the reference is weakened or not.
137 For example, if the edge is an ARRAY, then the following relation‐
138 ship holds:
139 $reference->[$index] eq $reference_value
141 The first element of the array reference is the $object_reference
143 that you pased to find_cycle() and may not be directly involved in
144 the cycle.
145 Cycle Report Formats
147 The default callback prints out a trace of each cycle it finds. You
149 can control the format of the trace by setting the package variable
150 $Devel::Cycle::FORMATTING to one of "raw," "cooked," or "roasted".
151 The "raw" format prints out anonymous memory references using standard
153 Perl memory location nomenclature. For example, a "Foo::Bar" object
154 that points to an ordinary hash will appear in the trace like this:
155 Foo::Bar=HASH(0x8124394)->{'phyllis'} => HASH(0x81b4a90)
157 The "cooked" format (the default), uses short names for anonymous mem‐
159 ory locations, beginning with "A" and moving upward with the magic ++
160 operator. This leads to a much more readable display:
161 $Foo::Bar=B->{'phyllis'} => \%A
163 The "roasted" format is similar to the "cooked" format, except that
165 object references are formatted slightly differently:
166 $Foo::Bar::B->{'phyllis'} => \%A
168 If a reference is a weakened ref, then it will have a 'w->' prepended
170 to it, like this:
171 w-> $Foo::Bar::B->{'phyllis'} => \%A
173 For your convenience, $Devel::Cycle::FORMATTING can be imported:
175 use Devel::Cycle qw(:DEFAULT $FORMATTING);
177 $FORMATTING = 'raw';
178 Alternatively, you can control the formatting at compile time by pass‐
180 ing one of the options -raw, -cooked, or -roasted to "use" as illus‐
181 trated here:
182 use Devel::Cycle -raw;
184 Code references (closures)
186 If the PadWalker module is installed, Devel::Cycle will also report
188 cycles in code closures. If PadWalker is not installed and Devel::Cycle
189 detects a CODE reference in one of the data structures, it will warn
190 (once per data structure) that it cannot inspect the CODE unless Pad‐
191 Walker is available. You can turn this warning off by passing -quiet to
192 Devel::Cycle at compile time:
193 use Devel::Cycle -quiet;
195
197 Test::Memory::Cycle Devel::Leak Scalar::Util
198
200 Lincoln Stein, <lstein@cshl.edu>
201
203 Copyright (C) 2003 by Lincoln Stein
204 This library is free software; you can redistribute it and/or modify it
206 under the same terms as Perl itself, either Perl version 5.8.2 or, at
207 your option, any later version of Perl 5 you may have available.
208perl v5.8.8 2006-05-23 Devel::Cycle(3)