NAME

Devel::TrackObjects - Track use of objects

SYNOPSIS

cmdline

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

inside

 use Devel::TrackObjects qr/^IO::/;
 use Devel::TrackObjects '-verbose','track_object';
 use Devel::TrackObjects '-size','-sizediff','-timestamp';
 use IO::Socket;
 ...
 my $sock = IO::Socket::INET->new...
 ...
 my $foreign = get_some_object_from_xs();
 track_object( $foreign, "This was created in XS" );
 ...
 Devel::TrackObjects->show_tracked;

DESCRIPTION

Devel::TrackObjects redefines bless and thus tracks the creation of objects 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.

-timestamp

Includes timestamp in messages.

-size

Includes size of objects in detailed output. Needs Devel::Size installed.

-sizediff

Includes size and difference in size to last output and first output.

-noend

Don't show remaining tracked objects at END.

-out \&func

Use given function (code reference) for output instead of printing to STDERR. This function is called as $func-($prefix,$line)> for simple output and $func-($prefix,\@lines)> for detailled output. It is expected to add time stamps when needed, i.e. option -timestamp is ignored.

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

track_object( OBJECT, [ INFO ] )

This tracks the given OBJECT manually. This can be used in cases, where one only wants to track single objects and not all objects for a given class or if the object was created outside of perl and thus could not be tracked automatically.

If an additional INFO string is given it will be saved and shown from show_tracked.

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" and the last one ends with "LEAK$PREFIX". Each line in between has the information about one object, including the stringification of REF, FILE and LINE of creation.

If option -size was given it will include the size and total_size of the object (see Devel::Size for meaning of size and total_size). If option -sizediff was given it will also add the difference of size between the last call and the first call.

COPYRIGHT

Steffen Ullrich Steffen_Ullrich-at-genua-dot-de