Commit | Line | Data |
a0d0e21e |
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 |
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 | |