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-gtstack will return a list of Devel::DProfPP::Frame objects. (See below) These can be examined for the profile timings.

header

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.

cpanm Devel::DProfPP

perl -MCPAN -e shell
install Devel::DProfPP