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