# Test::NoLeaks

![Build status](https://api.travis-ci.org/binary-com/perl-Test-NoLeaks.png "Build status")

# NAME

Test::NoLeaks - Memory and file descriptor leak detector

# VERSION

0.04

# SYNOPSYS

    use Test::NoLeaks;

    test_noleaks (
        code          => sub{
          # code that might leak
        },
        track_memory  => 1,
        track_fds     => 1,
        passes        => 2,
        warmup_passes => 1,
        tolerate_hits => 0,
    );

    Sample output:
    # pass 1, leaked: 225280 bytes 0 file descriptors
    # pass 36, leaked: 135168 bytes 0 file descriptors
    # pass 52, leaked: 319488 bytes 0 file descriptors
    # pass 84, leaked: 135168 bytes 0 file descriptors
    # pass 98, leaked: 155648 bytes 0 file descriptors
    not ok 1214 - Leaked 970752 bytes (5 hits) 0 file descriptors

    test_noleaks (
        code          => sub { ... },
        track_memory  => 1,
        passes        => 2,
    );

    # old-school way
    use Test::More;
    use Test::NoLeaks qw/noleaks/;
    ok noleaks(
        code          => sub { ... },
        track_memory  => ...,
        track_fds     => ...,
        passes        => ...,
        warmup_passes => ...,
      ), "non-leaked code description";

# DESCRIPTION

It is hard to track memory leaks. There are a lot of perl modules (e.g.
[Test::LeakTrace](https://metacpan.org/pod/Test::LeakTrace)), that try to **detect** and **point** leaks. Unfortunately,
they do not always work, and they are rather limited because they are not
able to detect leaks in XS-code or external libraries.

Instead of examining perl internals, this module offers a bit naive empirical
approach: let the suspicious code to be launched in infinite loop
some time and watch (via tools like `top`)if the memory consumption by
perl process increses over time. If it does, while it is expected to
be constant (stabilized), then, surely, there are leaks.

This approach is able only to **detect** and not able to **point** them. The
module `Test::NoLeaks` implements the general idea of the approach, which
might be enough in many cases.

# INTERFACE

### `test_noleaks`

### `noleaks`

The mandatory hash has the following members

- `code`

    Suspicious for leaks subroutine, that will be executed multiple times.

- `track_memory`
- `track_fds`

    Track memory or file descriptor leaks. At leas one of them should be
    specified.

    In **Unices**, every socket is file descriptor too, so, `track_fds`
    will be able to track unclosed sockets, i.e. network connections.

- `passes`

    How many times `code` should be executed. If memory leak is too small,
    number of passes should be large enough to trigger additional pages
    allocation for perl process, and the leak will be detected.

    Page size is 4kb on linux, so, if `code` leaks 4 bytes on every
    pass, then `1024` passes should be specified.

    In general, the more passes are specified, the more chance to
    detect possible leaks.

    It is good idea to initally define `passes` to some large number,
    e.g. `10_000` to be sure, that the suspicious code leaks, but then
    decrease to some smaller number, enough to produce test fail report,
    i.e. enough to produces 3-5 memory hits (additional pages allocations).
    This will speed up tests execution and will save CO2 atmospheric
    emissions a little bit.

    Default value is `100`. Minimal value is `2`.

- `warmup_passes`

    How many times the `code` should be executed before module starts
    tracking resources consumption on executing the `code` `passes`
    times.

    If you have caches, memoizes etc., then `warmup_passes` is your
    friend.

    Default value is `0`.

- `tolerate_hits`

    How many passes, which considered leaked, should be ingnored, i.e.
    maximal number of possible false leak reports.

    Even if your code has no leaks, it might cause perl interpreter
    allocate additional memory pages, e.g. due to memory fragmentation.
    Those allocations are legal, and should not be treated as leaks.

    Use this **only** when memory leaks are already fixed, but there
    are still false leak reports from `test_leak`. This value expected
    to be small enough, i.e. `1` or `2`. For additional assurance, please,
    increase `passes` value, if `tolarate_hits` is non-zero.

    Default value is `0`.

# MEMORY LEAKS TESTING TECHNIQUES

`Test::NoLeaks` can be used to test web applications for memory leaks.

Let's consider you have the following suspicious code

    sub might_leak {
      my $t = Test::Mojo->new('MyApp');
      $t->post_ok('/search.json' => form => {q => 'Perl'})
          ->status_is(200);
      ...;
    }

    test_noleaks (
        code          => \&might_leak,
        track_memory  => 1,
        track_fds     => 1,
        passes        => 1000,
    );

The `might_leak` subroutine isn't optimal for leak detection, because it
mixes infrastructure-related code (application) with request code. Let's
consider, that there is a leak: every request creates some data and puts
it into application, but forgets to do clean up. As soon as the application
is re-created on every pass, the leaked data might be destroyed together
with the application, and leak might remain undetected.

So, the code under test should look much more production like, i.e.

    my $t = Test::Mojo->new('MyApp');
    ok($t);
    sub might_leak {
      $t->post_ok('/search.json' => form => {q => 'Perl'})
          ->status_is(200);
      ...;
    }

That way web-application is created only once, and leaks will be tracked
on request-related code.

Anyway, `might_leak` still wrong, because it unintentionally leaks due to
use of direct or indirect [Test::More](https://metacpan.org/pod/Test::More) functions, like `ok` or
`post_ok`. They should not be used; if you still need to assert, that
`might_leak` works propertly, you can use `BAIL_OUT` subroutine,
to cancel any further testing, e.g.

    sub might_leak {
      my $got = some_function_might_leak;
      my $expected = "some_value";
      BAIL_OUT('some_function_might_leak does not work propertly!')
        unless $got eq $expected;
    }

Please, **do not** use `test_noleaks` more then once per test file. Consider
the following example:

    # (A)
    test_noleaks(
      code => &does_not_leak_but_consumes_large_amount_of_memory,
      ...,
    )

    # (B)
    test_noleaks(
      code => &leaks_but_consumes_small_amount_of_memory,
      ...
    )

In A-case OS already allocated large amount of memory for Perl interpreter.
In case-B perl might just re-use them, without allocating new ones, and
this will be false negative, i.e. memory leak might **not** be reported.

# LIMITATIONS

- Currently it works propertly only on **Linux**

    Patches or pull requests to support other OSes are welcome.

- The module will not work propertly in **fork**ed child

    It seems a little bit strange to use `test_noleaks` or
    `noleaks` in forked child, but if you really need that, please,
    send PR.

# SEE ALSO

[Test::MemoryGrowth](https://metacpan.org/pod/Test::MemoryGrowth)

# SOURCE CODE

[GitHub](https://github.com/binary-com/perl-Test-NoLeaks)

# AUTHOR

binary.com, `<perl at binary.com>`

# BUGS

Please report any bugs or feature requests to
[https://github.com/binary-com/perl-Test-NoLeaks/issues](https://github.com/binary-com/perl-Test-NoLeaks/issues).

# LICENSE AND COPYRIGHT

Copyright (C) 2015 binary.com

This program is free software; you can redistribute it and/or modify it
under the terms of the the Artistic License (2.0). You may obtain a
copy of the full license at:

[http://www.perlfoundation.org/artistic\_license\_2\_0](http://www.perlfoundation.org/artistic_license_2_0)

Any use, modification, and distribution of the Standard or Modified
Versions is governed by this Artistic License. By using, modifying or
distributing the Package, you accept this license. Do not use, modify,
or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made
by someone other than you, you are nevertheless required to ensure that
your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service
mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge
patent license to make, have made, use, offer to sell, sell, import and
otherwise transfer the Package with respect to any patent claims
licensable by the Copyright Holder that are necessarily infringed by the
Package. If you institute patent litigation (including a cross-claim or
counterclaim) against any party alleging that the Package constitutes
direct or contributory patent infringement, then this Artistic License
to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER
AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES.
THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY
YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR
CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR
CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.