NAME

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

SYNOPSIS

  use Time::TimeTick;
  # Your code...
  timetick("Starting phase three");
  # More of your code...

DESCRIPTION

Time::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 timetick() function 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 Time::HiRes::time() if Time::HiRes is available, otherwise time() will be used. (Since time() has one-second granularity this is unlikely to be useful.)

DISABLING

To disable the effect of timing with minimal modification to your program, just change ``use Time::TimeTick ...'' to ``no Time::TimeTick...''. The timetick() function will contain no instructions in order to maximize execution speed, and no report will be triggered.

CONFIGURATION

You can customize the action of Time::TimeTick via options passed as key-value pairs in the use statement. Recognized keys are:

suppress_initial

If true, do not put an initial entry in the report when the module is loaded.

suppress_final

If true, do not put a final entry in the report when the program terminates.

initial_tag

If set, replaces the default entry of ``Timeticker for <program> starting'' output initially (only if suppress_initial is not set.)

final_tag

If set, replaces the default entry of ``Timeticker for <program> finishing'' output initially (only if suppress_final is not set.)

reset_start

If true, report all times relative to the time that Time::TimeTick was loaded rather than the actual start of the program.

format_tick_tag

If set, should be a reference to a subroutine that will take as input a tag as passed to 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.

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 format_report callback is:

  sub { printf("%7.4f %s\n", @$_) for @_ }

suppress_report

If true, do not output a report when report() is called; just reset the time tick list instead.

FUNCTIONS

Time::TimeTick::timetick($tag)

Record the time at this point of the program and label it with the string $tag.

Time::TimeTick::report()

Output a report (unless suppress_report is set) and reset the time tick list.

Time::TimeTick::end()

Add a final time tick (unless suppress_final is set), and output a report. Called by default when the program finishes.

Exports

Time::TimeTick::timetick is exported to the caller. Note that Time::TimeTick::report is not exported; if you want to call it explicitly you will have to qualify the function name with the package name.

EXAMPLE

  use Time::TimeTick suppress_initial => 1;
  # ... picture intervening lines of code
  timetick("Phase 2");
  # ... picture more code
  timetick("Phase 3");
  # ... and yet more
  timetick("Phase 4");
  # Some time later, the program ends

Output from Time::TimeTick:

  0.7524 Phase 2
  0.7945 Phase 3
  0.8213 Phase 4
  0.8328 Timeticker for testprog finishing

AUTHOR

Peter Scott, <Peter@PSDT.com>

SEE ALSO

Benchmark::Timer, Time::HiRes.

NOTE

This module was originally written in a modified form and published in the book "Perl Medic" (Addison-Wesley, 2004): http://www.perlmedic.com/. Readers of that book should note that the user interface is different from what appeared there.

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.