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
77 default.
78 find_cycle($object_reference,[$callback])
80 The find_cycle() function will traverse the object reference and
81 print a report to STDOUT identifying any memory cycles it finds.
82 If an optional callback code reference is provided, then this
84 callback will be invoked on each cycle that is found. The callback
85 will be passed an array reference pointing to a list of lists with
86 the following format:
87 $arg = [ ['REFTYPE',$index,$reference,$reference_value],
89 ['REFTYPE',$index,$reference,$reference_value],
90 ['REFTYPE',$index,$reference,$reference_value],
91 ...
92 ]
93 Each element in the array reference describes one edge in the
95 memory cycle. 'REFTYPE' describes the type of the reference and is
96 one of 'SCALAR','ARRAY' or 'HASH'. $index is the index affected by
97 the reference, and is undef for a scalar, an integer for an array
98 reference, or a hash key for a hash. $reference is the memory
99 reference, and $reference_value is its dereferenced value. For
100 example, if the edge is an ARRAY, then the following relationship
101 holds:
102 $reference->[$index] eq $reference_value
104 The first element of the array reference is the $object_reference
106 that you pased to find_cycle() and may not be directly involved in
107 the cycle.
108 If a reference is a weak ref produced using Scalar::Util's weaken()
110 function then it won't contribute to cycles.
111 find_weakened_cycle($object_reference,[$callback])
113 The find_weakened_cycle() function will traverse the object
114 reference and print a report to STDOUT identifying any memory
115 cycles it finds, including any weakened cycles produced using
116 Scalar::Util's weaken().
117 If an optional callback code reference is provided, then this
119 callback will be invoked on each cycle that is found. The callback
120 will be passed an array reference pointing to a list of lists with
121 the following format:
122 $arg = [ ['REFTYPE',$index,$reference,$reference_value,$is_weakened],
124 ['REFTYPE',$index,$reference,$reference_value,$is_weakened],
125 ['REFTYPE',$index,$reference,$reference_value,$is_weakened],
126 ...
127 ]
128 Each element in the array reference describes one edge in the
130 memory cycle. 'REFTYPE' describes the type of the reference and is
131 one of 'SCALAR','ARRAY' or 'HASH'. $index is the index affected by
132 the reference, and is undef for a scalar, an integer for an array
133 reference, or a hash key for a hash. $reference is the memory
134 reference, and $reference_value is its dereferenced value.
135 $is_weakened is a boolean specifying if the reference is weakened
136 or not. For example, if the edge is an ARRAY, then the following
137 relationship holds:
138 $reference->[$index] eq $reference_value
140 The first element of the array reference is the $object_reference
142 that you pased to find_cycle() and may not be directly involved in
143 the cycle.
144 Cycle Report Formats
146 The default callback prints out a trace of each cycle it finds. You
147 can control the format of the trace by setting the package variable
148 $Devel::Cycle::FORMATTING to one of "raw," "cooked," or "roasted".
149 The "raw" format prints out anonymous memory references using standard
151 Perl memory location nomenclature. For example, a "Foo::Bar" object
152 that points to an ordinary hash will appear in the trace like this:
153 Foo::Bar=HASH(0x8124394)->{'phyllis'} => HASH(0x81b4a90)
155 The "cooked" format (the default), uses short names for anonymous
157 memory locations, beginning with "A" and moving upward with the magic
158 ++ operator. This leads to a much more readable display:
159 $Foo::Bar=B->{'phyllis'} => \%A
161 The "roasted" format is similar to the "cooked" format, except that
163 object references are formatted slightly differently:
164 $Foo::Bar::B->{'phyllis'} => \%A
166 If a reference is a weakened ref, then it will have a 'w->' prepended
168 to it, like this:
169 w-> $Foo::Bar::B->{'phyllis'} => \%A
171 For your convenience, $Devel::Cycle::FORMATTING can be imported:
173 use Devel::Cycle qw(:DEFAULT $FORMATTING);
175 $FORMATTING = 'raw';
176 Alternatively, you can control the formatting at compile time by
178 passing one of the options -raw, -cooked, or -roasted to "use" as
179 illustrated here:
180 use Devel::Cycle -raw;
182 Code references (closures)
184 If the PadWalker module is installed, Devel::Cycle will also report
185 cycles in code closures. If PadWalker is not installed and Devel::Cycle
186 detects a CODE reference in one of the data structures, it will warn
187 (once per data structure) that it cannot inspect the CODE unless
188 PadWalker is available. You can turn this warning off by passing -quiet
189 to Devel::Cycle at compile time:
190 use Devel::Cycle -quiet;
192
194 Test::Memory::Cycle Devel::Leak Scalar::Util
195
197 https://github.com/lstein/Devel-Cycle. Please contribute to the code
198 base by sending pull requests. Use GitHub for bug reports and feature
199 requests.
200
202 Lincoln Stein, <lincoln.stein@gmail.com>
203
205 Copyright (C) 2003-2014 by Lincoln Stein
206 This library is free software; you can redistribute it and/or modify it
208 under the same terms as Perl itself, either Perl version 5.8.2 or, at
209 your option, any later version of Perl 5 you may have available.
210perl v5.38.0 2023-07-20 Devel::Cycle(3)