File | /usr/local/lib/perl5/5.10.1/darwin-2level/Time/HiRes.pm |
Statements Executed | 32 |
Statement Execution Time | 481µs |
Calls | P | F | Exclusive Time |
Inclusive Time |
Subroutine |
---|---|---|---|---|---|
1 | 1 | 2 | 66µs | 66µs | bootstrap (xsub) | Time::HiRes::
1 | 1 | 1 | 23µs | 248µs | import | Time::HiRes::
1 | 1 | 1 | 21µs | 33µs | AUTOLOAD | Time::HiRes::
1 | 1 | 1 | 13µs | 16µs | BEGIN@3 | Time::HiRes::
1 | 1 | 2 | 8µs | 8µs | constant (xsub) | Time::HiRes::
1 | 1 | 1 | 7µs | 94µs | BEGIN@4 | Time::HiRes::
1 | 1 | 1 | 7µs | 18µs | BEGIN@42 | Time::HiRes::
1 | 1 | 2 | 4µs | 4µs | CORE:subst (opcode) | Time::HiRes::
1 | 1 | 1 | 1µs | 1µs | __ANON__[:43] | Time::HiRes::
0 | 0 | 0 | 0s | 0s | tv_interval | Time::HiRes::
Line | State ments |
Time on line |
Calls | Time in subs |
Code |
---|---|---|---|---|---|
1 | package Time::HiRes; | ||||
2 | |||||
3 | 3 | 24µs | 2 | 20µs | # spent 16µs (13+3) within Time::HiRes::BEGIN@3 which was called
# once (13µs+3µs) by SimpleDB::Client::BEGIN@51 at line 3 # spent 16µs making 1 call to Time::HiRes::BEGIN@3
# spent 3µs making 1 call to strict::import |
4 | 3 | 139µs | 2 | 180µs | # spent 94µs (7+86) within Time::HiRes::BEGIN@4 which was called
# once (7µs+86µs) by SimpleDB::Client::BEGIN@51 at line 4 # spent 94µs making 1 call to Time::HiRes::BEGIN@4
# spent 86µs making 1 call to vars::import |
5 | |||||
6 | 1 | 600ns | require Exporter; | ||
7 | 1 | 900ns | require DynaLoader; | ||
8 | |||||
9 | 1 | 13µs | @ISA = qw(Exporter DynaLoader); | ||
10 | |||||
11 | 1 | 200ns | @EXPORT = qw( ); | ||
12 | 1 | 6µs | @EXPORT_OK = qw (usleep sleep ualarm alarm gettimeofday time tv_interval | ||
13 | getitimer setitimer nanosleep clock_gettime clock_getres | ||||
14 | clock clock_nanosleep | ||||
15 | CLOCK_HIGHRES CLOCK_MONOTONIC CLOCK_PROCESS_CPUTIME_ID | ||||
16 | CLOCK_REALTIME CLOCK_SOFTTIME CLOCK_THREAD_CPUTIME_ID | ||||
17 | CLOCK_TIMEOFDAY CLOCKS_PER_SEC | ||||
18 | ITIMER_REAL ITIMER_VIRTUAL ITIMER_PROF ITIMER_REALPROF | ||||
19 | TIMER_ABSTIME | ||||
20 | d_usleep d_ualarm d_gettimeofday d_getitimer d_setitimer | ||||
21 | d_nanosleep d_clock_gettime d_clock_getres | ||||
22 | d_clock d_clock_nanosleep | ||||
23 | stat | ||||
24 | ); | ||||
25 | |||||
26 | 1 | 5µs | $VERSION = '1.9719'; | ||
27 | 1 | 200ns | $XS_VERSION = $VERSION; | ||
28 | 1 | 16µs | $VERSION = eval $VERSION; | ||
29 | |||||
30 | # spent 33µs (21+11) within Time::HiRes::AUTOLOAD which was called
# once (21µs+11µs) by Time::HiRes::import at line 51 | ||||
31 | 8 | 32µs | my $constname; | ||
32 | ($constname = $AUTOLOAD) =~ s/.*:://; # spent 4µs making 1 call to Time::HiRes::CORE:subst | ||||
33 | # print "AUTOLOAD: constname = $constname ($AUTOLOAD)\n"; | ||||
34 | die "&Time::HiRes::constant not defined" if $constname eq 'constant'; | ||||
35 | my ($error, $val) = constant($constname); # spent 8µs making 1 call to Time::HiRes::constant | ||||
36 | # print "AUTOLOAD: error = $error, val = $val\n"; | ||||
37 | if ($error) { | ||||
38 | my (undef,$file,$line) = caller; | ||||
39 | die "$error at $file line $line.\n"; | ||||
40 | } | ||||
41 | { | ||||
42 | 3 | 199µs | 2 | 30µs | # spent 18µs (7+11) within Time::HiRes::BEGIN@42 which was called
# once (7µs+11µs) by SimpleDB::Client::BEGIN@51 at line 42 # spent 18µs making 1 call to Time::HiRes::BEGIN@42
# spent 11µs making 1 call to strict::unimport |
43 | 1 | 3µs | # spent 1µs within Time::HiRes::__ANON__[/usr/local/lib/perl5/5.10.1/darwin-2level/Time/HiRes.pm:43] which was called
# once (1µs+0s) by Time::HiRes::import at line 45 | ||
44 | } | ||||
45 | goto &$AUTOLOAD; # spent 1µs making 1 call to Time::HiRes::__ANON__[Time/HiRes.pm:43] | ||||
46 | } | ||||
47 | |||||
48 | # spent 248µs (23+225) within Time::HiRes::import which was called
# once (23µs+225µs) by SimpleDB::Client::BEGIN@51 at line 51 of ../lib/SimpleDB/Client.pm | ||||
49 | 4 | 16µs | my $this = shift; | ||
50 | for my $i (@_) { | ||||
51 | if (($i eq 'clock_getres' && !&d_clock_getres) || # spent 33µs making 1 call to Time::HiRes::AUTOLOAD | ||||
52 | ($i eq 'clock_gettime' && !&d_clock_gettime) || | ||||
53 | ($i eq 'clock_nanosleep' && !&d_clock_nanosleep) || | ||||
54 | ($i eq 'clock' && !&d_clock) || | ||||
55 | ($i eq 'nanosleep' && !&d_nanosleep) || | ||||
56 | ($i eq 'usleep' && !&d_usleep) || | ||||
57 | ($i eq 'ualarm' && !&d_ualarm)) { | ||||
58 | require Carp; | ||||
59 | Carp::croak("Time::HiRes::$i(): unimplemented in this platform"); | ||||
60 | } | ||||
61 | } | ||||
62 | Time::HiRes->export_to_level(1, $this, @_); # spent 23µs making 1 call to Exporter::export_to_level | ||||
63 | } | ||||
64 | |||||
65 | 1 | 6µs | 1 | 351µs | bootstrap Time::HiRes; # spent 351µs making 1 call to DynaLoader::bootstrap |
66 | |||||
67 | # Preloaded methods go here. | ||||
68 | |||||
69 | sub tv_interval { | ||||
70 | # probably could have been done in C | ||||
71 | my ($a, $b) = @_; | ||||
72 | $b = [gettimeofday()] unless defined($b); | ||||
73 | (${$b}[0] - ${$a}[0]) + ((${$b}[1] - ${$a}[1]) / 1_000_000); | ||||
74 | } | ||||
75 | |||||
76 | # Autoload methods go after =cut, and are processed by the autosplit program. | ||||
77 | |||||
78 | 1 | 20µs | 1; | ||
79 | __END__ | ||||
80 | |||||
81 | =head1 NAME | ||||
82 | |||||
83 | Time::HiRes - High resolution alarm, sleep, gettimeofday, interval timers | ||||
84 | |||||
85 | =head1 SYNOPSIS | ||||
86 | |||||
87 | use Time::HiRes qw( usleep ualarm gettimeofday tv_interval nanosleep | ||||
88 | clock_gettime clock_getres clock_nanosleep clock | ||||
89 | stat ); | ||||
90 | |||||
91 | usleep ($microseconds); | ||||
92 | nanosleep ($nanoseconds); | ||||
93 | |||||
94 | ualarm ($microseconds); | ||||
95 | ualarm ($microseconds, $interval_microseconds); | ||||
96 | |||||
97 | $t0 = [gettimeofday]; | ||||
98 | ($seconds, $microseconds) = gettimeofday; | ||||
99 | |||||
100 | $elapsed = tv_interval ( $t0, [$seconds, $microseconds]); | ||||
101 | $elapsed = tv_interval ( $t0, [gettimeofday]); | ||||
102 | $elapsed = tv_interval ( $t0 ); | ||||
103 | |||||
104 | use Time::HiRes qw ( time alarm sleep ); | ||||
105 | |||||
106 | $now_fractions = time; | ||||
107 | sleep ($floating_seconds); | ||||
108 | alarm ($floating_seconds); | ||||
109 | alarm ($floating_seconds, $floating_interval); | ||||
110 | |||||
111 | use Time::HiRes qw( setitimer getitimer ); | ||||
112 | |||||
113 | setitimer ($which, $floating_seconds, $floating_interval ); | ||||
114 | getitimer ($which); | ||||
115 | |||||
116 | use Time::HiRes qw( clock_gettime clock_getres clock_nanosleep | ||||
117 | ITIMER_REAL ITIMER_VIRTUAL ITIMER_PROF ITIMER_REALPROF ); | ||||
118 | |||||
119 | $realtime = clock_gettime(CLOCK_REALTIME); | ||||
120 | $resolution = clock_getres(CLOCK_REALTIME); | ||||
121 | |||||
122 | clock_nanosleep(CLOCK_REALTIME, 1.5e9); | ||||
123 | clock_nanosleep(CLOCK_REALTIME, time()*1e9 + 10e9, TIMER_ABSTIME); | ||||
124 | |||||
125 | my $ticktock = clock(); | ||||
126 | |||||
127 | use Time::HiRes qw( stat ); | ||||
128 | |||||
129 | my @stat = stat("file"); | ||||
130 | my @stat = stat(FH); | ||||
131 | |||||
132 | =head1 DESCRIPTION | ||||
133 | |||||
134 | The C<Time::HiRes> module implements a Perl interface to the | ||||
135 | C<usleep>, C<nanosleep>, C<ualarm>, C<gettimeofday>, and | ||||
136 | C<setitimer>/C<getitimer> system calls, in other words, high | ||||
137 | resolution time and timers. See the L</EXAMPLES> section below and the | ||||
138 | test scripts for usage; see your system documentation for the | ||||
139 | description of the underlying C<nanosleep> or C<usleep>, C<ualarm>, | ||||
140 | C<gettimeofday>, and C<setitimer>/C<getitimer> calls. | ||||
141 | |||||
142 | If your system lacks C<gettimeofday()> or an emulation of it you don't | ||||
143 | get C<gettimeofday()> or the one-argument form of C<tv_interval()>. | ||||
144 | If your system lacks all of C<nanosleep()>, C<usleep()>, | ||||
145 | C<select()>, and C<poll>, you don't get C<Time::HiRes::usleep()>, | ||||
146 | C<Time::HiRes::nanosleep()>, or C<Time::HiRes::sleep()>. | ||||
147 | If your system lacks both C<ualarm()> and C<setitimer()> you don't get | ||||
148 | C<Time::HiRes::ualarm()> or C<Time::HiRes::alarm()>. | ||||
149 | |||||
150 | If you try to import an unimplemented function in the C<use> statement | ||||
151 | it will fail at compile time. | ||||
152 | |||||
153 | If your subsecond sleeping is implemented with C<nanosleep()> instead | ||||
154 | of C<usleep()>, you can mix subsecond sleeping with signals since | ||||
155 | C<nanosleep()> does not use signals. This, however, is not portable, | ||||
156 | and you should first check for the truth value of | ||||
157 | C<&Time::HiRes::d_nanosleep> to see whether you have nanosleep, and | ||||
158 | then carefully read your C<nanosleep()> C API documentation for any | ||||
159 | peculiarities. | ||||
160 | |||||
161 | If you are using C<nanosleep> for something else than mixing sleeping | ||||
162 | with signals, give some thought to whether Perl is the tool you should | ||||
163 | be using for work requiring nanosecond accuracies. | ||||
164 | |||||
165 | Remember that unless you are working on a I<hard realtime> system, | ||||
166 | any clocks and timers will be imprecise, especially so if you are working | ||||
167 | in a pre-emptive multiuser system. Understand the difference between | ||||
168 | I<wallclock time> and process time (in UNIX-like systems the sum of | ||||
169 | I<user> and I<system> times). Any attempt to sleep for X seconds will | ||||
170 | most probably end up sleeping B<more> than that, but don't be surpised | ||||
171 | if you end up sleeping slightly B<less>. | ||||
172 | |||||
173 | The following functions can be imported from this module. | ||||
174 | No functions are exported by default. | ||||
175 | |||||
176 | =over 4 | ||||
177 | |||||
178 | =item gettimeofday () | ||||
179 | |||||
180 | In array context returns a two-element array with the seconds and | ||||
181 | microseconds since the epoch. In scalar context returns floating | ||||
182 | seconds like C<Time::HiRes::time()> (see below). | ||||
183 | |||||
184 | =item usleep ( $useconds ) | ||||
185 | |||||
186 | Sleeps for the number of microseconds (millionths of a second) | ||||
187 | specified. Returns the number of microseconds actually slept. | ||||
188 | Can sleep for more than one second, unlike the C<usleep> system call. | ||||
189 | Can also sleep for zero seconds, which often works like a I<thread yield>. | ||||
190 | See also C<Time::HiRes::usleep()>, C<Time::HiRes::sleep()>, and | ||||
191 | C<Time::HiRes::clock_nanosleep()>. | ||||
192 | |||||
193 | Do not expect usleep() to be exact down to one microsecond. | ||||
194 | |||||
195 | =item nanosleep ( $nanoseconds ) | ||||
196 | |||||
197 | Sleeps for the number of nanoseconds (1e9ths of a second) specified. | ||||
198 | Returns the number of nanoseconds actually slept (accurate only to | ||||
199 | microseconds, the nearest thousand of them). Can sleep for more than | ||||
200 | one second. Can also sleep for zero seconds, which often works like | ||||
201 | a I<thread yield>. See also C<Time::HiRes::sleep()>, | ||||
202 | C<Time::HiRes::usleep()>, and C<Time::HiRes::clock_nanosleep()>. | ||||
203 | |||||
204 | Do not expect nanosleep() to be exact down to one nanosecond. | ||||
205 | Getting even accuracy of one thousand nanoseconds is good. | ||||
206 | |||||
207 | =item ualarm ( $useconds [, $interval_useconds ] ) | ||||
208 | |||||
209 | Issues a C<ualarm> call; the C<$interval_useconds> is optional and | ||||
210 | will be zero if unspecified, resulting in C<alarm>-like behaviour. | ||||
211 | |||||
212 | Returns the remaining time in the alarm in microseconds, or C<undef> | ||||
213 | if an error occurred. | ||||
214 | |||||
215 | ualarm(0) will cancel an outstanding ualarm(). | ||||
216 | |||||
217 | Note that the interaction between alarms and sleeps is unspecified. | ||||
218 | |||||
219 | =item tv_interval | ||||
220 | |||||
221 | tv_interval ( $ref_to_gettimeofday [, $ref_to_later_gettimeofday] ) | ||||
222 | |||||
223 | Returns the floating seconds between the two times, which should have | ||||
224 | been returned by C<gettimeofday()>. If the second argument is omitted, | ||||
225 | then the current time is used. | ||||
226 | |||||
227 | =item time () | ||||
228 | |||||
229 | Returns a floating seconds since the epoch. This function can be | ||||
230 | imported, resulting in a nice drop-in replacement for the C<time> | ||||
231 | provided with core Perl; see the L</EXAMPLES> below. | ||||
232 | |||||
233 | B<NOTE 1>: This higher resolution timer can return values either less | ||||
234 | or more than the core C<time()>, depending on whether your platform | ||||
235 | rounds the higher resolution timer values up, down, or to the nearest second | ||||
236 | to get the core C<time()>, but naturally the difference should be never | ||||
237 | more than half a second. See also L</clock_getres>, if available | ||||
238 | in your system. | ||||
239 | |||||
240 | B<NOTE 2>: Since Sunday, September 9th, 2001 at 01:46:40 AM GMT, when | ||||
241 | the C<time()> seconds since epoch rolled over to 1_000_000_000, the | ||||
242 | default floating point format of Perl and the seconds since epoch have | ||||
243 | conspired to produce an apparent bug: if you print the value of | ||||
244 | C<Time::HiRes::time()> you seem to be getting only five decimals, not | ||||
245 | six as promised (microseconds). Not to worry, the microseconds are | ||||
246 | there (assuming your platform supports such granularity in the first | ||||
247 | place). What is going on is that the default floating point format of | ||||
248 | Perl only outputs 15 digits. In this case that means ten digits | ||||
249 | before the decimal separator and five after. To see the microseconds | ||||
250 | you can use either C<printf>/C<sprintf> with C<"%.6f">, or the | ||||
251 | C<gettimeofday()> function in list context, which will give you the | ||||
252 | seconds and microseconds as two separate values. | ||||
253 | |||||
254 | =item sleep ( $floating_seconds ) | ||||
255 | |||||
256 | Sleeps for the specified amount of seconds. Returns the number of | ||||
257 | seconds actually slept (a floating point value). This function can | ||||
258 | be imported, resulting in a nice drop-in replacement for the C<sleep> | ||||
259 | provided with perl, see the L</EXAMPLES> below. | ||||
260 | |||||
261 | Note that the interaction between alarms and sleeps is unspecified. | ||||
262 | |||||
263 | =item alarm ( $floating_seconds [, $interval_floating_seconds ] ) | ||||
264 | |||||
265 | The C<SIGALRM> signal is sent after the specified number of seconds. | ||||
266 | Implemented using C<setitimer()> if available, C<ualarm()> if not. | ||||
267 | The C<$interval_floating_seconds> argument is optional and will be | ||||
268 | zero if unspecified, resulting in C<alarm()>-like behaviour. This | ||||
269 | function can be imported, resulting in a nice drop-in replacement for | ||||
270 | the C<alarm> provided with perl, see the L</EXAMPLES> below. | ||||
271 | |||||
272 | Returns the remaining time in the alarm in seconds, or C<undef> | ||||
273 | if an error occurred. | ||||
274 | |||||
275 | B<NOTE 1>: With some combinations of operating systems and Perl | ||||
276 | releases C<SIGALRM> restarts C<select()>, instead of interrupting it. | ||||
277 | This means that an C<alarm()> followed by a C<select()> may together | ||||
278 | take the sum of the times specified for the the C<alarm()> and the | ||||
279 | C<select()>, not just the time of the C<alarm()>. | ||||
280 | |||||
281 | Note that the interaction between alarms and sleeps is unspecified. | ||||
282 | |||||
283 | =item setitimer ( $which, $floating_seconds [, $interval_floating_seconds ] ) | ||||
284 | |||||
285 | Start up an interval timer: after a certain time, a signal ($which) arrives, | ||||
286 | and more signals may keep arriving at certain intervals. To disable | ||||
287 | an "itimer", use C<$floating_seconds> of zero. If the | ||||
288 | C<$interval_floating_seconds> is set to zero (or unspecified), the | ||||
289 | timer is disabled B<after> the next delivered signal. | ||||
290 | |||||
291 | Use of interval timers may interfere with C<alarm()>, C<sleep()>, | ||||
292 | and C<usleep()>. In standard-speak the "interaction is unspecified", | ||||
293 | which means that I<anything> may happen: it may work, it may not. | ||||
294 | |||||
295 | In scalar context, the remaining time in the timer is returned. | ||||
296 | |||||
297 | In list context, both the remaining time and the interval are returned. | ||||
298 | |||||
299 | There are usually three or four interval timers (signals) available: the | ||||
300 | C<$which> can be C<ITIMER_REAL>, C<ITIMER_VIRTUAL>, C<ITIMER_PROF>, or | ||||
301 | C<ITIMER_REALPROF>. Note that which ones are available depends: true | ||||
302 | UNIX platforms usually have the first three, but only Solaris seems to | ||||
303 | have C<ITIMER_REALPROF> (which is used to profile multithreaded programs). | ||||
304 | Win32 unfortunately does not haveinterval timers. | ||||
305 | |||||
306 | C<ITIMER_REAL> results in C<alarm()>-like behaviour. Time is counted in | ||||
307 | I<real time>; that is, wallclock time. C<SIGALRM> is delivered when | ||||
308 | the timer expires. | ||||
309 | |||||
310 | C<ITIMER_VIRTUAL> counts time in (process) I<virtual time>; that is, | ||||
311 | only when the process is running. In multiprocessor/user/CPU systems | ||||
312 | this may be more or less than real or wallclock time. (This time is | ||||
313 | also known as the I<user time>.) C<SIGVTALRM> is delivered when the | ||||
314 | timer expires. | ||||
315 | |||||
316 | C<ITIMER_PROF> counts time when either the process virtual time or when | ||||
317 | the operating system is running on behalf of the process (such as I/O). | ||||
318 | (This time is also known as the I<system time>.) (The sum of user | ||||
319 | time and system time is known as the I<CPU time>.) C<SIGPROF> is | ||||
320 | delivered when the timer expires. C<SIGPROF> can interrupt system calls. | ||||
321 | |||||
322 | The semantics of interval timers for multithreaded programs are | ||||
323 | system-specific, and some systems may support additional interval | ||||
324 | timers. For example, it is unspecified which thread gets the signals. | ||||
325 | See your C<setitimer()> documentation. | ||||
326 | |||||
327 | =item getitimer ( $which ) | ||||
328 | |||||
329 | Return the remaining time in the interval timer specified by C<$which>. | ||||
330 | |||||
331 | In scalar context, the remaining time is returned. | ||||
332 | |||||
333 | In list context, both the remaining time and the interval are returned. | ||||
334 | The interval is always what you put in using C<setitimer()>. | ||||
335 | |||||
336 | =item clock_gettime ( $which ) | ||||
337 | |||||
338 | Return as seconds the current value of the POSIX high resolution timer | ||||
339 | specified by C<$which>. All implementations that support POSIX high | ||||
340 | resolution timers are supposed to support at least the C<$which> value | ||||
341 | of C<CLOCK_REALTIME>, which is supposed to return results close to the | ||||
342 | results of C<gettimeofday>, or the number of seconds since 00:00:00:00 | ||||
343 | January 1, 1970 Greenwich Mean Time (GMT). Do not assume that | ||||
344 | CLOCK_REALTIME is zero, it might be one, or something else. | ||||
345 | Another potentially useful (but not available everywhere) value is | ||||
346 | C<CLOCK_MONOTONIC>, which guarantees a monotonically increasing time | ||||
347 | value (unlike time() or gettimeofday(), which can be adjusted). | ||||
348 | See your system documentation for other possibly supported values. | ||||
349 | |||||
350 | =item clock_getres ( $which ) | ||||
351 | |||||
352 | Return as seconds the resolution of the POSIX high resolution timer | ||||
353 | specified by C<$which>. All implementations that support POSIX high | ||||
354 | resolution timers are supposed to support at least the C<$which> value | ||||
355 | of C<CLOCK_REALTIME>, see L</clock_gettime>. | ||||
356 | |||||
357 | =item clock_nanosleep ( $which, $nanoseconds, $flags = 0) | ||||
358 | |||||
359 | Sleeps for the number of nanoseconds (1e9ths of a second) specified. | ||||
360 | Returns the number of nanoseconds actually slept. The $which is the | ||||
361 | "clock id", as with clock_gettime() and clock_getres(). The flags | ||||
362 | default to zero but C<TIMER_ABSTIME> can specified (must be exported | ||||
363 | explicitly) which means that C<$nanoseconds> is not a time interval | ||||
364 | (as is the default) but instead an absolute time. Can sleep for more | ||||
365 | than one second. Can also sleep for zero seconds, which often works | ||||
366 | like a I<thread yield>. See also C<Time::HiRes::sleep()>, | ||||
367 | C<Time::HiRes::usleep()>, and C<Time::HiRes::nanosleep()>. | ||||
368 | |||||
369 | Do not expect clock_nanosleep() to be exact down to one nanosecond. | ||||
370 | Getting even accuracy of one thousand nanoseconds is good. | ||||
371 | |||||
372 | =item clock() | ||||
373 | |||||
374 | Return as seconds the I<process time> (user + system time) spent by | ||||
375 | the process since the first call to clock() (the definition is B<not> | ||||
376 | "since the start of the process", though if you are lucky these times | ||||
377 | may be quite close to each other, depending on the system). What this | ||||
378 | means is that you probably need to store the result of your first call | ||||
379 | to clock(), and subtract that value from the following results of clock(). | ||||
380 | |||||
381 | The time returned also includes the process times of the terminated | ||||
382 | child processes for which wait() has been executed. This value is | ||||
383 | somewhat like the second value returned by the times() of core Perl, | ||||
384 | but not necessarily identical. Note that due to backward | ||||
385 | compatibility limitations the returned value may wrap around at about | ||||
386 | 2147 seconds or at about 36 minutes. | ||||
387 | |||||
388 | =item stat | ||||
389 | |||||
390 | =item stat FH | ||||
391 | |||||
392 | =item stat EXPR | ||||
393 | |||||
394 | As L<perlfunc/stat> but with the access/modify/change file timestamps | ||||
395 | in subsecond resolution, if the operating system and the filesystem | ||||
396 | both support such timestamps. To override the standard stat(): | ||||
397 | |||||
398 | use Time::HiRes qw(stat); | ||||
399 | |||||
400 | Test for the value of &Time::HiRes::d_hires_stat to find out whether | ||||
401 | the operating system supports subsecond file timestamps: a value | ||||
402 | larger than zero means yes. There are unfortunately no easy | ||||
403 | ways to find out whether the filesystem supports such timestamps. | ||||
404 | UNIX filesystems often do; NTFS does; FAT doesn't (FAT timestamp | ||||
405 | granularity is B<two> seconds). | ||||
406 | |||||
407 | A zero return value of &Time::HiRes::d_hires_stat means that | ||||
408 | Time::HiRes::stat is a no-op passthrough for CORE::stat(), | ||||
409 | and therefore the timestamps will stay integers. The same | ||||
410 | thing will happen if the filesystem does not do subsecond timestamps, | ||||
411 | even if the &Time::HiRes::d_hires_stat is non-zero. | ||||
412 | |||||
413 | In any case do not expect nanosecond resolution, or even a microsecond | ||||
414 | resolution. Also note that the modify/access timestamps might have | ||||
415 | different resolutions, and that they need not be synchronized, e.g. | ||||
416 | if the operations are | ||||
417 | |||||
418 | write | ||||
419 | stat # t1 | ||||
420 | read | ||||
421 | stat # t2 | ||||
422 | |||||
423 | the access time stamp from t2 need not be greater-than the modify | ||||
424 | time stamp from t1: it may be equal or I<less>. | ||||
425 | |||||
426 | =back | ||||
427 | |||||
428 | =head1 EXAMPLES | ||||
429 | |||||
430 | use Time::HiRes qw(usleep ualarm gettimeofday tv_interval); | ||||
431 | |||||
432 | $microseconds = 750_000; | ||||
433 | usleep($microseconds); | ||||
434 | |||||
435 | # signal alarm in 2.5s & every .1s thereafter | ||||
436 | ualarm(2_500_000, 100_000); | ||||
437 | # cancel that ualarm | ||||
438 | ualarm(0); | ||||
439 | |||||
440 | # get seconds and microseconds since the epoch | ||||
441 | ($s, $usec) = gettimeofday(); | ||||
442 | |||||
443 | # measure elapsed time | ||||
444 | # (could also do by subtracting 2 gettimeofday return values) | ||||
445 | $t0 = [gettimeofday]; | ||||
446 | # do bunch of stuff here | ||||
447 | $t1 = [gettimeofday]; | ||||
448 | # do more stuff here | ||||
449 | $t0_t1 = tv_interval $t0, $t1; | ||||
450 | |||||
451 | $elapsed = tv_interval ($t0, [gettimeofday]); | ||||
452 | $elapsed = tv_interval ($t0); # equivalent code | ||||
453 | |||||
454 | # | ||||
455 | # replacements for time, alarm and sleep that know about | ||||
456 | # floating seconds | ||||
457 | # | ||||
458 | use Time::HiRes; | ||||
459 | $now_fractions = Time::HiRes::time; | ||||
460 | Time::HiRes::sleep (2.5); | ||||
461 | Time::HiRes::alarm (10.6666666); | ||||
462 | |||||
463 | use Time::HiRes qw ( time alarm sleep ); | ||||
464 | $now_fractions = time; | ||||
465 | sleep (2.5); | ||||
466 | alarm (10.6666666); | ||||
467 | |||||
468 | # Arm an interval timer to go off first at 10 seconds and | ||||
469 | # after that every 2.5 seconds, in process virtual time | ||||
470 | |||||
471 | use Time::HiRes qw ( setitimer ITIMER_VIRTUAL time ); | ||||
472 | |||||
473 | $SIG{VTALRM} = sub { print time, "\n" }; | ||||
474 | setitimer(ITIMER_VIRTUAL, 10, 2.5); | ||||
475 | |||||
476 | use Time::HiRes qw( clock_gettime clock_getres CLOCK_REALTIME ); | ||||
477 | # Read the POSIX high resolution timer. | ||||
478 | my $high = clock_getres(CLOCK_REALTIME); | ||||
479 | # But how accurate we can be, really? | ||||
480 | my $reso = clock_getres(CLOCK_REALTIME); | ||||
481 | |||||
482 | use Time::HiRes qw( clock_nanosleep TIMER_ABSTIME ); | ||||
483 | clock_nanosleep(CLOCK_REALTIME, 1e6); | ||||
484 | clock_nanosleep(CLOCK_REALTIME, 2e9, TIMER_ABSTIME); | ||||
485 | |||||
486 | use Time::HiRes qw( clock ); | ||||
487 | my $clock0 = clock(); | ||||
488 | ... # Do something. | ||||
489 | my $clock1 = clock(); | ||||
490 | my $clockd = $clock1 - $clock0; | ||||
491 | |||||
492 | use Time::HiRes qw( stat ); | ||||
493 | my ($atime, $mtime, $ctime) = (stat("istics"))[8, 9, 10]; | ||||
494 | |||||
495 | =head1 C API | ||||
496 | |||||
497 | In addition to the perl API described above, a C API is available for | ||||
498 | extension writers. The following C functions are available in the | ||||
499 | modglobal hash: | ||||
500 | |||||
501 | name C prototype | ||||
502 | --------------- ---------------------- | ||||
503 | Time::NVtime double (*)() | ||||
504 | Time::U2time void (*)(pTHX_ UV ret[2]) | ||||
505 | |||||
506 | Both functions return equivalent information (like C<gettimeofday>) | ||||
507 | but with different representations. The names C<NVtime> and C<U2time> | ||||
508 | were selected mainly because they are operating system independent. | ||||
509 | (C<gettimeofday> is Unix-centric, though some platforms like Win32 and | ||||
510 | VMS have emulations for it.) | ||||
511 | |||||
512 | Here is an example of using C<NVtime> from C: | ||||
513 | |||||
514 | double (*myNVtime)(); /* Returns -1 on failure. */ | ||||
515 | SV **svp = hv_fetch(PL_modglobal, "Time::NVtime", 12, 0); | ||||
516 | if (!svp) croak("Time::HiRes is required"); | ||||
517 | if (!SvIOK(*svp)) croak("Time::NVtime isn't a function pointer"); | ||||
518 | myNVtime = INT2PTR(double(*)(), SvIV(*svp)); | ||||
519 | printf("The current time is: %f\n", (*myNVtime)()); | ||||
520 | |||||
521 | =head1 DIAGNOSTICS | ||||
522 | |||||
523 | =head2 useconds or interval more than ... | ||||
524 | |||||
525 | In ualarm() you tried to use number of microseconds or interval (also | ||||
526 | in microseconds) more than 1_000_000 and setitimer() is not available | ||||
527 | in your system to emulate that case. | ||||
528 | |||||
529 | =head2 negative time not invented yet | ||||
530 | |||||
531 | You tried to use a negative time argument. | ||||
532 | |||||
533 | =head2 internal error: useconds < 0 (unsigned ... signed ...) | ||||
534 | |||||
535 | Something went horribly wrong-- the number of microseconds that cannot | ||||
536 | become negative just became negative. Maybe your compiler is broken? | ||||
537 | |||||
538 | =head2 useconds or uinterval equal to or more than 1000000 | ||||
539 | |||||
540 | In some platforms it is not possible to get an alarm with subsecond | ||||
541 | resolution and later than one second. | ||||
542 | |||||
543 | =head2 unimplemented in this platform | ||||
544 | |||||
545 | Some calls simply aren't available, real or emulated, on every platform. | ||||
546 | |||||
547 | =head1 CAVEATS | ||||
548 | |||||
549 | Notice that the core C<time()> maybe rounding rather than truncating. | ||||
550 | What this means is that the core C<time()> may be reporting the time | ||||
551 | as one second later than C<gettimeofday()> and C<Time::HiRes::time()>. | ||||
552 | |||||
553 | Adjusting the system clock (either manually or by services like ntp) | ||||
554 | may cause problems, especially for long running programs that assume | ||||
555 | a monotonously increasing time (note that all platforms do not adjust | ||||
556 | time as gracefully as UNIX ntp does). For example in Win32 (and derived | ||||
557 | platforms like Cygwin and MinGW) the Time::HiRes::time() may temporarily | ||||
558 | drift off from the system clock (and the original time()) by up to 0.5 | ||||
559 | seconds. Time::HiRes will notice this eventually and recalibrate. | ||||
560 | Note that since Time::HiRes 1.77 the clock_gettime(CLOCK_MONOTONIC) | ||||
561 | might help in this (in case your system supports CLOCK_MONOTONIC). | ||||
562 | |||||
563 | Some systems have APIs but not implementations: for example QNX and Haiku | ||||
564 | have the interval timer APIs but not the functionality. | ||||
565 | |||||
566 | =head1 SEE ALSO | ||||
567 | |||||
568 | Perl modules L<BSD::Resource>, L<Time::TAI64>. | ||||
569 | |||||
570 | Your system documentation for C<clock>, C<clock_gettime>, | ||||
571 | C<clock_getres>, C<clock_nanosleep>, C<clock_settime>, C<getitimer>, | ||||
572 | C<gettimeofday>, C<setitimer>, C<sleep>, C<stat>, C<ualarm>. | ||||
573 | |||||
574 | =head1 AUTHORS | ||||
575 | |||||
576 | D. Wegscheid <wegscd@whirlpool.com> | ||||
577 | R. Schertler <roderick@argon.org> | ||||
578 | J. Hietaniemi <jhi@iki.fi> | ||||
579 | G. Aas <gisle@aas.no> | ||||
580 | |||||
581 | =head1 COPYRIGHT AND LICENSE | ||||
582 | |||||
583 | Copyright (c) 1996-2002 Douglas E. Wegscheid. All rights reserved. | ||||
584 | |||||
585 | Copyright (c) 2002, 2003, 2004, 2005, 2006, 2007, 2008 Jarkko Hietaniemi. | ||||
586 | All rights reserved. | ||||
587 | |||||
588 | This program is free software; you can redistribute it and/or modify | ||||
589 | it under the same terms as Perl itself. | ||||
590 | |||||
591 | =cut | ||||
# spent 4µs within Time::HiRes::CORE:subst which was called
# once (4µs+0s) by Time::HiRes::AUTOLOAD at line 32 of Time/HiRes.pm | |||||
# spent 66µs within Time::HiRes::bootstrap which was called
# once (66µs+0s) by DynaLoader::bootstrap at line 227 of DynaLoader.pm | |||||
# spent 8µs within Time::HiRes::constant which was called
# once (8µs+0s) by Time::HiRes::AUTOLOAD at line 35 of Time/HiRes.pm |