.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Test::LeakTrace 3pm"
.TH Test::LeakTrace 3pm 2024-01-10 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Test::LeakTrace \- Traces memory leaks
.SH VERSION
.IX Header "VERSION"
This document describes Test::LeakTrace version 0.17.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&    use Test::LeakTrace;
\&
\&    # simple report
\&    leaktrace{
\&        # ...
\&    };
\&
\&    # verbose output
\&    leaktrace{
\&        # ...
\&    } \-verbose;
\&
\&    # with callback
\&    leaktrace{
\&        # ...
\&    } sub {
\&        my($ref, $file, $line) = @_;
\&        warn "leaked $ref from $file line\en";
\&    };
\&
\&    my @refs = leaked_refs{
\&        # ...
\&    };
\&    my @info = leaked_info{
\&        # ...
\&    };
\&
\&    my $count = leaked_count{
\&        # ...
\&    };
\&
\&    # standard test interface
\&    use Test::LeakTrace;
\&
\&    no_leaks_ok{
\&        # ...
\&    } \*(Aqno memory leaks\*(Aq;
\&
\&    leaks_cmp_ok{
\&        # ...
\&    } \*(Aq<\*(Aq, 10;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Test::LeakTrace\*(C'\fR 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.
.PP
\&\fBLeaked SVs\fR 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, \f(CWno_leaks_ok()\fR and \f(CWleaks_cmp_ok()\fR
executes a block more than once.
.SH INTERFACE
.IX Header "INTERFACE"
.SS "Exported functions"
.IX Subsection "Exported functions"
\fR\f(CI\*(C`leaked_info { BLOCK }\*(C'\fR\fI\fR
.IX Subsection "leaked_info { BLOCK }"
.PP
Executes \fIBLOCK\fR and returns a list of leaked SVs and places where the SVs
come from, i.e. \f(CW\*(C`[$ref, $file, $line]\*(C'\fR.
.PP
\fR\f(CI\*(C`leaked_refs { BLOCK }\*(C'\fR\fI\fR
.IX Subsection "leaked_refs { BLOCK }"
.PP
Executes \fIBLOCK\fR and returns a list of leaked SVs.
.PP
\fR\f(CI\*(C`leaked_count { BLOCK }\*(C'\fR\fI\fR
.IX Subsection "leaked_count { BLOCK }"
.PP
Executes \fIBLOCK\fR and returns the number of leaked SVs.
.PP
\fR\f(CI\*(C`leaktrace { BLOCK } ?($mode | \e&callback)\*(C'\fR\fI\fR
.IX Subsection "leaktrace { BLOCK } ?($mode | &callback)"
.PP
Executes \fIBLOCK\fR and reports leaked SVs to \f(CW*STDERR\fR.
.PP
Defined \fR\f(CI$mode\fR\fI\fRs are:
.IP \-simple 4
.IX Item "-simple"
Default. Reports the leaked SV identity (type and address), file name and line number.
.IP \-sv_dump 4
.IX Item "-sv_dump"
In addition to \fB\-simple\fR, dumps the sv content using \f(CWsv_dump()\fR,
which also implements \f(CWDevel::Peek::Dump()\fR.
.IP \-lines 4
.IX Item "-lines"
In addition to \fB\-simple\fR, prints suspicious source lines.
.IP \-verbose 4
.IX Item "-verbose"
Both \fB\-sv_dump\fR and \fB\-lines\fR.
.PP
\fR\f(CI\*(C`no_leaks_ok { BLOCK } ?$description\*(C'\fR\fI\fR
.IX Subsection "no_leaks_ok { BLOCK } ?$description"
.PP
Tests that \fIBLOCK\fR does not leaks SVs. This is a test function
using \f(CW\*(C`Test::Builder\*(C'\fR.
.PP
Note that \fIBLOCK\fR is called more than once. This is because
\&\fIBLOCK\fR might prepare caches which are not memory leaks.
.PP
\fR\f(CI\*(C`leaks_cmp_ok { BLOCK } $cmp_op, $number, ?$description\*(C'\fR\fI\fR
.IX Subsection "leaks_cmp_ok { BLOCK } $cmp_op, $number, ?$description"
.PP
Tests that \fIBLOCK\fR leaks a specific number of SVs. This is a test
function using \f(CW\*(C`Test::Builder\*(C'\fR.
.PP
Note that \fIBLOCK\fR is called more than once. This is because
\&\fIBLOCK\fR might prepare caches which are not memory leaks.
.PP
\fR\f(CIcount_sv()\fR\fI\fR
.IX Subsection "count_sv()"
.PP
Counts all the SVs in the arena.
.SS "Script interface"
.IX Subsection "Script interface"
Like \f(CW\*(C`Devel::LeakTrace\*(C'\fR \f(CW\*(C`Test::LeakTrace::Script\*(C'\fR is provided for whole scripts.
.PP
The arguments of \f(CW\*(C`use Test::LeakTrace::Script\*(C'\fR directive is the same as \f(CWleaktrace()\fR.
.PP
.Vb 2
\&    $ 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) = @_;
\&        # ...
\&    };
\&
\&    # ...
.Ve
.SH EXAMPLES
.IX Header "EXAMPLES"
.SS "Testing modules"
.IX Subsection "Testing modules"
Here is a test script template that checks memory leaks.
.PP
.Vb 5
\&    #!perl \-w
\&    use strict;
\&    use constant HAS_LEAKTRACE => eval{ require Test::LeakTrace };
\&    use Test::More HAS_LEAKTRACE ? (tests => 1) : (skip_all => \*(Aqrequire Test::LeakTrace\*(Aq);
\&    use Test::LeakTrace;
\&
\&    use Some::Module;
\&
\&    leaks_cmp_ok{
\&        my $o = Some::Module\->new();
\&        $o\->something();
\&        $o\->something_else();
\&    } \*(Aq<\*(Aq, 1;
.Ve
.SH DEPENDENCIES
.IX Header "DEPENDENCIES"
Perl 5.8.1 or later, and a C compiler.
.SH CAVEATS
.IX Header "CAVEATS"
\&\f(CW\*(C`Test::LeakTrace\*(C'\fR does not work with \f(CW\*(C`Devel::Cover\*(C'\fR and modules which install
their own \f(CW\*(C`runops\*(C'\fR routines, or the perl executor. So if the test functions of
this module detect strange \f(CW\*(C`runops\*(C'\fR routines, they do nothing and report okay.
.SH BUGS
.IX Header "BUGS"
No bugs have been reported.
.PP
Please report any bugs or feature requests to the author.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Devel::LeakTrace.
.PP
Devel::LeakTrace::Fast.
.PP
Test::TraceObject.
.PP
Test::Weak.
.PP
For guts:
.PP
perlguts.
.PP
perlhack.
.PP
\&\fIsv.c\fR.
.SH AUTHOR
.IX Header "AUTHOR"
Goro Fuji(gfx) <gfuji(at)cpan.org>.
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright (c) 2009\-2010, Goro Fuji(gfx). All rights reserved.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.