Previous Table of Contents Next


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");




END { end() }



=head1 NAME

Benchmark::TimeTick - Keep a tally of times at different places in your program


  use Benchmark::TimeTick qw(timetick);

  # Your code...

  timetick("Starting phase three");

  # More of your code...


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.)


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.


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.


=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>.


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.


    Previous Table of Contents Next
    © 2000- NIV