1Devel::Cycle(3)       User Contributed Perl Documentation      Devel::Cycle(3)
2
3
4

NAME

6       Devel::Cycle - Find memory cycles in objects
7

SYNOPSIS

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
22         # output:
23
24         Cycle (1):
25                               $A->{'george'} => \%B
26                              $B->{'phyllis'} => \%A
27
28         Cycle (2):
29                               $A->{'george'} => \%B
30                                 $B->{'mary'} => \@A
31                                      $A->[3] => \%B
32
33         Cycle (3):
34                                 $A->{'fred'} => \@A
35                                      $A->[3] => \%B
36                              $B->{'phyllis'} => \%A
37
38         Cycle (4):
39                                 $A->{'fred'} => \@A
40                                      $A->[3] => \%B
41                                 $B->{'mary'} => \@A
42
43         # you can also check weakened references
44         weaken($test->{george}->{phyllis});
45         find_weakened_cycle($test);
46         exit 0;
47
48         # output:
49
50         Cycle (1):
51                               $A->{'george'} => \%B
52                                 $B->{'mary'} => \@C
53                                      $C->[3] => \%B
54
55         Cycle (2):
56                               $A->{'george'} => \%B
57                          w-> $B->{'phyllis'} => \%A
58
59         Cycle (3):
60                                 $A->{'fred'} => \@C
61                                      $C->[3] => \%B
62                                 $B->{'mary'} => \@C
63
64         Cycle (4):
65                                 $A->{'fred'} => \@C
66                                      $C->[3] => \%B
67                          w-> $B->{'phyllis'} => \%A
68

DESCRIPTION

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
75   EXPORT
76       The find_cycle() and find_weakened_cycle() subroutine are exported by
77       default.
78
79       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
83           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
88            $arg = [ ['REFTYPE',$index,$reference,$reference_value],
89                     ['REFTYPE',$index,$reference,$reference_value],
90                     ['REFTYPE',$index,$reference,$reference_value],
91                      ...
92                   ]
93
94           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
103              $reference->[$index] eq $reference_value
104
105           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
109           If a reference is a weak ref produced using Scalar::Util's weaken()
110           function then it won't contribute to cycles.
111
112       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
118           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
123            $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
129           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
139              $reference->[$index] eq $reference_value
140
141           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
145   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
150       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
154               Foo::Bar=HASH(0x8124394)->{'phyllis'} => HASH(0x81b4a90)
155
156       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
160               $Foo::Bar=B->{'phyllis'} => \%A
161
162       The "roasted" format is similar to the "cooked" format, except that
163       object references are formatted slightly differently:
164
165               $Foo::Bar::B->{'phyllis'} => \%A
166
167       If a reference is a weakened ref, then it will have a 'w->' prepended
168       to it, like this:
169
170               w-> $Foo::Bar::B->{'phyllis'} => \%A
171
172       For your convenience, $Devel::Cycle::FORMATTING can be imported:
173
174              use Devel::Cycle qw(:DEFAULT $FORMATTING);
175              $FORMATTING = 'raw';
176
177       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
181         use Devel::Cycle -raw;
182
183   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
191        use Devel::Cycle -quiet;
192

SEE ALSO

194       Test::Memory::Cycle Devel::Leak Scalar::Util
195

DEVELOPING

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

AUTHOR

202       Lincoln Stein, <lincoln.stein@gmail.com>
203
205       Copyright (C) 2003-2014 by Lincoln Stein
206
207       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.
210
211
212
213perl v5.38.0                      2023-07-20                   Devel::Cycle(3)
Impressum