# Time::Stopwatch - phpMan

## NAME
    [Time::Stopwatch] - Use tied scalars as timers

## SYNOPSIS
        use [Time::Stopwatch];
        tie my $timer, '[Time::Stopwatch]';

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

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

## DESCRIPTION
    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.

    *   Explicitly initialize the timer by assignment. The first measurement
        taken before resetting the timer will be a few microseconds longer
        due to the overhead of the tie() call.

    *   Always subtract the overhead of the timing code. This is true in
        general even if you're not using [Time::Stopwatch]. (High-level
        benchmarking tools like Benchmark.pm do this automatically.) See the
        code example below.

    *   Take as many measurements as you can to minimize random errors. The
        [Statistics::Descriptive] module may be useful for analyzing the data.
        This advice is also true for all benchmarking.

    *   Remember that a benchmark measures the time take to run the
        benchmark. Any generalizations to real applications may or may not
        be valid. If you want real world data, profile the real code in real
        use.

    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;
            $stat->add_data($diff);
        }

        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.

## BUGS
    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..

## CHANGE LOG
    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.

## SEE ALSO
    [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].

## AUTHORS
    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: <perl@itz.pp.sci.fi>