objecttracker(3)

NAME

Devel::ObjectTracker - Track object life to detect memory
leaks

SYNOPSIS

perl5 -d:ObjectTracker test.pl

DESCRIPTION

Debug module to find where perl objects (or arrays, hashes
and globs) are created by checking for objects passed to
and/or returned from subs, and monitoring when they are
destroyed via destructor subs. This can help detect mem
ory leaks caused by objects being left behind in your pro
grams when they shouldn't be.

The main output is stored in a file which logs the first
time a memory reference is seen with datetime, current
session number (starts at 1), object type, call stack
etc., and whether the object was first seen returned from
a sub or passed as an argument. Details are also logged
whenever an object is destroyed. This includes the date
time, session and call stack when the object was created.

The subroutine Devel::ObjectTracker::output_details out puts details on the currently existing objects on demand.
These details contain date/time, session, call stack, etc.
when the object was created.

EXAMPLES

When started ObjectTracker will output all object cre
ation/destruction in the log file ObjectTracker.log with a session ID of 1.

At a suitable point in your prog the sub Devel::Object Tracker::output_details should be called which will output a list of all current objects to a file Object_
Tracker_details_1.txt and then it will increment the ses sion ID to 2.

You should then carry out the operations being studied.
All object creation/destruction will now be recorded in
the log file with session ID of 2.

After the operation you should call Devel::Object Tracker::output_details again. This will output a list of all current objects to a file ObjectTracker_details_2.txt and then it will increment the session ID to 3.

A look at the details file ObjectTracker_details_2.txt will show any objects that were created during sessions 1
and 2. From the date/time, session and call stack you can
see when and where they were created. This can highlight
objects which are still in existence and shouldn't be.

Multiple sessions can be used to good effect in complex
programs either with output each time as above or sepa
rately incremented using the sub Devel::Object Tracker::increment_session

OPTIONS

ObjectTracker has some variables which can be used during
your script to affect what gets tracked.

� By default it will look for new objects in all subs.: $Devel::ObjectTracker::sub_match can be used to
defined a subroutine name pattern within which to look
for new objects. Note it will always check for
destructors (=~ /DESTROY$/).
� By default it will look for objects of all classes.: $Devel::ObjectTracker::class_match can be used to
defined a class name pattern.
� $Devel::ObjectTracker::class_exclude is used to refine: the class selection. By default this is set to
(HASH|ARRAY|GLOB) to exclude hashes, arrays and globs. If set to '' (blank) hashes, arrays and globs will be
included.; Note this takes precedence over the matching.
� The output to STDOUT can be adjusted by changing: $Devel::ObjectTracker::verbose as follows:

0 = print nothing
1 = print file creation, session ID etc. (default)
2 = print summary details upon object creation/de

struction
3 = print subroutine calls as well as object details; � The log file name can be changed by setting
$Devel::ObjectTracker::log_file. The default is
ObjectTracker.log in the current directory.; � The details file name can be changed by setting
$Devel::ObjectTracker::details_file. The token <NN>
will be replaced by the current session number (before
it is incremented). The default is Object_
Tracker_details_<NN>.txt in the current directory.; � Object monitoring can be switched on and off in your
programs by $Devel::ObjectTracker::enable. The
default is 1 (on).; � The whether a file header is printed is controlled by
$Devel::ObjectTracker::print_header. The default is 1
(yes).; � The output file beginning of line is set by
$Devel::ObjectTracker::bol. The default is nothing.
Set to "; � The output file value seperator is set by
$Devel::ObjectTracker::delim. The default is tab
(). Set to "; � The output file end of line is set by $Devel::Object
Tracker::eol. The default is a single newline (0.
Set to "; � The stack format line is set by $Devel::Object
Tracker::stack_format. This can contain tokens of
<LEVEL>, <PACK>, <FILE>, <LINE>, <CALLSUB>, <SUBNAME>, <HASARGS>, <WANTARRAY> which are replaced as follows:

LEVEL = the call level (starts at 0)
PACK = package
FILE = file name
LINE = line number
CALLSUB = the calling sub
SUBNAME = the called sub
HASARGS = as for caller()
WANTARRAY = as for caller()

The default is "<FILE>(<SUBNAME>) l=<LINE>".; � The stack seperator is set by $Devel::Object
Tracker::stack_delim. The default is "; ".; These variables can be put in a file called .objecttracker in the current directory as in the following example:

$Devel::ObjectTracker::class_exclude = '';
$Devel::ObjectTracker::class_match = '.';
$Devel::ObjectTracker::sub_match = '^(Mysubs|Oth

erSubs)::';
$Devel::ObjectTracker::log_file = 'mylogfile';
$Devel::ObjectTracker::details_file = 'myde

tails_<NN>.txt';; will set ObjectTracker to track hashes, arrays and globs
as well as objects but only in subroutines that match pat
tern ^(Mysubs|OtherSubs)::. The log output will be in mylogfile and details will be output to mydetails_1.txt, mydetails_2.txt, etc.

NOTES

� Memory references/Objects are often seen first in: unexpected places. For example as hash arguments to
subs which are called within the constructor or after
unpacking by Storable::thaw etc.; See also Exists as similarly objects are often seen
seemingly for the first time when called below
destructors.
� A sub UNIVERSAL::DESTROY is defined to catch destroys: of objects which do not have destructors defined them
selves. If the program defines this sub itself then
this should get overridden however this could produce
confusing results.
� It uses the debug hook DB::sub to look for memory ref: erences returned from subroutine calls, passed as
arguments and checks for destructors.
� Enabling/disabling monitoring and using subroutine: patterns only affects checking for new objects.
Destruction is always monitored.
� As every subroutine call is being intercepted and the: arguments and return values being analysed it obvi
ously adds a performance overhead. Furthermore it is
using considerable amounts of memory keeping track of
the object memory details. Expect performance to be
at least 3 times as slow depending on your platform
and size of program.; Note also that the output files can be huge.
� Tied hashes produce confusing results.
� ObjectTracker has been tested on perl 5.6.1 and 5.5005: on SGI Irix and Win32 (using SiePerl)
See also BUGS below

FUNCTIONS

output_details()

This subroutine outputs details on the currently existing
objects. It creates files in the current directory named
(by default) ObjectTracker_details_1.txt, Object_ Tracker_details_2.txt, etc. according to the current ses sion number. This function increments the session number
after each call (via increment_session)

This should be called at suitable points in your program
and the resultant files can be checked to see if there are
any objects which shouldn't still be in existence. It
will show the date/time, session ID and the call stack
when the object was created.

log_checkpoint()

This subroutine should be called at suitable points in
your program to record a checkpoint in the log file.

increment_session()

This can be used to independently increment the session ID
which is used to record details in the main log file and
name the output_details files.

FILE FORMATS

The output file formats are designed to be used in a
spreadsheet. By default they have a single header line
followed by data with values are separated by tab ()
with a single newline (0 at the end of each line.

ObjectTracker.log

This file logs the details of object creation and destruc
tion. The fields are as follows:

ObjectNo: The sequence number of the object (starts at 1). Only
set for new objects where Source ne DES.
DateTime: The local date/time the object is first seen or
destroyed.
Session: current session number (starts at 1)
Sub The subroutine called.: Will be set to NO_DESTRUCTOR if the test program has no destructor for the object concerned.
Source: Where the object is seen as follows:

Ret = first seen returned from a sub.
Arg = first seen as an arg.
DES = the sub is a destructor.; See also Exists as objects can sometimes be seen when
called from within destructors
Position: The argument or return value position (1=first)
Class: Object Class or HASH, ARRAY or GLOB
Ref The memory address of the object.
Exists: Object existance info as follows:; Y the object/ref has been seen before. Only applies
to Source=DES; N the object/ref has not been seen before. Only
applies to Source=DES; de the call stack contains a destructor subroutine
(sub =~ /DESTROY$/)
Stack: The current call stack. See OPTIONS for content.
CrDateTime: The local date/time the object was first seen. Only
output where Source=DES.
CrDateTime: The datetime when object first seen. Only output where
Source=DES.
CrSession: The session when object first seen. Only output where
Source=DES.
CrStack: The call stack when object first seen. Only output
where Source=DES.
ObjectTracker_details_<NN>.txt
This file is produced on demand by the subroutine "Devel::ObjectTracker::output_details". In the file name <NN> is replaced by the current session number which starts at 1.
The fields are as follows, see desciptions under Object_ Tracker.log for full details:
CrObjectNo: The creation number of the object.
CrDateTime: The local date/time the object was first seen.
CrSession: Session number when object first seen.
CrSub: Subroutine name called when object first seen.
CrSource: The source when object first seen.
Position: The argument or return value position when object
first seen.
CrClass: Object Class when object first seen.
CrRef: The memory address of the object when first seen.
CrStack: Call stack when object first seen.

INSTALLATION

The usual:: perl Makefile.PL
make
make test
make install
Should install fine via the CPAN module.

BUGS

COPYRIGHT

This module is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.

Because this module is distributed free of charge, there
is no warranty for this module to the extent permitted by
the applicable law. This module is provided "as is" with
out warranty of any kind, either expressed or implied,
including but not limited to the implied warranties of
merchantability and fitness for a particular purpose. The
entire risk as to the quality and performance of this mod
ule rests with you. Should this module prove defective,
you assume the cost of all necessary servicing, repair or
correction. In no event unless required by the applicable
law will the copyright holder, or any other party who may
modify and/or redistribute the program or this module be
liable to you for damages, including any general, special,
incidental or consequential damages arising out of the use
or inability to use this module (including but not limited
to loss of data or data being rendered inaccurate or
losses sustained by you or third parties) or a failure of
this module to operate with any other program even if such
holder or other party has been advised of the possibility
of such damages

Siemens Business Services

AUTHOR

John Clutterbuck, john.clutterbuck@sbs.siemens.co.uk

docs.sk

komplexný repozitár dokumentácie

Pozri tiež