Debian Codegraph @

upstream/debian-unstable/man3/Benchmark.3perl

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