Benchmark::Timer(3pm)

💖 Benchmark::Timer 💖

okay bestie, so this is Benchmark::Timer — the Perl module for benchmarking with statistical confidence. it's Benchmark::Timer, sitting in the 3pm manual section (perl modules, yk). let me break it all the way down for you 🫶

---

✨ SYNOPSIS ✨

non-statistical girlies, this one's for you:

# Non-statistical usage
use Benchmark::Timer;
$t = Benchmark::Timer->new(skip => 1);

for(1 .. 1000) {
    $t->start('tag');
    &long_running_operation();
    $t->stop('tag');
}
print $t->report;

and now for the statistical version, the main character:

# Statistical usage
use Benchmark::Timer;
$t = Benchmark::Timer->new(skip => 1, confidence => 97.5, error => 2);

while($t->need_more_samples('tag')) {
    $t->start('tag');
    &long_running_operation();
    $t->stop('tag');
}
print $t->report;

---

🌸 DESCRIPTION 🌸

so the Benchmark::Timer class lets you time bits of your code conveniently, and it also lets you benchmark code by timing repeated trials. it's literally perfect for when you need more precise info about the running time of parts of your code than the Benchmark module will give you, but you don't wanna go all out and profile your code. lowkey reasonable of you.

the methodology is simple, bestie: make a Benchmark::Timer object, and wrap the portions of code you wanna benchmark with start() and stop() method calls. you can pass a tag to those methods if you're planning to time multiple different bits of code. and if you provide error and confidence values, you can also use need_more_samples() to determine, statistically, whether you need to collect more data. slay.

after you've run your code, you can get info about the running time by calling the results() method, or get a descriptive benchmark report by calling report(). if you run your code over multiple trials, the average time is what gets reported. this is wonderful for benchmarking time-critical portions of code in a rigorous way. you can also optionally choose to skip any number of initial trials to cut down on initial case irregularities. periodt 💅

---

🎀 METHODS 🎀

in all of the following methods, $tag refers to the user-supplied name of the code being timed. unless otherwise specified, $tag defaults to the tag of the last call to start(), or "_default" if start() was not previously called with a tag. noted. moving on.

• $t = Benchmark::Timer->new( [options] ); — constructor for the Benchmark::Timer object; it returns a reference to a timer object. it takes the following named arguments:
  • skip — the number of trials (if any) to skip before recording timing information.
  • minimum — the minimum number of trials to run.
  • error — a percentage between 0 and 100 that says how much error you're willing to tolerate in the average time measured by the benchmark. for example, a value of 1 means you want the reported average time to be within 1% of the real average time. need_more_samples() uses this value to figure out when it's okay to stop collecting data.

if you specify an error you must also specify a confidence. no exceptions bestie.

• confidence — a percentage between 0 and 100 that says how confident you wanna be in the error measured by the benchmark. for example, a value of 97.5 means you want to be 97.5% confident that the real average time is within the error margin you specified. need_more_samples() uses this value to compute the estimated error for the collected data, so it can figure out when it's okay to stop.

if you specify a confidence you must also specify an error. yeah they're a package deal 💞

• $t->reset; — reset the timer object back to the pristine state it started in. erase all memory of tags and any previously accumulated timings. returns a reference to the timer object. it takes the same arguments the constructor takes.
• $t->start($tag); — record the current time so that when stop() is called, we can calculate an elapsed time.
• $t->stop($tag); — record timing information. if $tag is supplied, it must correspond to one given to a previously called start() call. it returns the elapsed time in milliseconds. stop() croaks if the timer gets out of sync (like, the number of start()s doesn't match the number of stop()s). keep it balanced girlies.
• $t->need_more_samples($tag); — compute the estimated error in the average of the data collected so far, and return true if that error exceeds the user-specified error. if a $tag is supplied, it must correspond to one given to a previously called start() call.

this routine assumes that the data are normally distributed. just so you know.

• $t->report($tag); — returns a string containing a simple report on the collected timings for $tag. this report contains the number of trials run, the total time taken, and, if more than one trial was run, the average time needed to run one trial plus error information. report() will complain (via a warning) if a tag is still active. 👀
• $t->reports; — in a scalar context, returns a string containing a simple report on the collected timings for all tags. that report is a concatenation of the individual tag reports, in the original tag order. in a list context, it returns a hash keyed by tag and containing reports for each tag. the return value is actually an array, so the original tag order is preserved if you assign to an array instead of a hash. reports() will complain (via a warning) if a tag is still active.
• $t->result($tag); — return the time it took for $tag to elapse, or the mean time it took for $tag to elapse once, if $tag was used to time code more than once. result() will complain (via a warning) if a tag is still active.
• $t->results; — returns the timing data as a hash keyed on tags where each value is the time it took to run that code, or the average time it took if that code ran more than once. in scalar context it returns a reference to that hash. the return value is actually an array, so the original tag order is preserved if you assign to an array instead of a hash. (same little trick as reports() 💜)
• $t->data($tag), $t->data; — these methods are useful if you wanna recover the full internal timing data so you can roll your own reports. no gatekeeping here.
  • if called with a $tag, it returns the raw timing data for that $tag as an array (or a reference to an array if called in scalar context). this is useful for feeding to something like the Statistics::Descriptive package.
  • if called with no arguments, it returns the raw timing data as a hash keyed on tags, where the values of the hash are lists of timings for that code. in scalar context, it returns a reference to that hash. as with results(), the data is internally represented as an array, so you can recover the original tag order by assigning to an array instead of a hash.

---

💀 BUGS 💀

benchmarking is an inherently futile activity, fraught with uncertainty not dissimilar to that experienced in quantum mechanics. like, it's giving Schrödinger's runtime fr fr. but things are a little better if you apply statistics. 🙈

---

📜 LICENSE 📜

this code is distributed under the GNU General Public License (GPL) Version 2. see the file LICENSE in the distribution for details.

---

👑 AUTHOR 👑

the original code (written before April 20, 2001) was written by Andrew Ho <andrew@zeuscat.com>, and is copyright (c) 2000-2001 Andrew Ho. versions up to 0.5 are distributed under the same terms as Perl.

maintenance of this module is now being done by David Coppit <david@coppit.org>. passing the torch 🫶

---

🌈 SEE ALSO 🌈

Benchmark, Time::HiRes, Time::Stopwatch, Statistics::Descriptive

---

and that's the whole thing bestie, no cap. this page is from perl v5.36.0, dated 2023-08-06, filed under Benchmark::Timer(3pm) in the User Contributed Perl Documentation. go forth and benchmark rigorously 💖✨🎀🦋