MAN page from RedHat Other perl-5.004-0.1.i386.rpm

Benchmark

Section: Perl Programmers Reference Guide (3)
Updated: perl 5.004, patch 04
Index

NAME

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

SYNOPSIS

    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";

DESCRIPTION

The Benchmark module encapsulates a number of routines to help youfigure out how long it takes to execute some code.

Methods

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;

Standard Exports

The following routines will be exported into your namespaceif you use the Benchmark module:

timeit(COUNT, CODE)

Arguments: COUNT is the number of times to run the loop, and CODE isthe code to run. CODE may be either a code reference or a string tobe 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 acode 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. STYLEdetermines 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 keysand either a string to eval or a code reference for each value.For each (KEY, VALUE) pair in the CODEHASHREF, this routine willcall

        timethis(COUNT, VALUE, KEY, STYLE)

timediff ( T1, T2 )

Returns the difference between two Benchmark times as a Benchmarkobject suitable for passing to timestr().

timestr ( TIMEDIFF, [ STYLE, [ FORMAT ]] )

Returns a string that formats the times in the TIMEDIFF object inthe requested STYLE. TIMEDIFF is expected to be a Benchmark objectsimilar to that returned by timediff().

STYLE can be any of `all', `noc', `nop' or `auto'. `all' shows eachof the 5 times available ('wallclock' time, user time, system time,user time of children, and system time of children). `noc' shows allexcept the two children times. `nop' shows only wallclock and thetwo children times. `auto' (the default) will act as `all' unlessthe children times are both zero, in which case it acts as `noc'.

FORMAT is the the printf(3) manpage-style format specifier (without theleading `%') to use to print the times. It defaults to `5.2f'.

Optional Exports

The following routines will be exported into your namespaceif 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 Benchmarkto recalculate these timings for each new piece of code timed.
enablecache ( ): Enable caching of timings for the null loop. The time taken for COUNTrounds of the null loop will be calculated only once for eachdifferent COUNT used.

NOTES

The data is stored as a list of values from the time and timesfunctions:

      ($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 samenumber of rounds but empty loop body) is subtractedfrom the time of the real loop.

The null loop times are cached, the key being thenumber of rounds. The caching can be controlled usingcalls like these:

    clearcache($key);    clearallcache();

    disablecache();    enablecache();

INHERITANCE

Benchmark inherits from no other class, except of coursefor Exporter.

CAVEATS

Comparing eval'd strings with code references will give youinaccurate results: a code reference will show a slowerexecution time than the equivalent eval'd string.

The real time timing is done using time(2) andthe granularity is therefore only one second.

Short tests may produce negative figures because perlcan appear to take longer to execute the empty loopthan a short test; try:

    timethis(100,'1');

The system time of the null loop might be slightlymore than the system time of the loop with the actualcode and therefore the difference might end up being < 0.

AUTHORS

Jarkko Hietaniemi <jhi@iki.fi>, Tim Bunce <Tim.BunceAATTig.co.uk>

MODIFICATION HISTORY

September 8th, 1994; by Tim Bunce.

March 28th, 1997; by Hugo van der Sanden: added support for codereferences and the already documented `debug' method; revampeddocumentation.

This document was created byman2html,using the manual pages.