Commit | Line | Data |
---|---|---|
a0d0e21e LW |
1 | =head1 NAME |
2 | ||
3 | Benchmark - benchmark running times of code | |
4 | ||
5 | timethis - run a chunk of code several times | |
6 | ||
7 | timethese - run several chunks of code several times | |
8 | ||
9 | timeit - run a chunk of code and see how long it goes | |
10 | ||
748a9306 | 11 | =head1 SYNOPSIS |
a0d0e21e LW |
12 | |
13 | timethis ($count, "code"); | |
14 | ||
15 | timethese($count, { | |
16 | 'Name1' => '...code1...', | |
17 | 'Name2' => '...code2...', | |
18 | }); | |
19 | ||
20 | $t = timeit($count, '...other code...') | |
21 | print "$count loops of other code took:",timestr($t),"\n"; | |
22 | ||
23 | =head1 DESCRIPTION | |
24 | ||
25 | The Benchmark module encapsulates a number of routines to help you | |
26 | figure out how long it takes to execute some code. | |
27 | ||
28 | =head2 Methods | |
29 | ||
30 | =over 10 | |
31 | ||
32 | =item new | |
33 | ||
34 | Returns the current time. Example: | |
35 | ||
36 | use Benchmark; | |
37 | $t0 = new Benchmark; | |
38 | # ... your code here ... | |
39 | $t1 = new Benchmark; | |
40 | $td = timediff($t1, $t0); | |
41 | print "the code took:",timestr($dt),"\n"; | |
42 | ||
43 | =item debug | |
44 | ||
45 | Enables or disable debugging by setting the C<$Benchmark::Debug> flag: | |
46 | ||
47 | debug Benchmark 1; | |
48 | $t = timeit(10, ' 5 ** $Global '); | |
49 | debug Benchmark 0; | |
50 | ||
51 | =back | |
52 | ||
53 | =head2 Standard Exports | |
54 | ||
55 | The following routines will be exported into your namespace | |
56 | if you use the Benchmark module: | |
57 | ||
58 | =over 10 | |
59 | ||
60 | =item timeit(COUNT, CODE) | |
61 | ||
62 | Arguments: COUNT is the number of time to run the loop, and | |
63 | the second is the code to run. CODE may be a string containing the code, | |
64 | a reference to the function to run, or a reference to a hash containing | |
65 | keys which are names and values which are more CODE specs. | |
66 | ||
67 | Side-effects: prints out noise to standard out. | |
68 | ||
69 | Returns: a Benchmark object. | |
70 | ||
71 | =item timethis | |
72 | ||
73 | =item timethese | |
74 | ||
75 | =item timediff | |
76 | ||
77 | =item timestr | |
78 | ||
79 | =back | |
80 | ||
81 | =head2 Optional Exports | |
82 | ||
83 | The following routines will be exported into your namespace | |
84 | if you specifically ask that they be imported: | |
85 | ||
86 | =over 10 | |
87 | ||
88 | clearcache | |
89 | ||
90 | clearallcache | |
91 | ||
92 | disablecache | |
93 | ||
94 | enablecache | |
95 | ||
96 | =back | |
97 | ||
98 | =head1 NOTES | |
99 | ||
100 | The data is stored as a list of values from the time and times | |
101 | functions: | |
102 | ||
103 | ($real, $user, $system, $children_user, $children_system) | |
104 | ||
105 | in seconds for the whole loop (not divided by the number of rounds). | |
106 | ||
107 | The timing is done using time(3) and times(3). | |
108 | ||
109 | Code is executed in the caller's package. | |
110 | ||
111 | Enable debugging by: | |
112 | ||
113 | $Benchmark::debug = 1; | |
114 | ||
115 | The time of the null loop (a loop with the same | |
116 | number of rounds but empty loop body) is subtracted | |
117 | from the time of the real loop. | |
118 | ||
119 | The null loop times are cached, the key being the | |
120 | number of rounds. The caching can be controlled using | |
121 | calls like these: | |
122 | ||
123 | clearcache($key); | |
124 | clearallcache(); | |
125 | ||
126 | disablecache(); | |
127 | enablecache(); | |
128 | ||
129 | =head1 INHERITANCE | |
130 | ||
131 | Benchmark inherits from no other class, except of course | |
132 | for Exporter. | |
133 | ||
134 | =head1 CAVEATS | |
135 | ||
136 | The real time timing is done using time(2) and | |
137 | the granularity is therefore only one second. | |
138 | ||
139 | Short tests may produce negative figures because perl | |
140 | can appear to take longer to execute the empty loop | |
141 | than a short test; try: | |
142 | ||
143 | timethis(100,'1'); | |
144 | ||
145 | The system time of the null loop might be slightly | |
146 | more than the system time of the loop with the actual | |
147 | code and therefore the difference might end up being < 0. | |
148 | ||
149 | More documentation is needed :-( especially for styles and formats. | |
150 | ||
151 | =head1 AUTHORS | |
152 | ||
153 | Jarkko Hietaniemi <Jarkko.Hietaniemi@hut.fi>, | |
154 | Tim Bunce <Tim.Bunce@ig.co.uk> | |
155 | ||
156 | =head1 MODIFICATION HISTORY | |
157 | ||
158 | September 8th, 1994; by Tim Bunce. | |
159 |