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, { a => "++\$i", b => "\$i *= 2" } ) ;
200 cmpthese( $results );
201 in case you want to see both sets of results. If the first
203 argument is an unblessed hash reference, that is
204 RESULTSHASHREF; otherwise that is COUNT.
205 Returns a reference to an ARRAY of rows, each row is an ARRAY
207 of cells from the above chart, including labels. This:
208 my $rows = cmpthese( -1, { a => '++$i', b => '$i *= 2' }, "none" );
210 returns a data structure like:
212 [
214 [ '', 'Rate', 'b', 'a' ],
215 [ 'b', '2885232/s', '--', '-59%' ],
216 [ 'a', '7099126/s', '146%', '--' ],
217 ]
218 NOTE: This result value differs from previous versions, which
220 returned the "timethese()" result structure. If you want
221 that, just use the two statement "timethese"..."cmpthese"
222 idiom shown above.
223 Incidently, note the variance in the result values between
225 the two examples; this is typical of benchmarking. If this
226 were a real benchmark, you would probably want to run a lot
227 more iterations.
228 countit(TIME, CODE)
230 Arguments: TIME is the minimum length of time to run CODE
231 for, and CODE is the code to run. CODE may be either a code
232 reference or a string to be eval'd; either way it will be run
233 in the caller's package.
234 TIME is not negative. countit() will run the loop many times
236 to calculate the speed of CODE before running it for TIME.
237 The actual time run for will usually be greater than TIME due
238 to system clock resolution, so it's best to look at the
239 number of iterations divided by the times that you are
240 concerned with, not just the iterations.
241 Returns: a Benchmark object.
243 disablecache ( )
245 Disable caching of timings for the null loop. This will force
246 Benchmark to recalculate these timings for each new piece of
247 code timed.
248 enablecache ( )
250 Enable caching of timings for the null loop. The time taken
251 for COUNT rounds of the null loop will be calculated only
252 once for each different COUNT used.
253 timesum ( T1, T2 )
255 Returns the sum of two Benchmark times as a Benchmark object
256 suitable for passing to timestr().
257 :hireswallclock
259 If the Time::HiRes module has been installed, you can specify the
260 special tag ":hireswallclock" for Benchmark (if Time::HiRes is not
261 available, the tag will be silently ignored). This tag will cause the
262 wallclock time to be measured in microseconds, instead of integer
263 seconds. Note though that the speed computations are still conducted
264 in CPU time, not wallclock time.
265
267 The data is stored as a list of values from the time and times
268 functions:
269 ($real, $user, $system, $children_user, $children_system, $iters)
271 in seconds for the whole loop (not divided by the number of rounds).
273 The timing is done using time(3) and times(3).
275 Code is executed in the caller's package.
277 The time of the null loop (a loop with the same number of rounds but
279 empty loop body) is subtracted from the time of the real loop.
280 The null loop times can be cached, the key being the number of rounds.
282 The caching can be controlled using calls like these:
283 clearcache($key);
285 clearallcache();
286 disablecache();
288 enablecache();
289 Caching is off by default, as it can (usually slightly) decrease
291 accuracy and does not usually noticably affect runtimes.
292
294 For example,
295 use Benchmark qw( cmpthese ) ;
297 $x = 3;
298 cmpthese( -5, {
299 a => sub{$x*$x},
300 b => sub{$x**2},
301 } );
302 outputs something like this:
304 Benchmark: running a, b, each for at least 5 CPU seconds...
306 Rate b a
307 b 1559428/s -- -62%
308 a 4152037/s 166% --
309 while
311 use Benchmark qw( timethese cmpthese ) ;
313 $x = 3;
314 $r = timethese( -5, {
315 a => sub{$x*$x},
316 b => sub{$x**2},
317 } );
318 cmpthese $r;
319 outputs something like this:
321 Benchmark: running a, b, each for at least 5 CPU seconds...
323 a: 10 wallclock secs ( 5.14 usr + 0.13 sys = 5.27 CPU) @ 3835055.60/s (n=20210743)
324 b: 5 wallclock secs ( 5.41 usr + 0.00 sys = 5.41 CPU) @ 1574944.92/s (n=8520452)
325 Rate b a
326 b 1574945/s -- -59%
327 a 3835056/s 144% --
328
330 Benchmark inherits from no other class, except of course for Exporter.
331
333 Comparing eval'd strings with code references will give you inaccurate
334 results: a code reference will show a slightly slower execution time
335 than the equivalent eval'd string.
336 The real time timing is done using time(2) and the granularity is
338 therefore only one second.
339 Short tests may produce negative figures because perl can appear to
341 take longer to execute the empty loop than a short test; try:
342 timethis(100,'1');
344 The system time of the null loop might be slightly more than the system
346 time of the loop with the actual code and therefore the difference
347 might end up being < 0.
348
350 Devel::DProf - a Perl code profiler
351
353 Jarkko Hietaniemi <jhi@iki.fi>, Tim Bunce <Tim.Bunce@ig.co.uk>
354
356 September 8th, 1994; by Tim Bunce.
357 March 28th, 1997; by Hugo van der Sanden: added support for code
359 references and the already documented 'debug' method; revamped
360 documentation.
361 April 04-07th, 1997: by Jarkko Hietaniemi, added the run-for-some-time
363 functionality.
364 September, 1999; by Barrie Slaymaker: math fixes and accuracy and
366 efficiency tweaks. Added cmpthese(). A result is now returned from
367 timethese(). Exposed countit() (was runfor()).
368 December, 2001; by Nicholas Clark: make timestr() recognise the style
370 'none' and return an empty string. If cmpthese is calling timethese,
371 make it pass the style in. (so that 'none' will suppress output). Make
372 sub new dump its debugging output to STDERR, to be consistent with
373 everything else. All bugs found while writing a regression test.
374 September, 2002; by Jarkko Hietaniemi: add ':hireswallclock' special
376 tag.
377 February, 2004; by Chia-liang Kao: make cmpthese and timestr use time
379 statistics for children instead of parent when the style is 'nop'.
380 November, 2007; by Christophe Grosjean: make cmpthese and timestr
382 compute time consistently with style argument, default is 'all' not
383 'noc' any more.
384perl v5.12.4 2011-06-07 Benchmark(3pm)