1Benchmark(3pm) Perl Programmers Reference Guide Benchmark(3pm)
2
6 Benchmark - benchmark running times of Perl code
7
9 use Benchmark qw(:all) ;
10 timethis ($count, "code");
12 # Use Perl code in strings...
14 timethese($count, {
15 'Name1' => '...code1...',
16 'Name2' => '...code2...',
17 });
18 # ... or use subroutine references.
20 timethese($count, {
21 'Name1' => sub { ...code1... },
22 'Name2' => sub { ...code2... },
23 });
24 # cmpthese can be used both ways as well
26 cmpthese($count, {
27 'Name1' => '...code1...',
28 'Name2' => '...code2...',
29 });
30 cmpthese($count, {
32 'Name1' => sub { ...code1... },
33 'Name2' => sub { ...code2... },
34 });
35 # ...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 $t = timeit($count, '...other code...')
47 print "$count loops of other code took:",timestr($t),"\n";
48 $t = countit($time, '...other code...')
50 $count = $t->iters ;
51 print "$count loops of other code took:",timestr($t),"\n";
52 # 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 timethis - run a chunk of code several times
61 timethese - run several chunks of code several times
63 cmpthese - print results of timethese as a comparison chart
65 timeit - run a chunk of code and see how long it goes
67 countit - see how many times a chunk of code runs in a given time
69 Methods
71 new Returns the current time. Example:
72 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 debug Enables or disable debugging by setting the $Benchmark::Debug
81 flag:
82 Benchmark->debug(1);
84 $t = timeit(10, ' 5 ** $Global ');
85 Benchmark->debug(0);
86 iters Returns the number of iterations.
88 Standard Exports
90 The following routines will be exported into your namespace if you use
91 the Benchmark module:
92 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 Returns: a Benchmark object.
100 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 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 timethis(-10, $code)
114 or to run two pieces of code tests for at least 3 seconds:
116 timethese(0, { test1 => '...', test2 => '...'})
118 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 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 Returns a Benchmark object.
133 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 timethis(COUNT, VALUE, KEY, STYLE)
141 The routines are called in string comparison order of KEY.
143 The COUNT can be zero or negative, see timethis().
145 Returns a hash reference of Benchmark objects, keyed by name.
147 timediff ( T1, T2 )
149 Returns the difference between two Benchmark times as a
150 Benchmark object suitable for passing to timestr().
151 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 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 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 Optional Exports
171 The following routines will be exported into your namespace if you
172 specifically ask that they be imported:
173 clearcache ( COUNT )
175 Clear the cached time for COUNT rounds of the null loop.
176 clearallcache ( )
178 Clear all cached times.
179 cmpthese ( COUNT, CODEHASHREF, [ STYLE ] )
181 cmpthese ( RESULTSHASHREF, [ STYLE ] )
182 Optionally calls timethese(), then outputs comparison chart.
183 This:
184 cmpthese( -1, { a => "++\$i", b => "\$i *= 2" } ) ;
186 outputs a chart like:
188 Rate b a
190 b 2831802/s -- -61%
191 a 7208959/s 155% --
192 This chart is sorted from slowest to fastest, and shows the
194 percent speed difference between each pair of tests.
195 "cmpthese" can also be passed the data structure that
197 timethese() returns:
198 $results = timethese( -1,
200 { a => "++\$i", b => "\$i *= 2" } ) ;
201 cmpthese( $results );
202 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 Returns a reference to an ARRAY of rows, each row is an ARRAY
208 of cells from the above chart, including labels. This:
209 my $rows = cmpthese( -1,
211 { a => '++$i', b => '$i *= 2' }, "none" );
212 returns a data structure like:
214 [
216 [ '', 'Rate', 'b', 'a' ],
217 [ 'b', '2885232/s', '--', '-59%' ],
218 [ 'a', '7099126/s', '146%', '--' ],
219 ]
220 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 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 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 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 Returns: a Benchmark object.
245 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 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 timesum ( T1, T2 )
257 Returns the sum of two Benchmark times as a Benchmark object
258 suitable for passing to timestr().
259 :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 Internally the Benchmark object holds timing values, described in
275 "NOTES" below. The following methods can be used to access them:
276 cpu_p
278 Total CPU (User + System) of the main (parent) process.
279 cpu_c
281 Total CPU (User + System) of any children processes.
282 cpu_a
284 Total CPU of parent and any children processes.
285 real
287 Real elapsed time "wallclock seconds".
288 iters
290 Number of iterations run.
291 The following illustrates use of the Benchmark object:
293 $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 ($real, $user, $system, $children_user, $children_system, $iters)
302 in seconds for the whole loop (not divided by the number of rounds).
304 The timing is done using time(3) and times(3).
306 Code is executed in the caller's package.
308 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 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 clearcache($key);
316 clearallcache();
317 disablecache();
319 enablecache();
320 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 use Benchmark qw( cmpthese ) ;
328 $x = 3;
329 cmpthese( -5, {
330 a => sub{$x*$x},
331 b => sub{$x**2},
332 } );
333 outputs something like this:
335 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 while
342 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 outputs something like this:
352 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 The real time timing is done using time(2) and the granularity is
369 therefore only one second.
370 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 timethis(100,'1');
375 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 March 28th, 1997; by Hugo van der Sanden: added support for code
390 references and the already documented 'debug' method; revamped
391 documentation.
392 April 04-07th, 1997: by Jarkko Hietaniemi, added the run-for-some-time
394 functionality.
395 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 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 September, 2002; by Jarkko Hietaniemi: add ':hireswallclock' special
407 tag.
408 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 November, 2007; by Christophe Grosjean: make cmpthese and timestr
413 compute time consistently with style argument, default is 'all' not
414 'noc' any more.
415perl v5.32.1 2021-05-31 Benchmark(3pm)