# man > Benchmark(3perl)

---
type: CommandReference
command: Benchmark
mode: perldoc
section: 3perl
source: perldoc
---

## Quick Reference
- `use Benchmark qw(:all);` — import all standard and optional routines
- `$t = timeit(1_000_000, sub { ... })` — run code block 1M times, return Benchmark object
- `timethis(-5, sub { ... })` — run code for at least 5 CPU seconds
- `timethese(0, { test => sub { ... }, ... })` — run multiple tests for at least 3 sec each
- `cmpthese(-1, { a => sub { ... }, b => sub { ... } })` — compare tests with chart
- `$t = countit(10, sub { ... })` — run code for at least 10 wallclock seconds
- `$td = timediff($t1, $t0); print timestr($td)` — formatted elapsed time
- `use Benchmark ':hireswallclock';` — use microsecond wallclock timing

## Name
Benchmark — benchmark running times of Perl code

## Synopsis
perl
use Benchmark qw(:all);

$t = timeit($count, "code");
$t = timeit($count, sub { ... });

timethis($count, "code");
timethis($count, sub { ... }, "title", "all");

$results = timethese($count, { name1 => "code1", name2 => sub { ... } });
cmpthese($count, { name1 => "code1", name2 => sub { ... } });
cmpthese($results);

$t = countit($time_sec, "code");
$count = $t->iters;
## Options

### Core Timing Functions
- `timeit(COUNT, CODE)` — Execute CODE COUNT times; returns a `Benchmark` object.
- `timethis(COUNT, CODE, [TITLE, [STYLE]])` — Time COUNT iterations; prints TITLE and formatted output. If COUNT ≤ 0, run for at least the absolute value in CPU seconds (negative) or default 3 seconds (zero).
- `timethese(COUNT, CODEHASHREF, [STYLE])` — Run each named piece of code with `timethis`. Returns a hashref of `Benchmark` objects keyed by name.
- `cmpthese(COUNT, CODEHASHREF, [STYLE])` — Calls `timethese` and prints a comparison chart. Also accepts the hashref returned by `timethese`. Returns an arrayref of chart rows.
- `countit(TIME, CODE)` — Run CODE for at least TIME wallclock seconds; returns a `Benchmark` object. TIME must be non‑negative.

### Time Manipulation
- `timediff(T1, T2)` — Difference between two `Benchmark` objects, returns a new object.
- `timesum(T1, T2)` — Sum of two `Benchmark` objects.
- `timestr(TIMEDIFF, [STYLE, [FORMAT]])` — Format a time difference object as a string. STYLE: `'all'`, `'noc'`, `'nop'`, `'auto'` (default), `'none'`. FORMAT: `printf`‑style without leading `%`, default `'5.2f'`.

### Cache Control
- `clearcache(COUNT)` — Clear cached null‑loop timing for COUNT rounds.
- `clearallcache()` — Clear all cached timings.
- `disablecache()` — Disable null‑loop caching.
- `enablecache()` — Enable null‑loop caching.

### Object Methods
- `new()` — Returns current time as a `Benchmark` object.
- `debug($flag)` — Set `$Benchmark::Debug` flag.
- `iters()` — Return number of iterations.
- `$obj->cpu_p` — total CPU of parent (user + system)
- `$obj->cpu_c` — total CPU of children (user + system)
- `$obj->cpu_a` — sum of `cpu_p` and `cpu_c`
- `$obj->real` — real elapsed wallclock time
- `$obj->iters` — iterations count

### High‑Resolution Wallclock
- `use Benchmark ':hireswallclock'` — If `Time::HiRes` is available, wallclock times are measured in microseconds. CPU‑based speed computations remain in seconds.

## Examples
perl
use Benchmark qw( cmpthese );
$x = 3;
cmpthese(-5, {
    a => sub { $x * $x },
    b => sub { $x ** 2 },
});
# Output:
#   Benchmark: running a, b, each for at least 5 CPU seconds...
#          Rate    b    a
#   b 1559428/s   -- -62%
#   a 4152037/s 166%   --
perl
use Benchmark qw( timethese cmpthese );
$x = 3;
$r = timethese(-5, {
    a => sub { $x * $x },
    b => sub { $x ** 2 },
});
cmpthese($r);
# Output:
#   Benchmark: running a, b, each for at least 5 CPU seconds...
#            a: 10 wallclock secs ( 5.14 usr +  0.13 sys =  5.27 CPU) @ 3835055.60/s (n=20210743)
#            b:  5 wallclock secs ( 5.41 usr +  0.00 sys =  5.41 CPU) @ 1574944.92/s (n=8520452)
#          Rate    b    a
#   b 1574945/s   -- -59%
#   a 3835056/s 144%   --
## See Also
- [Devel::NYTProf](http://localhost/phpMan.php/perldoc/Devel%3A%3ANYTProf/markdown) — a Perl code profiler