.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Stopwatch 3pm"
.TH Stopwatch 3pm "2022-12-04" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Time::Stopwatch \- Use tied scalars as timers
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    use Time::Stopwatch;
\&    tie my $timer, \*(AqTime::Stopwatch\*(Aq;
\&
\&    do_something();
\&    print "Did something in $timer seconds.\en";
\&
\&    my @times = map {
\&        $timer = 0;
\&        do_something_else();
\&        $timer;
\&    } 1 .. 5;
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
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 \fBtie()\fR.
.PP
If you have the module Time::HiRes installed, the timers created by
Time::Stopwatch will automatically count fractional seconds.  Do
\&\fInot\fR assume that the values of the timers are always integers.  You
may test the constant \f(CW\*(C`Time::Stopwatch::HIRES\*(C'\fR to find out whether
high resolution timing is enabled.
.SS "A note on timing short intervals"
.IX Subsection "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
\&\fBtie()\fR interface does not matter.  With Time::HiRes installed, it can
nonetheless be used for even microsecond timing, provided that
appropriate care is taken.
.IP "\(bu" 4
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 \fBtie()\fR call.
.IP "\(bu" 4
\&\fBAlways\fR 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.
.IP "\(bu" 4
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.
.IP "\(bu" 4
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.
.PP
The following sample code should give a relatively reasonable
measurement of a the time taken by a short operation:
.PP
.Vb 2
\&    use Time::HiRes;  # high resolution timing required
\&    use Time::Stopwatch;
\&
\&    use Statistics::Descriptive;
\&    my $stat = Statistics::Descriptive::Sparse\->new();
\&
\&    tie my $time, \*(AqTime::Stopwatch\*(Aq;  # code timer
\&    tie my $wait, \*(AqTime::Stopwatch\*(Aq;  # 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\en",
\&          "mean:  ", $stat\->mean(), " seconds\en",
\&          "s.d.:  ", $stat\->standard_deviation(), " seconds\en");
.Ve
.PP
Note that the above code includes the time of the subroutine call in
the measurement.
.SH "BUGS"
.IX Header "BUGS"
Since tied scalars do not (yet?) support atomic modification, use of
operators like \f(CW\*(C`$t++\*(C'\fR or \f(CW\*(C`$t *= 2\*(C'\fR on timers will cause them to lose
the time it takes to fetch, modify and store the value.  I \fImight\fR be
able to get around this by overloading the return value of \f(CW\*(C`FETCH\*(C'\fR,
but I doubt if it's worth the trouble.  Just don't do that.
.PP
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 \fBint()\fR will do
just fine if you want whole seconds, but still..
.SH "CHANGE LOG"
.IX Header "CHANGE LOG"
.IP "1.00 (15 Mar 2001)" 4
.IX Item "1.00 (15 Mar 2001)"
Explicitly localized \f(CW$SIG{_\|_DIE_\|_}\fR when testing for Time::HiRes
availability.  Added \*(L"A note on timing short intervals\*(R" to the \s-1POD\s0
documentation.  Bumped version to 1, no longer beta.
.IP "0.03 (27 Feb 2001)" 4
.IX Item "0.03 (27 Feb 2001)"
Modified tests to give more information, reduced subsecond accuracy
test to 1/10 seconds to allow for inaccurate \fBselect()\fR implementations.
Tweaked synopsis and \s-1README.\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Time::HiRes, \*(L"tie\*(R" in perlfunc
.PP
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.
.SH "AUTHORS"
.IX Header "AUTHORS"
Copyright 2000\-2001, Ilmari Karonen.  All rights reserved.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.PP
Address bug reports and comments to: perl@itz.pp.sci.fi