NAME¶
Test::LeakTrace - Traces memory leaks
VERSION¶
This document describes Test::LeakTrace version 0.14.
SYNOPSIS¶
use Test::LeakTrace;
# simple report
leaktrace{
# ...
};
# verbose output
leaktrace{
# ...
} -verbose;
# with callback
leaktrace{
# ...
} sub {
my($ref, $file, $line) = @_;
warn "leaked $ref from $file line\n";
};
my @refs = leaked_refs{
# ...
};
my @info = leaked_info{
# ...
};
my $count = leaked_count{
# ...
};
# standard test interface
use Test::LeakTrace;
no_leaks_ok{
# ...
} 'no memory leaks';
leaks_cmp_ok{
# ...
} '<', 10;
DESCRIPTION¶
"Test::LeakTrace" provides several functions that trace memory leaks.
This module scans arenas, the memory allocation system, so it can detect any
leaked SVs in given blocks.
Leaked SVs are SVs which are not released after the end of the scope they
have been created. These SVs include global variables and internal caches. For
example, if you call a method in a tracing block, perl might prepare a cache
for the method. Thus, to trace true leaks, "no_leaks_ok()" and
"leaks_cmp_ok()" executes a block more than once.
INTERFACE¶
Exported functions¶
"leaked_info { BLOCK }"
Executes
BLOCK and returns a list of leaked SVs and places where the SVs
come from, i.e. "[$ref, $file, $line]".
"leaked_refs { BLOCK }"
Executes
BLOCK and returns a list of leaked SVs.
"leaked_count { BLOCK }"
Executes
BLOCK and returns the number of leaked SVs.
"leaktrace { BLOCK } ?($mode | \&callback)"
Executes
BLOCK and reports leaked SVs to *STDERR.
Defined
$modes are:
- -simple
- Default. Reports the leaked SV identity (type and address), file name and
line number.
- -sv_dump
- In addition to -simple, dumps the sv content using
"sv_dump()", which also implements
"Devel::Peek::Dump()".
- -lines
- In addition to -simple, prints suspicious source lines.
- -verbose
- Both -sv_dump and -lines.
"no_leaks_ok { BLOCK } ?$description"
Tests that
BLOCK does not leaks SVs. This is a test function using
"Test::Builder".
Note that
BLOCK is called more than once. This is because
BLOCK
might prepare caches which are not memory leaks.
"leaks_cmp_ok { BLOCK } $cmp_op, $number,
?$description"
Tests that
BLOCK leaks a specific number of SVs. This is a test function
using "Test::Builder".
Note that
BLOCK is called more than once. This is because
BLOCK
might prepare caches which are not memory leaks.
"count_sv()"
Counts all the SVs in the arena.
Script interface¶
Like "Devel::LeakTrace" "Test::LeakTrace::Script" is
provided for whole scripts.
The arguments of "use Test::LeakTrace::Script" directive is the same
as "leaktrace()".
$ TEST_LEAKTRACE=-sv_dump perl -MTest::LeakTrace::Script script.pl
$ perl -MTest::LeakTrace::Script=-verbose script.pl
#!perl
# ...
use Test::LeakTrace::Script sub{
my($ref, $file, $line) = @_;
# ...
};
# ...
EXAMPLES¶
Testing modules¶
Here is a test script template that checks memory leaks.
#!perl -w
use strict;
use constant HAS_LEAKTRACE => eval{ require Test::LeakTrace };
use Test::More HAS_LEAKTRACE ? (tests => 1) : (skip_all => 'require Test::LeakTrace');
use Test::LeakTrace;
use Some::Module;
leaks_cmp_ok{
my $o = Some::Module->new();
$o->something();
$o->something_else();
} '<', 1;
DEPENDENCIES¶
Perl 5.8.1 or later, and a C compiler.
CAVEATS¶
"Test::LeakTrace" does not work with "Devel::Cover" and
modules which install their own "runops" routines, or the perl
executor. So if the test functions of this module detect strange
"runops" routines, they do nothing and report okay.
BUGS¶
No bugs have been reported.
Please report any bugs or feature requests to the author.
SEE ALSO¶
Devel::LeakTrace.
Devel::LeakTrace::Fast.
Test::TraceObject.
Test::Weak.
For guts:
perlguts.
perlhack.
sv.c.
AUTHOR¶
Goro Fuji(gfx) <gfuji(at)cpan.org>.
LICENSE AND COPYRIGHT¶
Copyright (c) 2009-2010, Goro Fuji(gfx). All rights reserved.
This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.