1Test::LeakTrace(3) User Contributed Perl Documentation Test::LeakTrace(3)
2
3
4
6 Test::LeakTrace - Traces memory leaks
7
9 This document describes Test::LeakTrace version 0.15.
10
12 use Test::LeakTrace;
13
14 # simple report
15 leaktrace{
16 # ...
17 };
18
19 # verbose output
20 leaktrace{
21 # ...
22 } -verbose;
23
24 # with callback
25 leaktrace{
26 # ...
27 } sub {
28 my($ref, $file, $line) = @_;
29 warn "leaked $ref from $file line\n";
30 };
31
32 my @refs = leaked_refs{
33 # ...
34 };
35 my @info = leaked_info{
36 # ...
37 };
38
39 my $count = leaked_count{
40 # ...
41 };
42
43 # standard test interface
44 use Test::LeakTrace;
45
46 no_leaks_ok{
47 # ...
48 } 'no memory leaks';
49
50 leaks_cmp_ok{
51 # ...
52 } '<', 10;
53
55 "Test::LeakTrace" provides several functions that trace memory leaks.
56 This module scans arenas, the memory allocation system, so it can
57 detect any leaked SVs in given blocks.
58
59 Leaked SVs are SVs which are not released after the end of the scope
60 they have been created. These SVs include global variables and internal
61 caches. For example, if you call a method in a tracing block, perl
62 might prepare a cache for the method. Thus, to trace true leaks,
63 "no_leaks_ok()" and "leaks_cmp_ok()" executes a block more than once.
64
66 Exported functions
67 "leaked_info { BLOCK }"
68
69 Executes BLOCK and returns a list of leaked SVs and places where the
70 SVs come from, i.e. "[$ref, $file, $line]".
71
72 "leaked_refs { BLOCK }"
73
74 Executes BLOCK and returns a list of leaked SVs.
75
76 "leaked_count { BLOCK }"
77
78 Executes BLOCK and returns the number of leaked SVs.
79
80 "leaktrace { BLOCK } ?($mode | \&callback)"
81
82 Executes BLOCK and reports leaked SVs to *STDERR.
83
84 Defined $modes are:
85
86 -simple
87 Default. Reports the leaked SV identity (type and address), file
88 name and line number.
89
90 -sv_dump
91 In addition to -simple, dumps the sv content using "sv_dump()",
92 which also implements "Devel::Peek::Dump()".
93
94 -lines
95 In addition to -simple, prints suspicious source lines.
96
97 -verbose
98 Both -sv_dump and -lines.
99
100 "no_leaks_ok { BLOCK } ?$description"
101
102 Tests that BLOCK does not leaks SVs. This is a test function using
103 "Test::Builder".
104
105 Note that BLOCK is called more than once. This is because BLOCK might
106 prepare caches which are not memory leaks.
107
108 "leaks_cmp_ok { BLOCK } $cmp_op, $number, ?$description"
109
110 Tests that BLOCK leaks a specific number of SVs. This is a test
111 function using "Test::Builder".
112
113 Note that BLOCK is called more than once. This is because BLOCK might
114 prepare caches which are not memory leaks.
115
116 "count_sv()"
117
118 Counts all the SVs in the arena.
119
120 Script interface
121 Like "Devel::LeakTrace" "Test::LeakTrace::Script" is provided for whole
122 scripts.
123
124 The arguments of "use Test::LeakTrace::Script" directive is the same as
125 "leaktrace()".
126
127 $ TEST_LEAKTRACE=-sv_dump perl -MTest::LeakTrace::Script script.pl
128 $ perl -MTest::LeakTrace::Script=-verbose script.pl
129
130 #!perl
131 # ...
132
133 use Test::LeakTrace::Script sub{
134 my($ref, $file, $line) = @_;
135 # ...
136 };
137
138 # ...
139
141 Testing modules
142 Here is a test script template that checks memory leaks.
143
144 #!perl -w
145 use strict;
146 use constant HAS_LEAKTRACE => eval{ require Test::LeakTrace };
147 use Test::More HAS_LEAKTRACE ? (tests => 1) : (skip_all => 'require Test::LeakTrace');
148 use Test::LeakTrace;
149
150 use Some::Module;
151
152 leaks_cmp_ok{
153 my $o = Some::Module->new();
154 $o->something();
155 $o->something_else();
156 } '<', 1;
157
159 Perl 5.8.1 or later, and a C compiler.
160
162 "Test::LeakTrace" does not work with "Devel::Cover" and modules which
163 install their own "runops" routines, or the perl executor. So if the
164 test functions of this module detect strange "runops" routines, they do
165 nothing and report okay.
166
168 No bugs have been reported.
169
170 Please report any bugs or feature requests to the author.
171
173 Devel::LeakTrace.
174
175 Devel::LeakTrace::Fast.
176
177 Test::TraceObject.
178
179 Test::Weak.
180
181 For guts:
182
183 perlguts.
184
185 perlhack.
186
187 sv.c.
188
190 Goro Fuji(gfx) <gfuji(at)cpan.org>.
191
193 Copyright (c) 2009-2010, Goro Fuji(gfx). All rights reserved.
194
195 This library is free software; you can redistribute it and/or modify it
196 under the same terms as Perl itself.
197
198
199
200perl v5.30.1 2020-01-30 Test::LeakTrace(3)