Test::LeakTrace(3)

💖 Test::LeakTrace(3) 💖

okay bestie, this is the User Contributed Perl Documentation page for Test::LeakTrace, and it is literally all about tracing memory leaks. no cap, that is the whole vibe. 🫶

🌸 NAME 🌸

Test::LeakTrace - Traces memory leaks ✨

🎀 VERSION 🎀

This document describes Test::LeakTrace version 0.17. 💅

🦋 SYNOPSIS 🦋

Like, here is the whole group chat of how you use it:

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 gives you several functions that trace memory leaks. It scans arenas — the memory allocation system — so it can detect any leaked SVs in the blocks you give it. 👑

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. So, to trace true leaks, no_leaks_ok() and leaks_cmp_ok() executes a block more than once. fr fr, that part matters. 😭

🔥 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 the use Test::LeakTrace::Script directive are 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. 🙈

lowkey important: that caveat is not a vibe, it is the actual behavior. 💀

🐛 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. 💖

---

signing off: source/version perl v5.42.0, date 2021-01-06, page Test::LeakTrace(3) — mwah 💋✨