View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Ilmari Karonen > Time-Stopwatch-1.00 > Time::Stopwatch



Annotate this POD

Related Modules

View/Report Bugs
Module Version: 1.00   Source  


Time::Stopwatch - Use tied scalars as timers


    use Time::Stopwatch;
    tie my $timer, 'Time::Stopwatch';

    print "Did something in $timer seconds.\n";

    my @times = map {
        $timer = 0;
    } 1 .. 5;


The Time::Stopwatch module provides a convenient interface to timing functions through tied scalars. From the point of view of the user, scalars tied to the module simply increase their value by one every second.

Using the module should mostly be obvious from the synopsis. You can provide an initial value for the timers either by assigning to them or by passing the value as a third argument to tie().

If you have the module Time::HiRes installed, the timers created by Time::Stopwatch will automatically count fractional seconds. Do not assume that the values of the timers are always integers. You may test the constant Time::Stopwatch::HIRES to find out whether high resolution timing is enabled.

A note on timing short intervals

Time::Stopwatch is primarily designed for timing moderately long intervals (i.e. several seconds), where the overhead imposed by the tie() interface does not matter. With Time::HiRes installed, it can nonetheless be used for even microsecond timing, provided that appropriate care is taken.

The following sample code should give a relatively reasonable measurement of a the time taken by a short operation:

    use Time::HiRes;  # high resolution timing required
    use Time::Stopwatch;

    use Statistics::Descriptive;
    my $stat = Statistics::Descriptive::Sparse->new();

    tie my $time, 'Time::Stopwatch';  # code timer
    tie my $wait, 'Time::Stopwatch';  # loop timer

    while ($wait < 60) {  # run for one minute
        my $diff = 0;
        $time = 0; do_whatever(); $diff += $time;
        $time = 0;                $diff -= $time;

    print("count: ", $stat->count(), " iterations\n",
          "mean:  ", $stat->mean(), " seconds\n",
          "s.d.:  ", $stat->standard_deviation(), " seconds\n");

Note that the above code includes the time of the subroutine call in the measurement.


Since tied scalars do not (yet?) support atomic modification, use of operators like $t++ or $t *= 2 on timers will cause them to lose the time it takes to fetch, modify and store the value. I might be able to get around this by overloading the return value of FETCH, but I doubt if it's worth the trouble. Just don't do that.

There is no way to force low-resolution timing if Time::HiRes has been installed. I'm not sure why anyone would want to, since int() will do just fine if you want whole seconds, but still..


1.00 (15 Mar 2001)

Explicitly localized $SIG{__DIE__} when testing for Time::HiRes availability. Added "A note on timing short intervals" to the POD documentation. Bumped version to 1, no longer beta.

0.03 (27 Feb 2001)

Modified tests to give more information, reduced subsecond accuracy test to 1/10 seconds to allow for inaccurate select() implementations. Tweaked synopsis and README.


Time::HiRes, "tie" in perlfunc

For a higher-level approach to timing, try (among others) the modules Time::SoFar, Devel::Timer, or Benchmark. Also see the profiling modules Devel::DProf, Devel::SmallProf and Devel::OpProf.


Copyright 2000-2001, Ilmari Karonen. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Address bug reports and comments to:

syntax highlighting: