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