Benchmark::TimeTick
package Benchmark::TimeTick;
use 5.006;
use strict;
use warnings;
use Exporter;
use File::Basename;
our @ISA = qw(Exporter);
our @EXPORT_OK = qw(timetick);
our $VERSION = '0.01';
my @Tix; # Where we keep the time ticks
our %Opt; # Global option setting interface
my $Epoch = $^T; # Point from which times are measured
sub import
{
my $class = $_[0];
eval { require Time::HiRes };
$Epoch = _current_time() if $Opt{reset_start};
unless ($Opt{suppress_initial})
{
my $prog = basename($0);
timetick("Timeticker for $prog starting");
}
$class->export_to_level(1, @_);
}
sub timetick
{
my $tag = pop;
$Opt{format_tick_tag} and $tag = $Opt{format_tick_tag}->($tag);
push @Tix, [ _current_time() - $Epoch, $tag ];
}
sub _current_time
{
exists &Time::HiRes::time ? Time::HiRes::time() : time;
}
sub report
{
unless ($Opt{suppress_report})
{
&{ $Opt{format_report} || \&_format_report }(@Tix);
}
@Tix = ();
}
sub _format_report
{
printf("%7.4f %s\n", @$_) for @_;
}
sub end
{
unless ($Opt{suppress_final})
{
my $prog = basename($0);
timetick("Timeticker for $prog finishing");
}
report();
}
END { end() }
1;
__END__
=head1 NAME
Benchmark::TimeTick - Keep a tally of times at different places in your program
=head1 SYNOPSIS
use Benchmark::TimeTick qw(timetick);
# Your code...
timetick("Starting phase three");
# More of your code...
=head1 DESCRIPTION
C<Benchmark::TimeTick> provides a quick and convenient way of
instrumenting a program to find out how long it took to reach various
points. Just use the module and call the C<timetick()> method whenever
you want to mark the time at a point in your program. When the
program ends, a report will be output giving the times at which each
point was reached.
The times will be recorded using C<Time::HiRes::time()> if
L<Time::HiRes> is available, otherwise C<time()> will be used. (Since
C<time()> has one-second granularity this is unlikely to be useful.)
=head1 CONFIGURATION
You can customize the action of L<Benchmark::TimeTick> via
the package hash C<%Benchmark::TimeTick::Opt>. Recognized keys are:
=over 4
=item suppress_initial
If true, do not put an initial entry in the report when the
module is loaded.
=item suppress_final
If true, do not put a final entry in the report when the
program terminates.
=item reset_start
If true, report all times relative to the time that C<Benchmark::Time-
Tick> was loaded rather than the actual start of the program.
=item format_tick_tag
If set, should be a reference to a subroutine that will take as
input a C<$tag> passed to C<timetick()> and return the actual tag
to be used. Can be helpful for applying a lengthy transformation
to every tag while keeping the calling code short.
=item format_report
If set, should be a reference to a subroutine that will take as
input a list of time ticks for reporting. Each list element will be
a reference to an array containing the time and the tag respectively.
The default C<format_report> callback is:
sub { printf("%7.4f %s\n", @$_) for @_ }
=item suppress_report
If true, do not output a report when C<report()> is called; just
reset the time tick list instead.
=back
For either C<suppress_initial> or C<reset_start> to be effective,
they must be set in C<BEGIN> blocks before this module is C<use>d.
=head1 METHODS
=over 4
=item Benchmark::TimeTick::timetick($tag)
Record the time at this point of the program and label it with
the string C<$tag>.
=item Benchmark::TimeTick::report()
Output a report (unless C<suppress_report> is set) and reset
the time tick list.
=item Benchmark::TimeTick::end()
Add a final time tick (unless C<suppress_final> is set), and output a
report. Called by default when the program finishes.
=back
=head2 Optional Exports
C<Benchmark::TimeTick::timetick()> will be exported on demand.
This is recommended for the sake of brevity.
=head1 EXAMPLE
BEGIN { $Benchmark::TimeTick::Opt{suppress_initial} = 1 }
use Benchmark::TimeTick qw(timetick);
# ... time passes
timetick("Phase 2");
# ... more time passes, program ends
Output from L<Benchmark::TimeTick>:
0.7524 Phase 2
0.8328 Timeticker for testprog finishing
=head1 AUTHOR
Peter Scott, E<lt>PerlMedic@PSDT.comE<gt>
=head1 SEE ALSO
L<Benchmark::Timer>, L<Time::HiRes>.
=head1 COPYRIGHT
Copyright (c) 2004 Peter Scott.
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
=cut
|
