Test::LeakTrace(3) User Contributed Perl Documentation Test::LeakTrace(3)NAMETest::LeakTrace - Traces memory leaks
VERSION
This document describes Test::LeakTrace version 0.13.
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.
perl v5.14.0 2010-08-01 Test::LeakTrace(3)
