---
name: "Test::LeakTrace"
section: "3pm"
platform: "linux"
package: "perl-test-leaktrace"
version: "0.17-8"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/Test::LeakTrace"
---

# Test::LeakTrace(3pm)

Traces memory leaks

## NAME

Test::LeakTrace - Traces memory leaks

## VERSION

This document describes Test::LeakTrace version 0.17.

## 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 *$mode*s 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.