view release on metacpan or  search on metacpan

lib/Devel/WxProf.pm  view on Meta::CPAN

__END__

=head1 NAME

Devel::WxProf - heavy-weight subroutine profiler and graphical profile analyzer

=head1 SYNOPSIS

    perl -d:WxProf program.pl
    wxprofile tmon.out

    # or if you like it better:
    dprofpp

    # or even
    perl -d:DProf program.pl
    wxprofile tmon.out

=head1 DESCRIPTION

Devel::WxProf package is a heavy-weight subroutine profiler for perl.

It collects information on the execution time of a Perl script - more
specifically: on the subs called from that script.

To profile a Perl script run the perl interpreter with the
-d debugging switch. The profiler uses the debugging
hooks.  So to profile script test.pl the following command
should be used:

    perl -d:WxProf test.pl

When the script terminates the profiler will dump the profile information to
a file called wxmon.out.

Use L<wxprofile|wxprofile> to display the information collected.

Devel::WxProf uses the (new) output format of L<Devel::DProf|Devel::DProf>.
You may thus use dprofpp to analyze the data, or analyze data collected using
L<Devel::DProf|Devel::DProf>.

Note that real (wall) time is reported as user time, and system tyme is not
reported at all, which means that dprofpp is likely to produce slightly
different output for profile data created by Devel::WxProf and
L<Devel::DProf|Devel::DProf>.

L<Devel::DProf|Devel::DProf> usually reports times at 1/100s granularity, so
one-shot data collected by L<Devel::DProf|Devel::DProf> is likely to be
useless (and results largely random).

=head1 ENVIRONMENT

=over 4

=item C<PERL_DPROF_OUT_FILE_NAME>

Filename to save profile data to, default is F<tmon.out>

=back

=head1 BUGS AND LIMITATIONS

Many.

Devel::WxProf measures wall clock times. These may be happily inaccurate -
especially if run under a system with heavy load, or a program using
interactive dialogs. Wall clock (also called stopwatch) times do not
nesseccarily represnt the processing time required to run a program.

Devel::WxProf does not profile anonymous subroutines (yet).

Valid profiling data is not saved until the application terminates and runs
this modules END{} block. Applications which cause END{} blocks not to run
(such as call _exit or exec) will leave a corrupt and/or incomplete temporary
data file.

WxProf reports time in your system's high resolution timer's clock ticks -
usually micro- or nanoseconds. The exact times reported by WxProf are
badly inaccurate.

If the program being profiled contains subroutines which do not return in a
normal manner (such as by throwing an exception), the timing data is
estimated and may be attributed incorrectly. The time data might even get
corrupted.

WxProf (and wxprofile) are heavy-weight tools. Use with care. You should
not try to profile benchmarks with WxProf - try it on single runs instead.

=head1 SEE ALSO

    Devel::Profile
    Devel::DProfLB
    Devel::DProf
    dprofpp

=head1 DEVELOPEMENT

I wrote Devel::WxProf because I needed a fine-grained one-shot profiler
(and because I saw that cool treemap in kcachegrind). I actually wrote it
for myself. I'd be pleased if you find it useful, but I probably won't put
much time into bugfixes. Send me a test and a patch if you want to speed
things up. If you're really out for boosting development, I'll set up a
repository I can open up...

=head1 LICENSE AND COPYRIGHT

Copyright 2008 Martin Kutter.

Based on L<Devel::DProfLB|Devel::DProfLB> by Jeff Weisberg

This library is free software. You may distribute/modify it under
the same terms as perl itself

=head1 AUTHOR

Martin Kutter E<lt>martin.kutter fen-net.deE<gt>

=head1 REPOSITORY INFORMATION

 $Rev: 583 $
 $LastChangedBy: kutterma $