1Benchmark(3pm) Perl Programmers Reference Guide Benchmark(3pm)
2
3
4
6 Benchmark - benchmark running times of Perl code
7
9 use Benchmark qw(:all) ;
10
11 timethis ($count, "code");
12
13 # Use Perl code in strings...
14 timethese($count, {
15 'Name1' => '...code1...',
16 'Name2' => '...code2...',
17 });
18
19 # ... or use subroutine references.
20 timethese($count, {
21 'Name1' => sub { ...code1... },
22 'Name2' => sub { ...code2... },
23 });
24
25 # cmpthese can be used both ways as well
26 cmpthese($count, {
27 'Name1' => '...code1...',
28 'Name2' => '...code2...',
29 });
30
31 cmpthese($count, {
32 'Name1' => sub { ...code1... },
33 'Name2' => sub { ...code2... },
34 });
35
36 # ...or in two stages
37 $results = timethese($count,
38 {
39 'Name1' => sub { ...code1... },
40 'Name2' => sub { ...code2... },
41 },
42 'none'
43 );
44 cmpthese( $results ) ;
45
46 $t = timeit($count, '...other code...')
47 print "$count loops of other code took:",timestr($t),"\n";
48
49 $t = countit($time, '...other code...')
50 $count = $t->iters ;
51 print "$count loops of other code took:",timestr($t),"\n";
52
53 # enable hires wallclock timing if possible
54 use Benchmark ':hireswallclock';
55
57 The Benchmark module encapsulates a number of routines to help you
58 figure out how long it takes to execute some code.
59
60 timethis - run a chunk of code several times
61
62 timethese - run several chunks of code several times
63
64 cmpthese - print results of timethese as a comparison chart
65
66 timeit - run a chunk of code and see how long it goes
67
68 countit - see how many times a chunk of code runs in a given time
69
70 Methods
71 new Returns the current time. Example:
72
73 use Benchmark;
74 $t0 = Benchmark->new;
75 # ... your code here ...
76 $t1 = Benchmark->new;
77 $td = timediff($t1, $t0);
78 print "the code took:",timestr($td),"\n";
79
80 debug Enables or disable debugging by setting the $Benchmark::Debug
81 flag:
82
83 Benchmark->debug(1);
84 $t = timeit(10, ' 5 ** $Global ');
85 Benchmark->debug(0);
86
87 iters Returns the number of iterations.
88
89 Standard Exports
90 The following routines will be exported into your namespace if you use
91 the Benchmark module:
92
93 timeit(COUNT, CODE)
94 Arguments: COUNT is the number of times to run the loop, and
95 CODE is the code to run. CODE may be either a code reference
96 or a string to be eval'd; either way it will be run in the
97 caller's package.
98
99 Returns: a Benchmark object.
100
101 timethis ( COUNT, CODE, [ TITLE, [ STYLE ]] )
102 Time COUNT iterations of CODE. CODE may be a string to eval
103 or a code reference; either way the CODE will run in the
104 caller's package. Results will be printed to STDOUT as TITLE
105 followed by the times. TITLE defaults to "timethis COUNT" if
106 none is provided. STYLE determines the format of the output,
107 as described for timestr() below.
108
109 The COUNT can be zero or negative: this means the minimum
110 number of CPU seconds to run. A zero signifies the default
111 of 3 seconds. For example to run at least for 10 seconds:
112
113 timethis(-10, $code)
114
115 or to run two pieces of code tests for at least 3 seconds:
116
117 timethese(0, { test1 => '...', test2 => '...'})
118
119 CPU seconds is, in UNIX terms, the user time plus the system
120 time of the process itself, as opposed to the real
121 (wallclock) time and the time spent by the child processes.
122 Less than 0.1 seconds is not accepted (-0.01 as the count,
123 for example, will cause a fatal runtime exception).
124
125 Note that the CPU seconds is the minimum time: CPU scheduling
126 and other operating system factors may complicate the attempt
127 so that a little bit more time is spent. The benchmark
128 output will, however, also tell the number of $code
129 runs/second, which should be a more interesting number than
130 the actually spent seconds.
131
132 Returns a Benchmark object.
133
134 timethese ( COUNT, CODEHASHREF, [ STYLE ] )
135 The CODEHASHREF is a reference to a hash containing names as
136 keys and either a string to eval or a code reference for each
137 value. For each (KEY, VALUE) pair in the CODEHASHREF, this
138 routine will call
139
140 timethis(COUNT, VALUE, KEY, STYLE)
141
142 The routines are called in string comparison order of KEY.
143
144 The COUNT can be zero or negative, see timethis().
145
146 Returns a hash reference of Benchmark objects, keyed by name.
147
148 timediff ( T1, T2 )
149 Returns the difference between two Benchmark times as a
150 Benchmark object suitable for passing to timestr().
151
152 timestr ( TIMEDIFF, [ STYLE, [ FORMAT ] ] )
153 Returns a string that formats the times in the TIMEDIFF
154 object in the requested STYLE. TIMEDIFF is expected to be a
155 Benchmark object similar to that returned by timediff().
156
157 STYLE can be any of 'all', 'none', 'noc', 'nop' or 'auto'.
158 'all' shows each of the 5 times available ('wallclock' time,
159 user time, system time, user time of children, and system
160 time of children). 'noc' shows all except the two children
161 times. 'nop' shows only wallclock and the two children times.
162 'auto' (the default) will act as 'all' unless the children
163 times are both zero, in which case it acts as 'noc'. 'none'
164 prevents output.
165
166 FORMAT is the printf(3)-style format specifier (without the
167 leading '%') to use to print the times. It defaults to
168 '5.2f'.
169
170 Optional Exports
171 The following routines will be exported into your namespace if you
172 specifically ask that they be imported:
173
174 clearcache ( COUNT )
175 Clear the cached time for COUNT rounds of the null loop.
176
177 clearallcache ( )
178 Clear all cached times.
179
180 cmpthese ( COUNT, CODEHASHREF, [ STYLE ] )
181 cmpthese ( RESULTSHASHREF, [ STYLE ] )
182 Optionally calls timethese(), then outputs comparison chart.
183 This:
184
185 cmpthese( -1, { a => "++\$i", b => "\$i *= 2" } ) ;
186
187 outputs a chart like:
188
189 Rate b a
190 b 2831802/s -- -61%
191 a 7208959/s 155% --
192
193 This chart is sorted from slowest to fastest, and shows the
194 percent speed difference between each pair of tests.
195
196 "cmpthese" can also be passed the data structure that
197 timethese() returns:
198
199 $results = timethese( -1,
200 { a => "++\$i", b => "\$i *= 2" } ) ;
201 cmpthese( $results );
202
203 in case you want to see both sets of results. If the first
204 argument is an unblessed hash reference, that is
205 RESULTSHASHREF; otherwise that is COUNT.
206
207 Returns a reference to an ARRAY of rows, each row is an ARRAY
208 of cells from the above chart, including labels. This:
209
210 my $rows = cmpthese( -1,
211 { a => '++$i', b => '$i *= 2' }, "none" );
212
213 returns a data structure like:
214
215 [
216 [ '', 'Rate', 'b', 'a' ],
217 [ 'b', '2885232/s', '--', '-59%' ],
218 [ 'a', '7099126/s', '146%', '--' ],
219 ]
220
221 NOTE: This result value differs from previous versions, which
222 returned the "timethese()" result structure. If you want
223 that, just use the two statement "timethese"..."cmpthese"
224 idiom shown above.
225
226 Incidentally, note the variance in the result values between
227 the two examples; this is typical of benchmarking. If this
228 were a real benchmark, you would probably want to run a lot
229 more iterations.
230
231 countit(TIME, CODE)
232 Arguments: TIME is the minimum length of time to run CODE
233 for, and CODE is the code to run. CODE may be either a code
234 reference or a string to be eval'd; either way it will be run
235 in the caller's package.
236
237 TIME is not negative. countit() will run the loop many times
238 to calculate the speed of CODE before running it for TIME.
239 The actual time run for will usually be greater than TIME due
240 to system clock resolution, so it's best to look at the
241 number of iterations divided by the times that you are
242 concerned with, not just the iterations.
243
244 Returns: a Benchmark object.
245
246 disablecache ( )
247 Disable caching of timings for the null loop. This will force
248 Benchmark to recalculate these timings for each new piece of
249 code timed.
250
251 enablecache ( )
252 Enable caching of timings for the null loop. The time taken
253 for COUNT rounds of the null loop will be calculated only
254 once for each different COUNT used.
255
256 timesum ( T1, T2 )
257 Returns the sum of two Benchmark times as a Benchmark object
258 suitable for passing to timestr().
259
260 :hireswallclock
261 If the Time::HiRes module has been installed, you can specify the
262 special tag ":hireswallclock" for Benchmark (if Time::HiRes is not
263 available, the tag will be silently ignored). This tag will cause the
264 wallclock time to be measured in microseconds, instead of integer
265 seconds. Note though that the speed computations are still conducted
266 in CPU time, not wallclock time.
267
269 Many of the functions in this module return a Benchmark object, or in
270 the case of "timethese()", a reference to a hash, the values of which
271 are Benchmark objects. This is useful if you want to store or further
272 process results from Benchmark functions.
273
274 Internally the Benchmark object holds timing values, described in
275 "NOTES" below. The following methods can be used to access them:
276
277 cpu_p
278 Total CPU (User + System) of the main (parent) process.
279
280 cpu_c
281 Total CPU (User + System) of any children processes.
282
283 cpu_a
284 Total CPU of parent and any children processes.
285
286 real
287 Real elapsed time "wallclock seconds".
288
289 iters
290 Number of iterations run.
291
292 The following illustrates use of the Benchmark object:
293
294 $result = timethis(100000, sub { ... });
295 print "total CPU = ", $result->cpu_a, "\n";
296
298 The data is stored as a list of values from the time and times
299 functions:
300
301 ($real, $user, $system, $children_user, $children_system, $iters)
302
303 in seconds for the whole loop (not divided by the number of rounds).
304
305 The timing is done using time(3) and times(3).
306
307 Code is executed in the caller's package.
308
309 The time of the null loop (a loop with the same number of rounds but
310 empty loop body) is subtracted from the time of the real loop.
311
312 The null loop times can be cached, the key being the number of rounds.
313 The caching can be controlled using calls like these:
314
315 clearcache($key);
316 clearallcache();
317
318 disablecache();
319 enablecache();
320
321 Caching is off by default, as it can (usually slightly) decrease
322 accuracy and does not usually noticeably affect runtimes.
323
325 For example,
326
327 use Benchmark qw( cmpthese ) ;
328 $x = 3;
329 cmpthese( -5, {
330 a => sub{$x*$x},
331 b => sub{$x**2},
332 } );
333
334 outputs something like this:
335
336 Benchmark: running a, b, each for at least 5 CPU seconds...
337 Rate b a
338 b 1559428/s -- -62%
339 a 4152037/s 166% --
340
341 while
342
343 use Benchmark qw( timethese cmpthese ) ;
344 $x = 3;
345 $r = timethese( -5, {
346 a => sub{$x*$x},
347 b => sub{$x**2},
348 } );
349 cmpthese $r;
350
351 outputs something like this:
352
353 Benchmark: running a, b, each for at least 5 CPU seconds...
354 a: 10 wallclock secs ( 5.14 usr + 0.13 sys = 5.27 CPU) @ 3835055.60/s (n=20210743)
355 b: 5 wallclock secs ( 5.41 usr + 0.00 sys = 5.41 CPU) @ 1574944.92/s (n=8520452)
356 Rate b a
357 b 1574945/s -- -59%
358 a 3835056/s 144% --
359
361 Benchmark inherits from no other class, except of course from Exporter.
362
364 Comparing eval'd strings with code references will give you inaccurate
365 results: a code reference will show a slightly slower execution time
366 than the equivalent eval'd string.
367
368 The real time timing is done using time(2) and the granularity is
369 therefore only one second.
370
371 Short tests may produce negative figures because perl can appear to
372 take longer to execute the empty loop than a short test; try:
373
374 timethis(100,'1');
375
376 The system time of the null loop might be slightly more than the system
377 time of the loop with the actual code and therefore the difference
378 might end up being < 0.
379
381 Devel::NYTProf - a Perl code profiler
382
384 Jarkko Hietaniemi <jhi@iki.fi>, Tim Bunce <Tim.Bunce@ig.co.uk>
385
387 September 8th, 1994; by Tim Bunce.
388
389 March 28th, 1997; by Hugo van der Sanden: added support for code
390 references and the already documented 'debug' method; revamped
391 documentation.
392
393 April 04-07th, 1997: by Jarkko Hietaniemi, added the run-for-some-time
394 functionality.
395
396 September, 1999; by Barrie Slaymaker: math fixes and accuracy and
397 efficiency tweaks. Added cmpthese(). A result is now returned from
398 timethese(). Exposed countit() (was runfor()).
399
400 December, 2001; by Nicholas Clark: make timestr() recognise the style
401 'none' and return an empty string. If cmpthese is calling timethese,
402 make it pass the style in. (so that 'none' will suppress output). Make
403 sub new dump its debugging output to STDERR, to be consistent with
404 everything else. All bugs found while writing a regression test.
405
406 September, 2002; by Jarkko Hietaniemi: add ':hireswallclock' special
407 tag.
408
409 February, 2004; by Chia-liang Kao: make cmpthese and timestr use time
410 statistics for children instead of parent when the style is 'nop'.
411
412 November, 2007; by Christophe Grosjean: make cmpthese and timestr
413 compute time consistently with style argument, default is 'all' not
414 'noc' any more.
415
416
417
418perl v5.36.3 2023-11-30 Benchmark(3pm)