Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Test::LeakTrace(3)    User Contributed Perl Documentation   Test::LeakTrace(3)

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.

perl v5.32.0			  2017-06-17		    Test::LeakTrace(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | INTERFACE | EXAMPLES | DEPENDENCIES | CAVEATS | BUGS | SEE ALSO | AUTHOR | LICENSE AND COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Test::LeakTrace&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help