1NAME
2 Test::Benchmark - Make sure something really is faster
3
4SYNOPSIS
5 use Test::More test => 17;
6 use Test::Benchmark;
7
8 is_faster(-10, sub {...}, sub {...}, "this is faster than that")
9 is_faster(5, -10, sub {...}, sub {...}, "this is 5 times faster than that")
10 is_n_times_faster(5, -10, sub {...}, sub {...}, "this is 5 times faster than that")
11
12 is_faster(-10, $bench1, $bench2, "res1 was faster than res2");
13
14 is_fastest("c", -1, {a => sub {...}, b => sub {...}, c => sub {...},);
15
16DESCRIPTION
17 Sometimes you want to make sure that your "faster" algorithm really is
18 faster than the old way. This lets you check. It might also be useful to
19 check that your super whizzo XS or Inline::C version is actually faster.
20
21 This module is based on the standard Benchmark module. If you have lots of
22 timings to compare and you don't want to keep running the same benchmarks
23 all the time, you can pass in a result object from "Benchmark::timethis()"
24 instead of sub routine reference.
25
26USAGE
27 There are 3 functions exported: "is_faster()", "is_n_times_faster()" and
28 "is_fastest()". Actually "is_faster()" is redundant because
29 "is_n_times_faster()" can do the same thing just by setting n to 1.
30
31 Anywhere you can pass a subroutine reference you can also pass in a
32 Benchmark object.
33
34 # call as
35 # is_faster($times, $sub1, $sub2, $name)
36 # is_faster($faster, $times, $sub1, $sub2, $name)
37
38 If you leave the number of iterations blank then it will use Benchmark's
39 default.
40
41 is_faster()
42 is_faster($times, $sub1, $sub2, $name)
43
44 is_faster($factor, $times, $sub1, $sub2, $name)
45
46 This runs each subroutine reference $times times and then compares the
47 results. Instead of either subroutine reference you can pass in a Benchmark
48 object. If you pass in 2 Benchmark objects then $times is irrelevant.
49
50 If $times is negative then that specifies a minimum duration for the
51 benchmark rather than a number of iterations (see Benchmark for more
52 details). I strongly recommend you use this feature if you want your modules
53 to still pass tests reliably on machines that are much faster than your own.
54 10000 iterations may be enough for a reliable benchmark on your home PC but
55 it be just a twinkling in the eye of somebody else's super computer.
56
57 If the test fails, you will get a diagnostic output showing the benchmark
58 results in the standard Benchmark format.
59
60 is_n_times_faster()
61 is_n_times_faster($factor, $times, $sub1, $sub2, $name)
62
63 This is exactly the same as the second form of is_faster but it's just
64 explicit about the "n times" part.
65
66 is_fastest()
67 is_fastest($bname, $times, $bhash, $name)
68
69 This takes a hash reference containing benchmark subroutines as values and
70 their names as keys. It times each subroutine and checks that the one named
71 in $bname was the fastest. If the test fails, it will print out a sorted
72 list of the timings of all the subroutines.
73
74VARIABLES
75 If you set "$Test::Benchmark::VERBOSE = 1" then the benchmark results will
76 be printed out as diagnostics whether the tests pass or fail.
77
78DANGERS
79 Benchmarking can be slow so please consider leaving out the benchmark tests
80 from your default test suite, perhaps only running them if the user has set
81 a particular environment variable.
82
83 Some benchmarks are inherently unreliable and should not be part of an
84 automated test suite.
85
86BUGS
87 None that I know of but I said that last time too.
88
89DEPENDENCIES
90 Benchmark, Test::Builder but they come with most Perls.
91
92HISTORY
93 This came up on the perl-qa mailing list, when Jim Cromie wanted to display
94 benchmark results in tests.
95
96SEE ALSO
97 Test::Builder, Benchmark
98
99AUTHOR
100 Written by Fergal Daly <fergal@esatclear.ie>.
101
102COPYRIGHT
103 Copyright 2003 by Fergal Daly <fergal@esatclear.ie>.
104
105 This program is free software and comes with no warranty. It is distributed
106 under the LGPL license. You do not have to accept this license but nothing
107 else gives you the right to use this software.
108
109 See the file LGPL included in this distribution or
110 http://www.fsf.org/licenses/licenses.html.
111
112