NAME

Test::LeakTrace - Traces memory leaks

VERSION

This document describes Test::LeakTrace version 0.05.

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;

not_leaked{
	# ...
} "description";

leaked_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.

TODO: writeing the document

INTERFACE

Exported functions

leaked_info { BLOCK }

Executes BLOCK and returns a list of leaked SVs and places where the SVs come from.

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), filename 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.

not_leaked { 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.

leaked_cmp_ok { BLOCK } $cmp_op, $number, ?$description

Tests that BLOCK leakes 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.

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;

leaked_cmp_ok{
	my $o = Some::Module->new();
	$o->something();
	$o->something_else();
} '<', 1;

DEPENDENCIES

Perl 5.8.1 or later, and a C compiler.

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 <gfuji(at)cpan.org>.

LICENSE AND COPYRIGHT

Copyright (c) 2009, Goro Fuji. Some rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Test::LeakTrace

perl -MCPAN -e shell
install Test::LeakTrace