Benchmark(3)
NNAAMMEE
Benchmark - benchmark running times of code
timethis - run a chunk of code several times
timethese - run several chunks of code several times
timeit - run a chunk of code and see how long it goes
SSYYNNOOPPSSIISS
timethis ($count, "code");
# Use Perl code in strings...
timethese($count, {
'Name1' => '...code1...',
'Name2' => '...code2...',
});
# ... or use subroutine references.
timethese($count, {
'Name1' => sub { ...code1... },
'Name2' => sub { ...code2... },
});
$t = timeit($count, '...other code...')
print "$count loops of other code took:",timestr($t),"\n";
DDEESSCCRRIIPPTTIIOONN
The Benchmark module encapsulates a number of routines to
help you figure out how long it takes to execute some
code.
MMeetthhooddss
new Returns the current time. Example:
use Benchmark;
$t0 = new Benchmark;
# ... your code here ...
$t1 = new Benchmark;
$td = timediff($t1, $t0);
print "the code took:",timestr($td),"\n";
debug Enables or disable debugging by setting the
$Benchmark::Debug flag:
debug Benchmark 1;
$t = timeit(10, ' 5 ** $Global ');
debug Benchmark 0;
SSttaannddaarrdd EExxppoorrttss
The following routines will be exported into your
namespace if you use the Benchmark module:
timeit(COUNT, CODE)
Arguments: COUNT is the number of times to run
the loop, and CODE is the code to run. CODE may
be either a code reference or a string to be
eval'd; either way it will be run in the
caller's package.
Returns: a Benchmark object.
timethis ( COUNT, CODE, [ TITLE, [ STYLE ]] )
Time COUNT iterations of CODE. CODE may be a
string to eval or a code reference; either way
the CODE will run in the caller's package.
Results will be printed to STDOUT as TITLE
followed by the times. TITLE defaults to
"timethis COUNT" if none is provided. STYLE
determines the format of the output, as
described for timestr() below.
timethese ( COUNT, CODEHASHREF, [ STYLE ] )
The CODEHASHREF is a reference to a hash
containing names as keys and either a string to
eval or a code reference for each value. For
each (KEY, VALUE) pair in the CODEHASHREF, this
routine will call
timethis(COUNT, VALUE, KEY, STYLE)
timediff ( T1, T2 )
Returns the difference between two Benchmark
times as a Benchmark object suitable for passing
to timestr().
timestr ( TIMEDIFF, [ STYLE, [ FORMAT ]] )
Returns a string that formats the times in the
TIMEDIFF object in the requested STYLE. TIMEDIFF
is expected to be a Benchmark object similar to
that returned by timediff().
STYLE can be any of 'all', 'noc', 'nop' or
'auto'. 'all' shows each of the 5 times
available ('wallclock' time, user time, system
time, user time of children, and system time of
children). 'noc' shows all except the two
children times. 'nop' shows only wallclock and
the two children times. 'auto' (the default)
will act as 'all' unless the children times are
both zero, in which case it acts as 'noc'.
FORMAT is the the printf(3) manpage-style format
specifier (without the leading '%') to use to
print the times. It defaults to '5.2f'.
OOppttiioonnaall EExxppoorrttss
The following routines will be exported into your
namespace if you specifically ask that they be imported:
clearcache ( COUNT )
Clear the cached time for COUNT rounds of the
null loop.
clearallcache ( )
Clear all cached times.
disablecache ( )
Disable caching of timings for the null loop.
This will force Benchmark to recalculate these
timings for each new piece of code timed.
enablecache ( )
Enable caching of timings for the null loop. The
time taken for COUNT rounds of the null loop
will be calculated only once for each different
COUNT used.
NNOOTTEESS
The data is stored as a list of values from the time and
times functions:
($real, $user, $system, $children_user, $children_system)
in seconds for the whole loop (not divided by the number
of rounds).
The timing is done using time(3) and times(3).
Code is executed in the caller's package.
The time of the null loop (a loop with the same number of
rounds but empty loop body) is subtracted from the time of
the real loop.
The null loop times are cached, the key being the number
of rounds. The caching can be controlled using calls like
these:
clearcache($key);
clearallcache();
disablecache();
enablecache();
IINNHHEERRIITTAANNCCEE
Benchmark inherits from no other class, except of course
for Exporter.
CCAAVVEEAATTSS
Comparing eval'd strings with code references will give
you inaccurate results: a code reference will show a
slower execution time than the equivalent eval'd string.
The real time timing is done using time(2) and the
granularity is therefore only one second.
Short tests may produce negative figures because perl can
appear to take longer to execute the empty loop than a
short test; try:
timethis(100,'1');
The system time of the null loop might be slightly more
than the system time of the loop with the actual code and
therefore the difference might end up being < 0.
AAUUTTHHOORRSS
Jarkko Hietaniemi lt;jhi@iki.fi, Tim Bunce
lt;Tim.Bunce@ig.co.uk
MMOODDIIFFIICCAATTIIOONN HHIISSTTOORRYY
September 8th, 1994; by Tim Bunce.
March 28th, 1997; by Hugo van der Sanden: added support
for code references and the already documented 'debug'
method; revamped documentation.