Tracking an individual object

  use Devel::LeakGuard::Object qw( track );

  # Later...
  track( my $obj = new Foo );

Tracking object leaks in a block of code

  use Devel::LeakGuard::Object qw( leakguard );

  leakguard {
    # your code here.
  };

Tracking global object leaks

  use Devel::LeakGuard::Object qw( GLOBAL_bless );

Finding out what leaked

If you use "GLOBAL_bless" or "track" then you can also specify the ":at_end" option

  use Devel::LeakGuard::Object qw( GLOBAL_bless :at_end );

in which case a summary of leaks will be displayed at program exit.

Load early!

What is a leak?

When interpreting the results you need to remember that it may be quite legitimate for certain allocations to live beyond the scope of the code under test.

You can use the various options that "leakguard" supports to filter out such legitimate allocations that live beyond the life of the block being checked.

Performance

Bear in mind that "bless" is fast and unless your program is doing a huge amount of blessing you're unlikely to notice a difference. On my machine core bless takes around 0.5 IXS and loading "Devel::LeakGuard::Object" slows that down to around 2 IXS.

"leakguard"

At its simplest "leakguard" runs a block of code and warns if leaks are found:

  leakguard {
    my $foo = Foo->new;
    $foo->{me} = $foo; # leak
  };

  # Displays this warning:
  Object leaks found:
    Class Before  After  Delta
    Foo        3      4      1
  Detected at foo.pl line 23

If you really don't want to leak you can die instead of warning:

  leakguard {
    my $foo = Foo->new;
    $foo->{me} = $foo; # leak
  }
  on_leak => 'die';

If you need to do something more complex you can pass a coderef to the "on_leak" option:

  leakguard {
    my $foo = Foo->new;
    $foo->{me} = $foo; # leak
    my $bar = Bar->new;
    $bar->{me} = $bar; # leak again
  }
  on_leak => sub {
    my $report = shift;
    for my $pkg ( sort keys %$report ) {
      printf "%s %d %d\n", $pkg, @{ $report->{$pkg} };
    }
    # do something
  };

In the event of a leak the sub will be called with a reference to a hash. The keys of the hash are the names of classes that have leaked; the values are refs to two-element arrays containing the bless count for that class before and after the block so the example above would print:

  Foo 0 1
  Bar 0 1

Options

Other options are supported. Here's the full list:

"on_leak"

What to do if a leak is detected. May be 'warn' (the default), 'die', 'ignore' or a code reference. If "on_leak" is set to 'ignore' no leak tracking will be performed.

"only"

If you need to concentrate on a subset of classes use "only" to limit leak tracking to a subset of classes:

  leakguard {
    # do stuff
  }
  only => 'My::Stuff::*';
    

The pattern to match can be a string (with '*' as a shell-style wildcard), a "Regexp", a coderef or a reference to an array of any of the above. This (improbable) example illustrates all of these:

  leakguard {
    # do stuff
  }
  only => [
    'My::Stuff::*', 
    qr{Leaky}, 
    sub { length $_ > 20 } 
  ];
    

That would track classes beginning with 'My::Stuff::', containing 'Leaky' or whose length is greater than 20 characters.

"exclude"

To track all classes apart from a few exceptions use "exclude". The "exclude" spec is like an "only" spec but classes that match will be excluded from tracking.

"expect"

Sometimes a certain amount of 'leakage' is acceptable. Imagine, for example, an application that maintains a single cached database connection in a class called "My::DB". The connection is created on demand and deleted after it has been used 100 times - to be created again next time it's needed.

We could use "exclude" to ignore this class - but then we'd miss the case where something goes wrong and we create 5 connections at a time.

Using "exclude" we can specify that no more than one "My::DB" should be created or destroyed:

  leakguard {
    # do stuff
  }
  expect => {
    'My::DB' => [ -1, 1 ] 
  };
    

"leakstate"

Returns a reference to a hash with package names as keys and allocation counts as values.

"track"

If the object is reblessed into a different package the count for the new package will be incremented and the count for the old package decremented.

"status"

  use Devel::LeakGuard::Object qw( GLOBAL_bless :at_end );

then "status" will be called at program exit to dump a summary of outstanding allocations.