1Devel::LeakGuard::ObjecUts(e3r)Contributed Perl DocumentDaetvieoln::LeakGuard::Object(3)
2
6 Devel::LeakGuard::Object - Scoped checks for object leaks
7
9 This document describes Devel::LeakGuard::Object version 0.08
10
12 # Track a single object
13 use Devel::LeakGuard::Object;
14 my $obj = Foo::Bar->new;
15 Devel::LeakGuard::Object::track($obj);
16 # Track every object
18 use Devel::LeakGuard::Object qw( GLOBAL_bless );
19 # Track every object, summary at exit
21 use Devel::LeakGuard::Object qw( GLOBAL_bless :at_end );
22 # Track a block of code, warning on leaks
24 leakguard {
25 # your potentially leaky code here
26 };
27 # Track a block of code, die on leaks
29 leakguard {
30 # your potentially leaky code here
31 }
32 on_leak => 'die';
33
35 This module provides tracking of objects, for the purpose of detecting
36 memory leaks due to circular references or innappropriate caching
37 schemes.
38 It is derived from, and backwards compatible with Adam Kennedy's
40 Devel::Leak::Object. Any errors are mine.
41 It works by overridding "bless" and adding a synthetic "DESTROY" method
43 to any tracked classes so that it can maintain a count of blessed
44 objects per-class.
45 Object tracking can be enabled:
47 • for an individual object
49 • for a block of code
51 • globally
53 Tracking an individual object
55 Track individual objects like this:
56 use Devel::LeakGuard::Object qw( track );
58 # Later...
60 track( my $obj = new Foo );
61 Tracking object leaks in a block of code
63 To detect any object leaks in a block of code:
64 use Devel::LeakGuard::Object qw( leakguard );
66 leakguard {
68 # your code here.
69 };
70 Tracking global object leaks
72 use Devel::LeakGuard::Object qw( GLOBAL_bless );
73 Finding out what leaked
75 If you use "leakguard" (recommended) then by default a warning is
76 thrown when leaks are detected. You can customise this behaviour by
77 passing options to "leakguard"; see the documentation for "leakguard"
78 for more information.
79 If you use "GLOBAL_bless" or "track" then you can also specify the
81 ":at_end" option
82 use Devel::LeakGuard::Object qw( GLOBAL_bless :at_end );
84 in which case a summary of leaks will be displayed at program exit.
86 Load early!
88 "Devel::LeakGuard::Object" can only track allocations of objects
89 compiled after it is loaded - so load it as early as possible.
90 What is a leak?
92 This module counts the number of blessed instances of each tracked
93 class. When we talk about a 'leak' what we really mean here is an
94 imbalance in the number of allocated objects across some boundary.
95 Using this definition we see a leak even in the case of expected
96 imbalances.
97 When interpreting the results you need to remember that it may be quite
99 legitimate for certain allocations to live beyond the scope of the code
100 under test.
101 You can use the various options that "leakguard" supports to filter out
103 such legitimate allocations that live beyond the life of the block
104 being checked.
105 Performance
107 As soon as "Devel::LeakGuard::Object" is loaded "bless" is overloaded.
108 That means that "bless" gets a little slower everywhere. When not
109 actually tracking the overloaded "bless" is quite fast - but still
110 around four times slower than the built-in "bless".
111 Bear in mind that "bless" is fast and unless your program is doing a
113 huge amount of blessing you're unlikely to notice a difference. On my
114 machine core bless takes around 0.5 μS and loading
115 "Devel::LeakGuard::Object" slows that down to around 2 μS.
116
118 "leakguard"
119 Run a block of code tracking object creation and destruction and report
120 any leaks at block exit.
121 At its simplest "leakguard" runs a block of code and warns if leaks are
123 found:
124 leakguard {
126 my $foo = Foo->new;
127 $foo->{me} = $foo; # leak
128 };
129 # Displays this warning:
131 Object leaks found:
132 Class Before After Delta
133 Foo 3 4 1
134 Detected at foo.pl line 23
135 If you really don't want to leak you can die instead of warning:
137 leakguard {
139 my $foo = Foo->new;
140 $foo->{me} = $foo; # leak
141 }
142 on_leak => 'die';
143 If you need to do something more complex you can pass a coderef to the
145 "on_leak" option:
146 leakguard {
148 my $foo = Foo->new;
149 $foo->{me} = $foo; # leak
150 my $bar = Bar->new;
151 $bar->{me} = $bar; # leak again
152 }
153 on_leak => sub {
154 my $report = shift;
155 for my $pkg ( sort keys %$report ) {
156 printf "%s %d %d\n", $pkg, @{ $report->{$pkg} };
157 }
158 # do something
159 };
160 In the event of a leak the sub will be called with a reference to a
162 hash. The keys of the hash are the names of classes that have leaked;
163 the values are refs to two-element arrays containing the bless count
164 for that class before and after the block so the example above would
165 print:
166 Foo 0 1
168 Bar 0 1
169 Options
171 Other options are supported. Here's the full list:
173 "on_leak"
175 What to do if a leak is detected. May be 'warn' (the default),
176 'die', 'ignore' or a code reference. If "on_leak" is set to
177 'ignore' no leak tracking will be performed.
178 "only"
180 If you need to concentrate on a subset of classes use "only" to
181 limit leak tracking to a subset of classes:
182 leakguard {
184 # do stuff
185 }
186 only => 'My::Stuff::*';
187 The pattern to match can be a string (with '*' as a shell-style
189 wildcard), a "Regexp", a coderef or a reference to an array of any
190 of the above. This (improbable) example illustrates all of these:
191 leakguard {
193 # do stuff
194 }
195 only => [
196 'My::Stuff::*',
197 qr{Leaky},
198 sub { length $_ > 20 }
199 ];
200 That would track classes beginning with 'My::Stuff::', containing
202 'Leaky' or whose length is greater than 20 characters.
203 "exclude"
205 To track all classes apart from a few exceptions use "exclude". The
206 "exclude" spec is like an "only" spec but classes that match will
207 be excluded from tracking.
208 "expect"
210 Sometimes a certain amount of 'leakage' is acceptable. Imagine, for
211 example, an application that maintains a single cached database
212 connection in a class called "My::DB". The connection is created on
213 demand and deleted after it has been used 100 times - to be created
214 again next time it's needed.
215 We could use "exclude" to ignore this class - but then we'd miss
217 the case where something goes wrong and we create 5 connections at
218 a time.
219 Using "exclude" we can specify that no more than one "My::DB"
221 should be created or destroyed:
222 leakguard {
224 # do stuff
225 }
226 expect => {
227 'My::DB' => [ -1, 1 ]
228 };
229 "leakstate"
231 Get the current allocation counts for all tracked objects. If
232 "GLOBAL_bless" is in force this will include all blessed objects. If
233 you are using the finer-grained tracking tools ("track" and
234 "leakguard") then only allocations that they cover will be included.
235 Returns a reference to a hash with package names as keys and allocation
237 counts as values.
238 "track"
240 Track an individual object. Tracking an object increases the allocation
241 count for its package by one. When the object is destroyed the
242 allocation count is decreased by one. Current allocation counts may be
243 retrieved using "leakstate".
244 If the object is reblessed into a different package the count for the
246 new package will be incremented and the count for the old package
247 decremented.
248 "status"
250 Print out a Devel::Leak::Object style summary of current object
251 allocations. If you
252 use Devel::LeakGuard::Object qw( GLOBAL_bless :at_end );
254 then "status" will be called at program exit to dump a summary of
256 outstanding allocations.
257
259 List::Util, Scalar::Util, Test::Differences, Test::More
260
262 Devel::Leak::Object
263
265 None reported.
266
268 Please report any bugs or feature requests via
269 "https://github.com/AndyA/Devel--LeakGuard--Object/issues".
270
272 Andy Armstrong "<andy@hexten.net>"
273 Based on code taken from Adam Kennedy's Devel::Leak::Object which
275 carries this copyright notice:
276 Copyright 2007 Adam Kennedy.
278 Rewritten from original copyright 2004 Ivor Williams.
280 Some documentation also copyright 2004 Ivor Williams.
282
284 Copyright (c) 2009-2015, Andy Armstrong "<andy@hexten.net>".
285 This module is free software; you can redistribute it and/or modify it
287 under the same terms as Perl itself. See perlartistic.
288perl v5.36.0 2023-01-20 Devel::LeakGuard::Object(3)