1Benchmark::Dumb(3)    User Contributed Perl Documentation   Benchmark::Dumb(3)
2
3
4

NAME

6       Benchmark::Dumb - Benchmark.pm compatibility layer for Dumbbench
7

SYNOPSIS

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

DESCRIPTION

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
27       Understanding this documentation requires some familiarity of how
28       "Benchmark.pm" works since it mostly explains how this module is
29       different.
30
31       Please read the following section carefully to understand the most
32       important differences:
33
34   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
38The $count parameter is interpreted very differently!
39
40         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
45         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
49         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
54         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
58         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
62       • There are no exported functions by default!
63
64       • The ":hireswallclock" option is ignored. We always use the hi-res
65         wallclock!  While on the topic: We also only use wallclock times.
66
67       • The cache-related functions aren't implemented because we don't use a
68         cache.
69
70       • The original "Benchmark.pm" implementation provides a rudimentary
71         object-oriented interface. We do not faithfully copy that. See
72         "METHODS" below.
73
74       • 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
79       • The "debug" method is not implemented and neither is the "countit"
80         function.
81
82       • 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

FUNCTIONS

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
93       I'm quoting the "Benchmark" documentation liberally.
94
95   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
102       STYLE determines the format of the output, as described for timestr()
103       below.
104
105       Please read the section on "Differences to Benchmark.pm" for a
106       discussion of how the COUNT parameter is interpreted.
107
108       Returns a "Benchmark::Dumb" object.
109
110   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
116       Returns a "Benchmark::Dumb" object.
117
118   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
123         timethis(COUNT, VALUE, KEY, STYLE)
124
125       The routines are called in string comparison order of KEY.
126
127       The COUNT must be positive or zero. See discussion above.
128
129       Returns a hash reference of "Benchmark::Dumb" objects, keyed by name.
130
131   cmpthese(COUNT, CODEHASHREF, [STYLE]) cmpthese(RESULTSHASHREF, [STYLE])
132       Optionally calls timethese(), then outputs a comparison chart.  This:
133
134         cmpthese( 500.01, { a => "++\$i", b => "\$i *= 2" } ) ;
135
136       outputs a chart like:
137
138                        Rate/s Precision/s       a       b
139               a -3.59e+07       6e+06      -- -535.3%
140               b  8.24e+06      220000 -123.0%      --
141
142       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
148       c<cmpthese> can also be passed the data structure that timethese()
149       returns:
150
151         my $results = timethese( 100.01, { a => "++\$i", b => "\$i *= 2" } ) ;
152         cmpthese( $results );
153
154       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
158       Returns a reference to an ARRAY of rows, each row is an ARRAY of cells
159       from the above chart, including labels. This:
160
161         my $rows = cmpthese( 500.01, { a => '++$i', b => '$i *= 2' }, "none" );
162
163       returns a data structure like:
164
165               [
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

METHODS

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
178       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
182   name()
183       Returns the name of the benchmark result if any. (Not in "Benchmark".)
184
185   iters()
186       Returns the number of samples taken.
187
188   timesum($other_benchmark)
189       Returns a new "Benchmark::Dumb" object that represents the sum of this
190       benchmark and $other_benchmark.
191
192       "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
196   timediff($other_benchmark)
197       Returns a new "Benchmark::Dumb" object that represents the difference
198       between this benchmark and $other_benchmark ("$this-$other").
199
200       "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
204   timestr()
205       Returns a textual representation of this benchmark.
206
207       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

SEE ALSO

212       Dumbbench
213
214       Benchmark
215
216       Some of the documentation was taken from the documentation for
217       "Benchmark.pm"'s functions.
218

AUTHOR

220       Steffen Mueller, <smueller@cpan.org>
221
223       Copyright (C) 2010, 2012 by Steffen Mueller
224
225       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.
228
229
230
231perl v5.38.0                      2023-07-20                Benchmark::Dumb(3)
Impressum