1Test::LeakTrace(3)    User Contributed Perl Documentation   Test::LeakTrace(3)
2
3
4

NAME

6       Test::LeakTrace - Traces memory leaks
7

VERSION

9       This document describes Test::LeakTrace version 0.13.
10

SYNOPSIS

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

DESCRIPTION

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

INTERFACE

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

EXAMPLES

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

DEPENDENCIES

159       Perl 5.8.1 or later, and a C compiler.
160

CAVEATS

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

BUGS

168       No bugs have been reported.
169
170       Please report any bugs or feature requests to the author.
171

SEE ALSO

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

AUTHOR

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.12.2                      2010-08-01                Test::LeakTrace(3)
Impressum