.\" -*- 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::JA 3"
.TH Test::LeakTrace::JA 3 2023-07-26 "perl v5.38.0" "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::JA \- メモリリークを追跡する
.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{
\&                # ...
\&        } "description";
\&
\&        leaks_cmp_ok{
\&                # ...
\&        } \*(Aq<\*(Aq, 10;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
PerlのGCはリファレンスカウンタを用いたものなので，オブジェクトが開放されるタイミングが明確であることや体感速度が高速であることなど数々の利点があります。
その一方で，循環参照を開放できないこと，Cレベルでの操作でミスしやすいなど，問題点がいくつかあります。それらの問題点のほとんどはメモリリークに関することですから，メモリリークを追跡することは非常に重要な課題です。
.PP
\&\f(CW\*(C`Test::LeakTrce\*(C'\fRはメモリリークを追跡するためのいくつかのユーティリティと\f(CW\*(C`Test::Builder\*(C'\fRベースのテスト関数を提供します。このモジュールはPerlのメモリアロケーションシステムであるアリーナを走査するため，SVに関することであれば与えられたコードのどんなメモリリークでも検出できます。つまり，Perlレベルでの循環参照を始めとして，XSモジュールやPerl自身のバグによるメモリリークを追跡することができます。
.PP
ここで\fBリーク\fRとは，特定のスコープ内で新たに作成されて，そのスコープ終了後にも残っている値を意味します。これは，新たに作成されたグローバルな値やPerlが暗黙のうちに作成するキャッシュの値も含みます。たとえば，リーク追跡を行っている最中に新たに名前つきサブルーチンを定義すれば，それはリークとみなされます。また，継承したメソッドを呼び出したり，オブジェクトを作成したりするだけで様々なキャッシュが生成され，リークが報告される可能性があります。
.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
\&\fIBLOCK\fRを実行し，追跡結果をリストで返します。
結果はリークした値のリファレンス，ファイル名，行番号の三要素を持つ配列，つまり\f(CW\*(C`[$ref, $file, $line]\*(C'\fRのリストとなっています。
.PP
なお，この関数はPerl内部で使用する値を返す可能性があります。そのような内部用の値を変更するとPerl実行環境に致命的な影響を与える可能性があるので注意してください。また，配列やハッシュの要素として，リファレンスではない配列やハッシュそれ自体が含まれる可能性があります。そのような値は通常Perlレベルで操作することができません。たとえば\f(CW\*(C`Data::Dumper\*(C'\fRなどで出力することはできません。
.PP
\fR\f(CI\*(C`leaked_refs { BLOCK }\*(C'\fR\fI\fR
.IX Subsection "leaked_refs { BLOCK }"
.PP
\&\fIBLOCK\fRを実行し，リークしたSVのリファレンスのリストを返します。
.PP
\&\f(CW\*(C`map{ $_\->[0] } leaked_info{ BLOCK }\*(C'\fRと同じですが，より高速です。
.PP
\fR\f(CI\*(C`leaked_count { BLOCK }\*(C'\fR\fI\fR
.IX Subsection "leaked_count { BLOCK }"
.PP
\&\fIBLOCK\fRを実行し，リークしたSVのリファレンスの個数を返します。
.PP
\&\f(CWleaked_info()\fRと\f(CWleaked_refs()\fRもスカラコンテキストでは個数を返しますが，
\&\f(CWleaked_count()\fRはコンテキストに依存しません。
.PP
\fR\f(CI\*(C`leaktrace { BLOCK } ?($mode | \e&callback)\*(C'\fR\fI\fR
.IX Subsection "leaktrace { BLOCK } ?($mode | &callback)"
.PP
\&\fIBLOCK\fRを実行し，その中で起きたメモリリークを\f(CW*STDERR\fRに報告します。
.PP
メモリリークの報告は\fR\f(CI$mode\fR\fI\fRで指定したモードに従います。
受け付ける\fI\fR\f(CI$mode\fR\fI\fRは以下の通りです：
.IP \-simple 4
.IX Item "-simple"
デフォルトのモードです。リークしたSVの型とアドレス，ファイル名，行番号を報告します。
.IP \-sv_dump 4
.IX Item "-sv_dump"
\&\fB\-simple\fRに加えて，\f(CWsv_dump()\fRでSVの中身をダンプします。
これは，\f(CWDevel::Peek::Dump()\fRの出力とほぼ同じです。
.IP \-lines 4
.IX Item "-lines"
\&\fB\-simple\fRに加えて，リークしていると見られる行の周辺を出力します。
.IP \-verbose 4
.IX Item "-verbose"
\&\fB\-simple\fRと\fB\-sv_dump\fRと\fB\-lines\fRの全てを出力します。
.PP
より細かな制御のためにコールバックを指定することもできます。
\&\fI\e&callback\fRはリークしたSV毎に呼び出され，その引数はリークしたSVのリファレンス，ファイル名，行番号の3つです。
.PP
\fR\f(CI\*(C`no_leaks_ok { BLOCK } ?$description\*(C'\fR\fI\fR
.IX Subsection "no_leaks_ok { BLOCK } ?$description"
.PP
\&\fIBLOCK\fRにメモリリークがないことテストします。
これは\f(CW\*(C`Test::Builder\*(C'\fRベースのテスト関数です。
.PP
なお，\fIBLOCK\fRは複数回実行されます。これは，初回の実行でキャッシュを用意する可能性を考慮するためです。
.PP
\fR\f(CI\*(C`leaks_cmp_ok { BLOCK } $cmp_op, $count, ?$description\*(C'\fR\fI\fR
.IX Subsection "leaks_cmp_ok { BLOCK } $cmp_op, $count, ?$description"
.PP
\&\fIBLOCK\fRのメモリリーク数と特定の数値を比較するテストを行います。
これは\f(CW\*(C`Test::Builder\*(C'\fRベースのテスト関数です。
.PP
なお，\fIBLOCK\fRは複数回実行されます。これは，初回の実行でキャッシュを用意する可能性を考慮するためです。
.SS "Script interface"
.IX Subsection "Script interface"
\&\f(CW\*(C`Devel::LeakTrace\*(C'\fRと同様に，スクリプトのリーク追跡のために\f(CW\*(C`Test::LeakTrace::Script\*(C'\fRが提供されます。\f(CW\*(C`use Test::LeakTrace::Script\*(C'\fR宣言の引数は\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"
以下はモジュールのメモリリークをチェックするテストスクリプトのテンプレートです。
.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 GUTS
.IX Header "GUTS"
\&\f(CW\*(C`Test::LeakTrace\*(C'\fRはアリーナを走査します。アリーナとは，Perlが作成するSVのためのメモリアロケーションシステムであり，\fIsv.c\fRで実装されています。
アリーナの走査には\fIsv.c\fRにある\f(CWS_visit()\fRのコードを元にしたマクロを用いています。
.PP
さて，アリーナを走査すれば，メモリリークの検出そのものは簡単にできるように思えます。まず，コードブロックを実行する前に一度アリーナを走査し，全てのSVに「使用済み」の印を付けておきます。次に，コードブロック実行後にもう一度アリーナを走査し，使用済みの印がついていないSVがあれば，それはコードブロック内で作成され，開放されなかったSVだと考えます。あとはそれを報告するだけです。実際には，SVに対して使用済みの印を付けるスペースがないため，インサイドアウト法を応用して外部のコンテナに使用済みの印を保存します。
これを仮にPerlコードで書くと以下のようになります。
.PP
.Vb 5
\&        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 \*(Aqleaked count: \*(Aq, scalar @leaked;
.Ve
.PP
リークしたSVを得るだけならこの方法で十分です。実際，\f(CWleaked_refs()\fRと\f(CWleaked_count()\fRはこのような方法でリークしたSVやその個数を調べています。
.PP
しかし，リークしたSVのステートメントの情報，つまりファイル名や行番号を得るためにはこれだけでは不十分です。Perl 5.10以降にはSVが作成されたときのステートメント情報を追跡する機能があるのですが，この機能を利用するためには，コンパイラオプションとしてに\f(CW\*(C`\-DDEBUG_LEAKING_SCALARS\*(C'\fRを与えてPerlをビルドしなければなりません。
.PP
そこで，\f(CW\*(C`Test::LeakTrace\*(C'\fRでは拡張可能な\f(CW\*(C`PL_runops\*(C'\fRを利用して，Perl VMがOPコードを実行する1ステートメント毎にアリーナを走査し，ステートメント情報を記録します。これは，1ステートメント毎にマーク＆スイープのような処理を行うのに等しく，非常に時間が掛かります。しかし，Perlを特殊な条件の下でビルドする必要もなく，バージョンに依存した機能もほとんど使用しないため，多くの環境で動かすことができます。
.PP
また，\f(CWno_leaks_ok()\fRのようなテスト関数はまず\f(CWleaked_count()\fRでリークしたSVの個数を得てから，必要に応じてリークした位置を特定するために\f(CWleaktrace()\fRを実行するため，テストが成功する限りは時間の掛かる追跡処理はしません。
.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は\f(CW\*(C`Devel::Cover\*(C'\fRと一緒に動かすことはできません。
したがって，\f(CW\*(C`Devel::Cover\*(C'\fRの元で動いていることが検出されると，テスト関数は何も行わずにテストをパスさせます。
.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
sv.c.
.SH AUTHOR
.IX Header "AUTHOR"
Goro Fuji <gfuji(at)cpan.org>.
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright (c) 2009, Goro Fuji. Some rights reserved.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.