NAME

Devel::DProfPP - Parse "Devel::DProf" output

SYNOPSIS

  use Devel::DProfPP;
  my $pp = Devel::DProfPP->new;

  Devel::DProfPP->new(
        file    => "../tmon.out",
        enter   => sub { my ($self, $sub_name)  = shift;
                         my $frame = ($self->stack)[-1];
                         print "\t" x $frame->height, $frame->sub_name;
                       }
  )->parse;

DESCRIPTION

This module takes the output file from Devel::DProf (typically tmon.out) and parses it. By hooking subroutines onto the "enter" and "leave" events, you can produce useful reports from the profiling data.

METHODS

new

    new(
        file    => $file,
        enter   => \&entersub_code,
        leave   => \&leavesub_code
    );

Creates a new parser object. All parameters are optional. See below for more information about what the enter and leave hooks can do.

parse

This parses the profiler output, running the enter and leave hooks, and gathering information about subroutine timings.

stack

During the parsing run, "$pp-"gt"stack" will return a list of "Devel::DProfPP::Frame" objects. (See below) These can be examined for the profile timings.

This returns a hash of the header information, whose keys are:

hz: The number of clock cycles per second; the times are measured in cycles and then converted into seconds later.
XS_VERSION: The version of the XS for the profiler.
over_utime
over_stime
over_rtime: The tested overhead of profiling, in user, system and real times. These are in cycles.
over_tests: The number of samples that generated the above overhead; this is usually 2000. So divide "over_utime" by "over_tests" and you'll find the user time overhead required to enter a subroutine. Take this off each subroutine enter and leave event, and you'll have the "real" user time of a subroutine call. "Devel::DProfPP" doesn't do this for you.
rrun_utime
rrun_stime
rrun_rtime: The user, system and real times (in cycles) for the whole program run.

HOOKS

The "enter" and "leave" hooks are called every time a subroutine is, predictable, entered or left. In each case, the parser and name of the subroutine are passed in as parameters to the hook, and everything else can be accessed through the parser object and the stack.

FRAME OBJECTS

The following methods are available on a "Devel::DProfPP::Frame" object:

times

inc_times

cum_times

These return the current execution time for a stack frame individually, for the stack frame and all of its descendants, and for all instances of this code.

These times are given in seconds, but DO NOT include compensation for subroutine enter/leave overheads. If you want to compensate for these, subtract the appropriate overhead value from "$pp->header".

height

The height of this stack frame - 1 for the first subroutine call on the stack, 2 for the second, and so on.

sub_name

The fully qualified name of this subroutine.

BUGS

Understanding how "dprofpp"'s overhead compensation code works is Not Easy and has meant that I haven't tried to apply overhead compensation in this module. All the data's there if you want to do it yourself. The numbers produced by "Devel::DProf" are pseudorandom anyway, so this omission should't make any real difference.

AUTHOR

Simon Cozens is the original author. Currently maintained by Steve Peters, "steve@fisharerojo.org"

LICENSE

You may distribute this module under the same terms as Perl itself.