1Devel::LeakGuard::ObjecUts(e3r)Contributed Perl DocumentDaetvieoln::LeakGuard::Object(3)
2
3
4

NAME

6       Devel::LeakGuard::Object - Scoped checks for object leaks
7

VERSION

9       This document describes Devel::LeakGuard::Object version 0.08
10

SYNOPSIS

12         # Track a single object
13         use Devel::LeakGuard::Object;
14         my $obj = Foo::Bar->new;
15         Devel::LeakGuard::Object::track($obj);
16
17         # Track every object
18         use Devel::LeakGuard::Object qw( GLOBAL_bless );
19
20         # Track every object, summary at exit
21         use Devel::LeakGuard::Object qw( GLOBAL_bless :at_end );
22
23         # Track a block of code, warning on leaks
24         leakguard {
25             # your potentially leaky code here
26         };
27
28         # Track a block of code, die on leaks
29         leakguard {
30             # your potentially leaky code here
31         }
32         on_leak => 'die';
33

DESCRIPTION

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
39       It is derived from, and backwards compatible with Adam Kennedy's
40       Devel::Leak::Object. Any errors are mine.
41
42       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
46       Object tracking can be enabled:
47
48       •   for an individual object
49
50       •   for a block of code
51
52       •   globally
53
54   Tracking an individual object
55       Track individual objects like this:
56
57         use Devel::LeakGuard::Object qw( track );
58
59         # Later...
60         track( my $obj = new Foo );
61
62   Tracking object leaks in a block of code
63       To detect any object leaks in a block of code:
64
65         use Devel::LeakGuard::Object qw( leakguard );
66
67         leakguard {
68             # your code here.
69         };
70
71   Tracking global object leaks
72         use Devel::LeakGuard::Object qw( GLOBAL_bless );
73
74   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
80       If you use "GLOBAL_bless" or "track" then you can also specify the
81       ":at_end" option
82
83         use Devel::LeakGuard::Object qw( GLOBAL_bless :at_end );
84
85       in which case a summary of leaks will be displayed at program exit.
86
87   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
91   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
98       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
102       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
106   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
112       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

INTERFACE

118   "leakguard"
119       Run a block of code tracking object creation and destruction and report
120       any leaks at block exit.
121
122       At its simplest "leakguard" runs a block of code and warns if leaks are
123       found:
124
125         leakguard {
126             my $foo = Foo->new;
127             $foo->{me} = $foo; # leak
128         };
129
130         # 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
136       If you really don't want to leak you can die instead of warning:
137
138         leakguard {
139             my $foo = Foo->new;
140             $foo->{me} = $foo; # leak
141         }
142         on_leak => 'die';
143
144       If you need to do something more complex you can pass a coderef to the
145       "on_leak" option:
146
147         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
161       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
167         Foo 0 1
168         Bar 0 1
169
170       Options
171
172       Other options are supported. Here's the full list:
173
174       "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
179       "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
183             leakguard {
184                 # do stuff
185             }
186             only => 'My::Stuff::*';
187
188           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
192             leakguard {
193                 # do stuff
194             }
195             only => [
196                 'My::Stuff::*',
197                 qr{Leaky},
198                 sub { length $_ > 20 }
199             ];
200
201           That would track classes beginning with 'My::Stuff::', containing
202           'Leaky' or whose length is greater than 20 characters.
203
204       "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
209       "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
216           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
220           Using "exclude" we can specify that no more than one "My::DB"
221           should be created or destroyed:
222
223             leakguard {
224                 # do stuff
225             }
226             expect => {
227                 'My::DB' => [ -1, 1 ]
228             };
229
230   "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
236       Returns a reference to a hash with package names as keys and allocation
237       counts as values.
238
239   "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
245       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
249   "status"
250       Print out a Devel::Leak::Object style summary of current object
251       allocations. If you
252
253         use Devel::LeakGuard::Object qw( GLOBAL_bless :at_end );
254
255       then "status" will be called at program exit to dump a summary of
256       outstanding allocations.
257

DEPENDENCIES

259       List::Util, Scalar::Util, Test::Differences, Test::More
260

SEE ALSO

262       Devel::Leak::Object
263

INCOMPATIBILITIES

265       None reported.
266

BUGS AND LIMITATIONS

268       Please report any bugs or feature requests via
269       "https://github.com/AndyA/Devel--LeakGuard--Object/issues".
270

AUTHOR

272       Andy Armstrong  "<andy@hexten.net>"
273
274       Based on code taken from Adam Kennedy's Devel::Leak::Object which
275       carries this copyright notice:
276
277         Copyright 2007 Adam Kennedy.
278
279         Rewritten from original copyright 2004 Ivor Williams.
280
281         Some documentation also copyright 2004 Ivor Williams.
282
284       Copyright (c) 2009-2015, Andy Armstrong "<andy@hexten.net>".
285
286       This module is free software; you can redistribute it and/or modify it
287       under the same terms as Perl itself. See perlartistic.
288
289
290
291perl v5.36.0                      2023-01-20       Devel::LeakGuard::Object(3)
Impressum