Details | Last modification | View Log | RSS feed
Rev | Author | Line No. | Line |
---|---|---|---|
365 | rain-er | 1 | package Time::HiRes; |
2 | |||
3 | use strict; |
||
4 | use vars qw($VERSION $XS_VERSION @ISA @EXPORT @EXPORT_OK $AUTOLOAD); |
||
5 | |||
6 | require Exporter; |
||
7 | require DynaLoader; |
||
8 | |||
9 | @ISA = qw(Exporter DynaLoader); |
||
10 | |||
11 | @EXPORT = qw( ); |
||
12 | @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 | $VERSION = '1.9719'; |
||
27 | $XS_VERSION = $VERSION; |
||
28 | $VERSION = eval $VERSION; |
||
29 | |||
30 | sub AUTOLOAD { |
||
31 | my $constname; |
||
32 | ($constname = $AUTOLOAD) =~ s/.*:://; |
||
33 | # print "AUTOLOAD: constname = $constname ($AUTOLOAD)\n"; |
||
34 | die "&Time::HiRes::constant not defined" if $constname eq 'constant'; |
||
35 | my ($error, $val) = constant($constname); |
||
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 | no strict 'refs'; |
||
43 | *$AUTOLOAD = sub { $val }; |
||
44 | } |
||
45 | goto &$AUTOLOAD; |
||
46 | } |
||
47 | |||
48 | sub import { |
||
49 | my $this = shift; |
||
50 | for my $i (@_) { |
||
51 | if (($i eq 'clock_getres' && !&d_clock_getres) || |
||
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, @_); |
||
63 | } |
||
64 | |||
65 | bootstrap Time::HiRes; |
||
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; |
||
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 |