Stopwatch(3pm)

💖 NAME 💖

okay so this is Time::Stopwatch from the User Contributed Perl Documentation bestie collection — literally use tied scalars as timers. that's it, that's the whole vibe. ⏱️✨

---

🌸 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 🦋

so the Time::Stopwatch module is literally your girl for timing stuff through tied scalars, giving you a super convenient interface to timing functions. from your POV as the user, a scalar tied to this module just keeps going up by one every second. it's giving clock behavior, no cap. 🕐💅

using the module is mostly self-explanatory from the synopsis, fr fr. you can give your timers an initial value either by assigning to them or by passing the value as a third argument to tie(). both work, pick your fighter. 🎀

if you have the Time::HiRes module installed, the timers made by Time::Stopwatch will automatically count fractional seconds too. so like — do not assume the timer values are always integers, bestie, that's a trap. 😭 you can test the constant Time::Stopwatch::HIRES to find out whether high resolution timing is enabled. slay. 🔥

⏳ A note on timing short intervals ⏳

Time::Stopwatch is primarily designed for timing moderately long intervals (i.e. several seconds), where the overhead from the tie() interface genuinely does not matter. but 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 because of the overhead of the tie() call. no cap, that's just how it is. 🫠
• Always subtract the overhead of the timing code. this is true in general even if you're not using Time::Stopwatch, btw. (high-level benchmarking tools like Benchmark.pm do this automatically.) peep 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, periodt. 📊
• Remember that a benchmark measures the time taken 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. main character energy only. 👑

the following sample code should give a relatively reasonable measurement of 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");

heads up tho — the code above includes the time of the subroutine call in the measurement. so like, factor that in, bestie. 💀

---

💀 BUGS 💀

since tied scalars do not (yet?) support atomic modification, using operators like $t++ or $t *= 2 on timers will cause them to lose the time it takes to fetch, modify and store the value. 😭 the author says they might be able to get around this by overloading the return value of FETCH, but doubts it's worth the trouble. so like — just don't do that. 🙅‍♀️

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

---

📜 CHANGE LOG 📜

1. 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. 🎉
2. 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 peep the profiling modules Devel::DProf, Devel::SmallProf and Devel::OpProf. the whole squad fr fr. 🫶

---

👑 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. iconic behavior honestly. ✨

address bug reports and comments to: perl@itz.pp.sci.fi 📬

---

okay that's the whole thing bestie, you're officially a timing girlie now 💅🦋

this page shipped as perl v5.36.0 on 2022-12-04 — the Stopwatch(3pm) era, and we ate. 🎀🌸