NAME

       Test::LeakTrace - Traces memory leaks

VERSION

       This document describes Test::LeakTrace version 0.15.

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.