NAME
Devel::Trace::Method - Track how your object methods interact
SYNOPSIS
use Devel::Trace::Method qw(
track_object_methods
track_method
fetch_trace
);
# configure your object for method tracking
track_object_methods( $self ); # in your new() method
# in each method call within your object, inform the method
# that you want it tracked
track_method( $self );
# retrieve the data
my @all = fetch_trace( $object ); # or $self
my @codeflow = fetch_trace( $obj, 'codeflow' );
my @stacktrace = fetch_trace( $obj, 'stacktrace' );DESCRIPTION
This module takes any object, and injects into it the ability to have it track itself through all of its progress. As of now, it creates an ordered stack trace, and a list of ordered method calls.
Note that I do have a rendering engine for both CLI and HTML, for the output, but I have not hooked them in yet.
FUNCTIONS
track_object_methods( OBJ )
Prepares and configures your object so that it can create and retain its own codeflow and stack trace data over time.
Takes an object as its only parameter, and returns the object.
This function should be called within your new() method, after blessing your object, and prior to returning it.
track_method( OBJ )
This function appends tracking data to what is currently saved for each method call that calls this function.
Currently, this function call must be manually listed in each method you want to track. It should be entered in all of your class methods, or the program flow won't make much sense ;)
Takes your $self object as the only parameter, and returns 0 upon success.
fetch_trace( OBJ, STRING )
Retrieves the stored data that had accumulated thus far in the run of your program. Can be called from within one of your methods, or by a program using one of your methods.
Takes an object as the first mandatory parameter. The second optional string parameter states which data you'd like returned:
'codeflow' -returns an array containing the list of methods
called, in the order they were called.
'stacktrace' -returns an array of hash references, where
each hash ref contains details of each method callGiven no optional parameters, the return is an array reference that contains an array reference for all the above types.
EXAMPLES
# print the stack trace
my @stack = fetch_trace( $obj, 'stacktrace' ); print Dumper \@stack;
$VAR1 = [ { 'sub' => 'Dude::say_hi', 'filename' => './dude.pl', 'caller' => 0, 'line' => 26, 'package' => 'Dude' }, { 'sub' => 'Dude::say_bye', 'filename' => './dude.pl', 'caller' => 'Dude::say_hi', 'line' => 46, 'package' => 'Dude' } ];
# print the code flow my @codeflow = fetch_trace( $obj, 'codeflow' ); print Dumper \@codeflow;
$VAR1 = [ '0 => Dude::say_hi', '1 => Dude::say_bye' ];
LIMITATIONS ETC
This is pure alpha software. Although the code works well, there are some serious limitations, and for large class hierarchies, there may be a significant performance hit. There is no internal method to bypass the work this module does (yet), so use it only for testing, or wrap the track_method() calls within an if($debug) type block.
Until I figure out how to get around it, the trace_method() call must be manually placed in all methods you want to keep track of.
Currently, we do not munge the symbol table of the object to create its own methods, therefore your object has to pass itself in as an argument. In the future, we'll have an option to have it either way.
AUTHOR Steve Bertrand, <steveb@cpan.org>
COPYRIGHT AND LICENSE
Copyright (C) 2012 by Steve Bertrand
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.12.4 or, at your option, any later version of Perl 5 you may have available.