1Benchmark::Dumb(3) User Contributed Perl Documentation Benchmark::Dumb(3)
2
6 Benchmark::Dumb - Benchmark.pm compatibility layer for Dumbbench
7
9 use Benchmark::Dumb qw(:all);
10 cmpthese(
11 0.05, # 5% precision
12 {
13 fast => 'fast code',
14 slow => 'slow code',
15 }
16 );
17 # etc
18
20 This module implements an interface that is similar to the functional
21 interface of the Benchmark module. This module, however, uses the
22 Dumbbench benchmarking tool under the hood. For various reasons, the
23 interface and the output of the benchmark runs are not exactly the
24 same. Among other reasons, you would lose out on some of "Dumbbench"'s
25 advantages.
26 Understanding this documentation requires some familiarity of how
28 "Benchmark.pm" works since it mostly explains how this module is
29 different.
30 Please read the following section carefully to understand the most
32 important differences:
33 Differences to Benchmark.pm
35 This is a list of differences to the interface and behaviour of the
36 "Benchmark" module. It may not be complete. If so, please let me know.
37 • The $count parameter is interpreted very differently!
39 With "Benchmark.pm", specifying a positive integer meant that the
41 benchmark should be run exactly $count times. A negative value
42 indicated that the code should be run until $count seconds of
43 cumulated run-time have elapsed.
44 With "Benchmark::Dumb", we can do better. A positive integer
46 specifies the minimum number of iterations. "Dumbbench" may choose to
47 run more iterations to arrive at the necessary precision.
48 Specifying a certain target run-time (via a negative number for
50 $count) may seem like a tempting idea, but if you care at all about
51 the precision of your result, it's quite useless. This usage is not
52 supported by "Benchmark::Dumb"!
53 Instead, if you pass a positive floating point number as $count, the
55 fractional part of the number willbe interpreted as the target
56 relative precision that you expect from the result.
57 Finally, supplying a 0 as $count means that "Dumbbench" will be
59 invoked with the default settings. This is good enough for most
60 cases.
61 • There are no exported functions by default!
63 • The ":hireswallclock" option is ignored. We always use the hi-res
65 wallclock! While on the topic: We also only use wallclock times.
66 • The cache-related functions aren't implemented because we don't use a
68 cache.
69 • The original "Benchmark.pm" implementation provides a rudimentary
71 object-oriented interface. We do not faithfully copy that. See
72 "METHODS" below.
73 • The benchmark code will be run in a special package. It will not be
75 run in the caller package (at this time). If you need access to
76 previously-set-up package variables, you will need to include a
77 "package" statement in your code.
78 • The "debug" method is not implemented and neither is the "countit"
80 function.
81 • Some things that were previously considered functions are now
83 considered primarily methods (see "METHODS" below). But they are all
84 importable and callable as functions.
85
87 These functions work mostly (see the $count gotcha above) like the
88 equivalent functions in the "Benchmark" module, but the textual output
89 is different in that it contains estimates of the uncertainties. Some
90 of the style and format options of the original functions are ignored
91 for the time being.
92 I'm quoting the "Benchmark" documentation liberally.
94 timethis(COUNT, CODE, [TITLE, [STYLE]])
96 Time COUNT iterations of CODE. CODE may be a string to eval or a code
97 reference. Unlike with the original "Benchmark", the code will not run
98 in the caller's package. Results will be printed to "STDOUT" as TITLE
99 followed by the timestr(). TITLE defaults to "timethis COUNT" if none
100 is provided.
101 STYLE determines the format of the output, as described for timestr()
103 below.
104 Please read the section on "Differences to Benchmark.pm" for a
106 discussion of how the COUNT parameter is interpreted.
107 Returns a "Benchmark::Dumb" object.
109 timeit(COUNT, CODE)
111 Arguments: COUNT is the number of times to run the loop (see discussion
112 above), and CODE is the code to run. CODE may be either a code
113 reference or a string to be eval'd. Unlike with the original
114 "Benchmark", the code will not run in the caller's package.
115 Returns a "Benchmark::Dumb" object.
117 timethese(COUNT, CODEHASHREF, [STYLE])
119 The CODEHASHREF is a reference to a hash containing names as keys and
120 either a string to eval or a code reference for each value. For each
121 (KEY, VALUE) pair in the CODEHASHREF, this routine will call
122 timethis(COUNT, VALUE, KEY, STYLE)
124 The routines are called in string comparison order of KEY.
126 The COUNT must be positive or zero. See discussion above.
128 Returns a hash reference of "Benchmark::Dumb" objects, keyed by name.
130 cmpthese(COUNT, CODEHASHREF, [STYLE]) cmpthese(RESULTSHASHREF, [STYLE])
132 Optionally calls timethese(), then outputs a comparison chart. This:
133 cmpthese( 500.01, { a => "++\$i", b => "\$i *= 2" } ) ;
135 outputs a chart like:
137 Rate/s Precision/s a b
139 a -3.59e+07 6e+06 -- -535.3%
140 b 8.24e+06 220000 -123.0% --
141 This chart is sorted from slowest to fastest, and shows the percent
143 speed difference between each pair of tests as well as the
144 uncertainties on the rates and the relative speed difference. The
145 uncertainty on a speed difference may be omitted if it is below one
146 tenth of a percent.
147 c<cmpthese> can also be passed the data structure that timethese()
149 returns:
150 my $results = timethese( 100.01, { a => "++\$i", b => "\$i *= 2" } ) ;
152 cmpthese( $results );
153 in case you want to see both sets of results. If the first argument is
155 an unblessed hash reference, that is "RESULTSHASHREF"; otherwise that
156 is "COUNT".
157 Returns a reference to an ARRAY of rows, each row is an ARRAY of cells
159 from the above chart, including labels. This:
160 my $rows = cmpthese( 500.01, { a => '++$i', b => '$i *= 2' }, "none" );
162 returns a data structure like:
164 [
166 [ '', 'Rate/s', 'Precision/s', 'a', 'b' ],
167 [ 'a', '-4.43e+06', '120000', '--', '93+-6.9%' ],
168 [ 'b', '-2.294e+06', '52000', '-48.2%', '--' ]
169 ];
170
172 Please note that while the original "Benchmark" objects practically
173 asked for manual introspection since the API didn't provide convenient
174 access to all information, that practice is frowned upon with
175 "Benchmark::Dumb" objects. You have been warned. If there's a piece of
176 API missing, let me know.
177 There's no public constructor for "Benchmark::Dumb" objects because it
179 doesn't do what the "Benchmark" constructor did: It's not running
180 time() for you.
181 name()
183 Returns the name of the benchmark result if any. (Not in "Benchmark".)
184 iters()
186 Returns the number of samples taken.
187 timesum($other_benchmark)
189 Returns a new "Benchmark::Dumb" object that represents the sum of this
190 benchmark and $other_benchmark.
191 "timesum($b1, $b2)" was a function in the original "Benchmark" module
193 and may be called as a function on two "Benchmark::Dumb" objects as
194 well. It is available for importing into your namespace.
195 timediff($other_benchmark)
197 Returns a new "Benchmark::Dumb" object that represents the difference
198 between this benchmark and $other_benchmark ("$this-$other").
199 "timediff($b1, $b2)" was a function in the original "Benchmark" module
201 and may be called as a function on two "Benchmark::Dumb" objects as
202 well. It is available for importing into your namespace.
203 timestr()
205 Returns a textual representation of this benchmark.
206 timestr($b) was a function in the original "Benchmark" module and may
208 be called as a function on a "Benchmark::Dumb" object as well. It is
209 available for importing into your namespace.
210
212 Dumbbench
213 Benchmark
215 Some of the documentation was taken from the documentation for
217 "Benchmark.pm"'s functions.
218
220 Steffen Mueller, <smueller@cpan.org>
221
223 Copyright (C) 2010, 2012 by Steffen Mueller
224 This library is free software; you can redistribute it and/or modify it
226 under the same terms as Perl itself, either Perl version 5.8.1 or, at
227 your option, any later version of Perl 5 you may have available.
228perl v5.36.0 2023-01-20 Benchmark::Dumb(3)