NAME

VERSION

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{
                # ...
        } "description";

        leaks_cmp_ok{
                # ...
        } '<', 10;

DESCRIPTION

"Test::LeakTrce"はメモリリークを追跡するためのいくつかのユーティリティと"Test::Builder"ベースのテスト関数を提供します。このモジュールはPerlのメモリアロケーションシステムであるアリーナを走査するため，SVに関することであれば与えられたコードのどんなメモリリークでも検出できます。つまり，Perlレベルでの循環参照を始めとして，XSモジュールやPerl自身のバグによるメモリリークを追跡することができます。

ここでリークとは，特定のスコープ内で新たに作成されて，そのスコープ終了後にも残っている値を意味します。これは，新たに作成されたグローバルな値やPerlが暗黙のうちに作成するキャッシュの値も含みます。たとえば，リーク追跡を行っている最中に新たに名前つきサブルーチンを定義すれば，それはリークとみなされます。また，継承したメソッドを呼び出したり，オブジェクトを作成したりするだけで様々なキャッシュが生成され，リークが報告される可能性があります。

INTERFACE

        $ 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

        #!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;

GUTS

さて，アリーナを走査すれば，メモリリークの検出そのものは簡単にできるように思えます。まず，コードブロックを実行する前に一度アリーナを走査し，全てのSVに「使用済み」の印を付けておきます。次に，コードブロック実行後にもう一度アリーナを走査し，使用済みの印がついていないSVがあれば，それはコードブロック内で作成され，開放されなかったSVだと考えます。あとはそれを報告するだけです。実際には，SVに対して使用済みの印を付けるスペースがないため，インサイドアウト法を応用して外部のコンテナに使用済みの印を保存します。 これを仮にPerlコードで書くと以下のようになります。

        my %used_sv;
        foreach my $sv(@ARENA){
                $used_sv{$sv}++;
        }
        $block->();

        my @leaked
        foreach my $sv(@ARENA){
                if(not exists $used_sv{$sv}){
                        push @leaked, $sv;
                }
        }
        say 'leaked count: ', scalar @leaked;

リークしたSVを得るだけならこの方法で十分です。実際，"leaked_refs()"と"leaked_count()"はこのような方法でリークしたSVやその個数を調べています。

しかし，リークしたSVのステートメントの情報，つまりファイル名や行番号を得るためにはこれだけでは不十分です。Perl 5.10以降にはSVが作成されたときのステートメント情報を追跡する機能があるのですが，この機能を利用するためには，コンパイラオプションとしてに"-DDEBUG_LEAKING_SCALARS"を与えてPerlをビルドしなければなりません。

そこで，"Test::LeakTrace"では拡張可能な"PL_runops"を利用して，Perl VMがOPコードを実行する1ステートメント毎にアリーナを走査し，ステートメント情報を記録します。これは，1ステートメント毎にマーク＆スイープのような処理を行うのに等しく，非常に時間が掛かります。しかし，Perlを特殊な条件の下でビルドする必要もなく，バージョンに依存した機能もほとんど使用しないため，多くの環境で動かすことができます。

また，"no_leaks_ok()"のようなテスト関数はまず"leaked_count()"でリークしたSVの個数を得てから，必要に応じてリークした位置を特定するために"leaktrace()"を実行するため，テストが成功する限りは時間の掛かる追跡処理はしません。

DEPENDENCIES

CAVEATS

BUGS

Please report any bugs or feature requests to the author.

SEE ALSO

Devel::LeakTrace::Fast.

Test::TraceObject.

Test::Weak.

For guts:

perlguts.

perlhack.

sv.c.

AUTHOR

LICENSE AND COPYRIGHT

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