Debian Codegraph @

upstream/mageia-cauldron/man3pm/Benchmark.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Benchmark 3pm"
61 .TH Benchmark 3pm 2025-06-24 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Benchmark \- Benchmark running times of Perl code
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use Benchmark qw(:all);
72 \&
73 \& timethis($count, "code");
74 \&
75 \& # Use Perl code in strings...
76 \& timethese($count, {
77 \& \*(AqName1\*(Aq => \*(Aq...code1...\*(Aq,
78 \& \*(AqName2\*(Aq => \*(Aq...code2...\*(Aq,
79 \& });
80 \&
81 \& # ... or use subroutine references.
82 \& timethese($count, {
83 \& \*(AqName1\*(Aq => sub { ...code1... },
84 \& \*(AqName2\*(Aq => sub { ...code2... },
85 \& });
86 \&
87 \& # cmpthese can be used both ways as well
88 \& cmpthese($count, {
89 \& \*(AqName1\*(Aq => \*(Aq...code1...\*(Aq,
90 \& \*(AqName2\*(Aq => \*(Aq...code2...\*(Aq,
91 \& });
92 \&
93 \& cmpthese($count, {
94 \& \*(AqName1\*(Aq => sub { ...code1... },
95 \& \*(AqName2\*(Aq => sub { ...code2... },
96 \& });
97 \&
98 \& # ...or in two stages
99 \& $results = timethese($count,
100 \& {
101 \& \*(AqName1\*(Aq => sub { ...code1... },
102 \& \*(AqName2\*(Aq => sub { ...code2... },
103 \& },
104 \& \*(Aqnone\*(Aq
105 \& );
106 \& cmpthese( $results );
107 \&
108 \& my $t1 = timeit($count, \*(Aq...other code...\*(Aq);
109 \& print "$count loops of other code took:", timestr($t1),"\en";
110 \&
111 \& my $t2 = countit($time, \*(Aq...other code...\*(Aq);
112 \& $count = $t2\->iters;
113 \& print "$count loops of other code took:", timestr($t2),"\en";
114 \&
115 \& # Enable hires wallclock timing if possible
116 \& use Benchmark \*(Aq:hireswallclock\*(Aq;
117 .Ve
118 .SH DESCRIPTION
119 .IX Header "DESCRIPTION"
120 The \f(CW\*(C`Benchmark\*(C'\fR module encapsulates a number of routines to
121 help you figure out how long it takes to execute some code.
122 .PP
123 \&\f(CW\*(C`timethis\*(C'\fR \- Run a chunk of code several times
124 .PP
125 \&\f(CW\*(C`timethese\*(C'\fR \- Run several chunks of code several times
126 .PP
127 \&\f(CW\*(C`cmpthese\*(C'\fR \- Print results of \f(CW\*(C`timethese\*(C'\fR as a comparison chart
128 .PP
129 \&\f(CW\*(C`timeit\*(C'\fR \- Run a chunk of code and see how long it goes
130 .PP
131 \&\f(CW\*(C`countit\*(C'\fR \- See how many times a chunk of code runs in a given time
132 .SS Methods
133 .IX Subsection "Methods"
134 .IP new 10
135 .IX Item "new"
136 Returns the current time. Example:
137 .Sp
138 .Vb 6
139 \& use Benchmark;
140 \& my $t0 = Benchmark\->new;
141 \& # ... your code here ...
142 \& my $t1 = Benchmark\->new;
143 \& my $td = timediff($t1, $t0);
144 \& print "the code took:",timestr($td),"\en";
145 .Ve
146 .IP debug 10
147 .IX Item "debug"
148 Enables or disable debugging by setting the \f(CW$Benchmark::Debug\fR flag:
149 .Sp
150 .Vb 3
151 \& Benchmark\->debug(1);
152 \& my $t = timeit(10, \*(Aq 5 ** $Global \*(Aq);
153 \& Benchmark\->debug(0);
154 .Ve
155 .IP iters 10
156 .IX Item "iters"
157 Returns the number of iterations.
158 .SS "Standard Exports"
159 .IX Subsection "Standard Exports"
160 The following routines will be exported into your namespace
161 if you use the Benchmark module:
162 .IP "timeit(COUNT, CODE)" 10
163 .IX Item "timeit(COUNT, CODE)"
164 Arguments: COUNT is the number of times to run the loop, and CODE is
165 the code to run. CODE may be either a code reference or a string to
166 be eval\*(Aqd; either way it will be run in the caller\*(Aqs package.
167 .Sp
168 Returns: a Benchmark object.
169 .IP "timethis ( COUNT, CODE, [ TITLE, [ STYLE ]] )" 10
170 .IX Item "timethis ( COUNT, CODE, [ TITLE, [ STYLE ]] )"
171 Time COUNT iterations of CODE. CODE may be a string to eval or a
172 code reference; either way the CODE will run in the caller\*(Aqs package.
173 Results will be printed to STDOUT as TITLE followed by the times.
174 TITLE defaults to "timethis COUNT" if none is provided. STYLE
175 determines the format of the output, as described for \fBtimestr()\fR below.
176 .Sp
177 The COUNT can be zero or negative: this means the \fIminimum number of
178 CPU seconds\fR to run. A zero signifies the default of 3 seconds. For
179 example to run at least for 10 seconds:
180 .Sp
181 .Vb 1
182 \& timethis(\-10, $code);
183 .Ve
184 .Sp
185 or to run two pieces of code tests for at least 3 seconds:
186 .Sp
187 .Vb 1
188 \& timethese(0, { test1 => \*(Aq...\*(Aq, test2 => \*(Aq...\*(Aq});
189 .Ve
190 .Sp
191 CPU seconds is, in UNIX terms, the user time plus the system time of
192 the process itself, as opposed to the real (wallclock) time and the
193 time spent by the child processes. Less than 0.1 seconds is not
194 accepted (\-0.01 as the count, for example, will cause a fatal runtime
195 exception).
196 .Sp
197 Note that the CPU seconds is the \fBminimum\fR time: CPU scheduling and
198 other operating system factors may complicate the attempt so that a
199 little bit more time is spent. The benchmark output will, however,
200 also tell the number of \f(CW$code\fR runs/second, which should be a more
201 interesting number than the actually spent seconds.
202 .Sp
203 Returns a Benchmark object.
204 .IP "timethese ( COUNT, CODEHASHREF, [ STYLE ] )" 10
205 .IX Item "timethese ( COUNT, CODEHASHREF, [ STYLE ] )"
206 The CODEHASHREF is a reference to a hash containing names as keys
207 and either a string to eval or a code reference for each value.
208 For each (KEY, VALUE) pair in the CODEHASHREF, this routine will
209 call
210 .Sp
211 .Vb 1
212 \& timethis(COUNT, VALUE, KEY, STYLE);
213 .Ve
214 .Sp
215 The routines are called in string comparison order of KEY.
216 .Sp
217 The COUNT can be zero or negative, see \fBtimethis()\fR.
218 .Sp
219 Returns a hash reference of Benchmark objects, keyed by name.
220 .IP "timediff ( T1, T2 )" 10
221 .IX Item "timediff ( T1, T2 )"
222 Returns the difference between two Benchmark times as a Benchmark
223 object suitable for passing to \fBtimestr()\fR.
224 .IP "timestr ( TIMEDIFF, [ STYLE, [ FORMAT ] ] )" 10
225 .IX Item "timestr ( TIMEDIFF, [ STYLE, [ FORMAT ] ] )"
226 Returns a string that formats the times in the TIMEDIFF object in
227 the requested STYLE. TIMEDIFF is expected to be a Benchmark object
228 similar to that returned by \fBtimediff()\fR.
229 .Sp
230 STYLE can be any of \*(Aqall\*(Aq, \*(Aqnone\*(Aq, \*(Aqnoc\*(Aq, \*(Aqnop\*(Aq or \*(Aqauto\*(Aq. \*(Aqall\*(Aq shows
231 each of the 5 times available (\*(Aqwallclock\*(Aq time, user time, system time,
232 user time of children, and system time of children). \*(Aqnoc\*(Aq shows all
233 except the two children times. \*(Aqnop\*(Aq shows only wallclock and the
234 two children times. \*(Aqauto\*(Aq (the default) will act as \*(Aqall\*(Aq unless
235 the children times are both zero, in which case it acts as \*(Aqnoc\*(Aq.
236 \&\*(Aqnone\*(Aq prevents output.
237 .Sp
238 FORMAT is the \fBprintf\fR\|(3)\-style format specifier (without the
239 leading \*(Aq%\*(Aq) to use to print the times. It defaults to \*(Aq5.2f\*(Aq.
240 .SS "Optional Exports"
241 .IX Subsection "Optional Exports"
242 The following routines will be exported into your namespace
243 if you specifically ask that they be imported:
244 .IP "clearcache ( COUNT )" 10
245 .IX Item "clearcache ( COUNT )"
246 Clear the cached time for COUNT rounds of the null loop.
247 .IP "clearallcache ( )" 10
248 .IX Item "clearallcache ( )"
249 Clear all cached times.
250 .IP "cmpthese ( COUNT, CODEHASHREF, [ STYLE ] )" 10
251 .IX Item "cmpthese ( COUNT, CODEHASHREF, [ STYLE ] )"
252 .PD 0
253 .IP "cmpthese ( RESULTSHASHREF, [ STYLE ] )" 10
254 .IX Item "cmpthese ( RESULTSHASHREF, [ STYLE ] )"
255 .PD
256 Optionally calls \fBtimethese()\fR, then outputs comparison chart. This:
257 .Sp
258 .Vb 1
259 \& cmpthese( \-1, { a => "++\e$i", b => "\e$i *= 2" } );
260 .Ve
261 .Sp
262 outputs a chart like:
263 .Sp
264 .Vb 3
265 \& Rate b a
266 \& b 2831802/s \-\- \-61%
267 \& a 7208959/s 155% \-\-
268 .Ve
269 .Sp
270 This chart is sorted from slowest to fastest, and shows the percent speed
271 difference between each pair of tests.
272 .Sp
273 \&\f(CW\*(C`cmpthese\*(C'\fR can also be passed the data structure that \fBtimethese()\fR returns:
274 .Sp
275 .Vb 3
276 \& my $results = timethese( \-1,
277 \& { a => "++\e$i", b => "\e$i *= 2" } );
278 \& cmpthese( $results );
279 .Ve
280 .Sp
281 in case you want to see both sets of results.
282 If the first argument is an unblessed hash reference,
283 that is RESULTSHASHREF; otherwise that is COUNT.
284 .Sp
285 Returns a reference to an ARRAY of rows, each row is an ARRAY of cells from the
286 above chart, including labels. This:
287 .Sp
288 .Vb 2
289 \& my $rows = cmpthese( \-1,
290 \& { a => \*(Aq++$i\*(Aq, b => \*(Aq$i *= 2\*(Aq }, "none" );
291 .Ve
292 .Sp
293 returns a data structure like:
294 .Sp
295 .Vb 5
296 \& [
297 \& [ \*(Aq\*(Aq, \*(AqRate\*(Aq, \*(Aqb\*(Aq, \*(Aqa\*(Aq ],
298 \& [ \*(Aqb\*(Aq, \*(Aq2885232/s\*(Aq, \*(Aq\-\-\*(Aq, \*(Aq\-59%\*(Aq ],
299 \& [ \*(Aqa\*(Aq, \*(Aq7099126/s\*(Aq, \*(Aq146%\*(Aq, \*(Aq\-\-\*(Aq ],
300 \& ]
301 .Ve
302 .Sp
303 \&\fBNOTE\fR: This result value differs from previous versions, which returned
304 the \f(CWtimethese()\fR result structure. If you want that, just use the two
305 statement \f(CW\*(C`timethese\*(C'\fR...\f(CW\*(C`cmpthese\*(C'\fR idiom shown above.
306 .Sp
307 Incidentally, note the variance in the result values between the two examples;
308 this is typical of benchmarking. If this were a real benchmark, you would
309 probably want to run a lot more iterations.
310 .IP "countit(TIME, CODE)" 10
311 .IX Item "countit(TIME, CODE)"
312 Arguments: TIME is the minimum length of time to run CODE for, and CODE is
313 the code to run. CODE may be either a code reference or a string to
314 be eval\*(Aqd; either way it will be run in the caller\*(Aqs package.
315 .Sp
316 TIME is \fInot\fR negative. \fBcountit()\fR will run the loop many times to
317 calculate the speed of CODE before running it for TIME. The actual
318 time run for will usually be greater than TIME due to system clock
319 resolution, so it\*(Aqs best to look at the number of iterations divided
320 by the times that you are concerned with, not just the iterations.
321 .Sp
322 Returns: a Benchmark object.
323 .IP "disablecache ( )" 10
324 .IX Item "disablecache ( )"
325 Disable caching of timings for the null loop. This will force Benchmark
326 to recalculate these timings for each new piece of code timed.
327 .IP "enablecache ( )" 10
328 .IX Item "enablecache ( )"
329 Enable caching of timings for the null loop. The time taken for COUNT
330 rounds of the null loop will be calculated only once for each
331 different COUNT used.
332 .IP "timesum ( T1, T2 )" 10
333 .IX Item "timesum ( T1, T2 )"
334 Returns the sum of two Benchmark times as a Benchmark object suitable
335 for passing to \fBtimestr()\fR.
336 .SS :hireswallclock
337 .IX Subsection ":hireswallclock"
338 If the Time::HiRes module has been installed, you can specify the
339 special tag \f(CW\*(C`:hireswallclock\*(C'\fR for Benchmark (if Time::HiRes is not
340 available, the tag will be silently ignored). This tag will cause the
341 wallclock time to be measured in microseconds, instead of integer
342 seconds. Note though that the speed computations are still conducted
343 in CPU time, not wallclock time.
344 .SH "Benchmark Object"
345 .IX Header "Benchmark Object"
346 Many of the functions in this module return a Benchmark object,
347 or in the case of \f(CWtimethese()\fR, a reference to a hash, the values of
348 which are Benchmark objects. This is useful if you want to store or
349 further process results from Benchmark functions.
350 .PP
351 Internally the Benchmark object holds timing values,
352 described in "NOTES" below.
353 The following methods can be used to access them:
354 .IP cpu_p 4
355 .IX Item "cpu_p"
356 Total CPU (User + System) of the main (parent) process.
357 .IP cpu_c 4
358 .IX Item "cpu_c"
359 Total CPU (User + System) of any children processes.
360 .IP cpu_a 4
361 .IX Item "cpu_a"
362 Total CPU of parent and any children processes.
363 .IP real 4
364 .IX Item "real"
365 Real elapsed time "wallclock seconds".
366 .IP iters 4
367 .IX Item "iters"
368 Number of iterations run.
369 .PP
370 The following illustrates use of the Benchmark object:
371 .PP
372 .Vb 2
373 \& my $result = timethis(100000, sub { ... });
374 \& print "total CPU = ", $result\->cpu_a, "\en";
375 .Ve
376 .SH NOTES
377 .IX Header "NOTES"
378 The data is stored as a list of values from the time and times
379 functions:
380 .PP
381 .Vb 1
382 \& ($real, $user, $system, $children_user, $children_system, $iters)
383 .Ve
384 .PP
385 in seconds for the whole loop (not divided by the number of rounds).
386 .PP
387 The timing is done using \fBtime\fR\|(3) and \fBtimes\fR\|(3).
388 .PP
389 Code is executed in the caller\*(Aqs package.
390 .PP
391 The time of the null loop (a loop with the same
392 number of rounds but empty loop body) is subtracted
393 from the time of the real loop.
394 .PP
395 The null loop times can be cached, the key being the
396 number of rounds. The caching can be controlled using
397 calls like these:
398 .PP
399 .Vb 2
400 \& clearcache($key);
401 \& clearallcache();
402 \&
403 \& disablecache();
404 \& enablecache();
405 .Ve
406 .PP
407 Caching is off by default, as it can (usually slightly) decrease
408 accuracy and does not usually noticeably affect runtimes.
409 .SH EXAMPLES
410 .IX Header "EXAMPLES"
411 For example,
412 .PP
413 .Vb 6
414 \& use Benchmark qw( cmpthese ) ;
415 \& my $x = 3;
416 \& cmpthese( \-5, {
417 \& a => sub{$x*$x},
418 \& b => sub{$x**2},
419 \& } );
420 .Ve
421 .PP
422 outputs something like this:
423 .PP
424 .Vb 4
425 \& Benchmark: running a, b, each for at least 5 CPU seconds...
426 \& Rate b a
427 \& b 1559428/s \-\- \-62%
428 \& a 4152037/s 166% \-\-
429 .Ve
430 .PP
431 while
432 .PP
433 .Vb 7
434 \& use Benchmark qw( timethese cmpthese ) ;
435 \& my $x = 3;
436 \& my $r = timethese( \-5, {
437 \& a => sub{$x*$x},
438 \& b => sub{$x**2},
439 \& } );
440 \& cmpthese $r;
441 .Ve
442 .PP
443 outputs something like this:
444 .PP
445 .Vb 6
446 \& Benchmark: running a, b, each for at least 5 CPU seconds...
447 \& a: 10 wallclock secs ( 5.14 usr + 0.13 sys = 5.27 CPU) @ 3835055.60/s (n=20210743)
448 \& b: 5 wallclock secs ( 5.41 usr + 0.00 sys = 5.41 CPU) @ 1574944.92/s (n=8520452)
449 \& Rate b a
450 \& b 1574945/s \-\- \-59%
451 \& a 3835056/s 144% \-\-
452 .Ve
453 .SH INHERITANCE
454 .IX Header "INHERITANCE"
455 Benchmark inherits from no other class, except of course
456 from Exporter.
457 .SH CAVEATS
458 .IX Header "CAVEATS"
459 Comparing eval\*(Aqd strings with code references will give you
460 inaccurate results: a code reference will show a slightly slower
461 execution time than the equivalent eval\*(Aqd string.
462 .PP
463 The real time timing is done using \fBtime\fR\|(2) and
464 the granularity is therefore only one second.
465 .PP
466 Short tests may produce negative figures because perl
467 can appear to take longer to execute the empty loop
468 than a short test; try:
469 .PP
470 .Vb 1
471 \& timethis(100,\*(Aq1\*(Aq);
472 .Ve
473 .PP
474 The system time of the null loop might be slightly
475 more than the system time of the loop with the actual
476 code and therefore the difference might end up being < 0.
477 .SH "SEE ALSO"
478 .IX Header "SEE ALSO"
479 Devel::NYTProf \- a Perl code profiler
480 .SH AUTHORS
481 .IX Header "AUTHORS"
482 Jarkko Hietaniemi <\[email protected]\fR>, Tim Bunce <\[email protected]\fR>
483 .SH "MODIFICATION HISTORY"
484 .IX Header "MODIFICATION HISTORY"
485 September 8th, 1994; by Tim Bunce.
486 .PP
487 March 28th, 1997; by Hugo van der Sanden: added support for code
488 references and the already documented \*(Aqdebug\*(Aq method; revamped
489 documentation.
490 .PP
491 April 04\-07th, 1997: by Jarkko Hietaniemi, added the run\-for\-some\-time
492 functionality.
493 .PP
494 September, 1999; by Barrie Slaymaker: math fixes and accuracy and
495 efficiency tweaks. Added \fBcmpthese()\fR. A result is now returned from
496 \&\fBtimethese()\fR. Exposed \fBcountit()\fR (was \fBrunfor()\fR).
497 .PP
498 December, 2001; by Nicholas Clark: make \fBtimestr()\fR recognise the style \*(Aqnone\*(Aq
499 and return an empty string. If cmpthese is calling timethese, make it pass the
500 style in. (so that \*(Aqnone\*(Aq will suppress output). Make sub new dump its
501 debugging output to STDERR, to be consistent with everything else.
502 All bugs found while writing a regression test.
503 .PP
504 September, 2002; by Jarkko Hietaniemi: add \*(Aq:hireswallclock\*(Aq special tag.
505 .PP
506 February, 2004; by Chia\-liang Kao: make cmpthese and timestr use time
507 statistics for children instead of parent when the style is \*(Aqnop\*(Aq.
508 .PP
509 November, 2007; by Christophe Grosjean: make cmpthese and timestr compute
510 time consistently with style argument, default is \*(Aqall\*(Aq not \*(Aqnoc\*(Aq any more.