Devel::TrackObjects 0.2

Devel::TrackObjects is a Perl module to track use of objects.

SYNOPSIS

cmdline

perl -MDevel::TrackObjects=/^IO::/ server.pl

inside

use Devel::TrackObjects qr/^IO::/;
use Devel::TrackObjects -verbose;
use IO::Socket;
...
my $sock = IO::Socket::INET->new...
...

Devel::TrackObjects->show_tracked;

Devel::TrackObjects redefines bless and thus tracks the creation of objectsi by putting weak references to the object into a list. It can be specified which classes to track.

At the end of the program it will print out infos about the still existing objects (probably leaking). The same info can be print out during the run using show_tracked.

IMPORTANT

The Module must be loaded as early as possible, because it cannot redefine bless in already loaded modules. See import how to load it so that it redefines bless.

METHODS

The following class methods are defined.

import ( COND|OPTIONS )

Called from use.

COND is a list of conditions. A condition is either a regex used as a match for a classname, a string used to match the class with exactly this name or a reference to a subroutine, which gets called to decide if the class should get tracked (must return TRUE).

Special is if the condition is /regex/. In this case it will be compiled as a regex. This is used, because on the perl cmdline one cannot enter compiled regex.
If the item is a string starting with "-" it will be interpreted as an option. Valid options are:

-verbose

Output from show_tracked will be more verbose, e.g it will use show_tracked_detailed instead of show_tracked_compact.

-noend

Dont show remaining tracked objects at END.

-debug

Will switch an internal debugging.

If conditions are given it will redefine CORE::GLOBAL::bless unless it was already redefined by this module.

That means you do not pay a performance penalty if you just include the module, only if conditions are given it will redefine bless.

show_tracked ( [ PREFIX ] )

If -verbose was set in import it will call show_tracked_detailed, otherwise show_tracked_compact.

This method will be called at END unless -noend was specified in import.

show_tracked_compact ( [ PREFIX ] )

Will create a hash containing all tracked classes and the current object count for the class.

If the caller wants to get something in return it will return a reference to this hash, otherwise it will print out the information in a single line to STDERR starting with "LEAK$PREFIX".

show_tracked_detailed ( [ PREFIX ] )

If the caller wants something in return it will give it a reference to an array containing array-refs with [ REF,FILE,LINE ], where REF is the weak reference to the object, FILE and LINE the file name and line number, where the object was blessed.

If the calling context is void it will print these information to STDERR. The first line will start with "LEAK$PREFIX", the next ones with "--" and the last one again with "LEAK$PREFIX".