1HiRes(3) User Contributed Perl Documentation HiRes(3)
2
6 Time::HiRes - High resolution alarm, sleep, gettimeofday, interval
7 timers
8
10 use Time::HiRes qw( usleep ualarm gettimeofday tv_interval nanosleep
11 clock_gettime clock_getres clock_nanosleep clock
12 stat );
13 usleep ($microseconds);
15 nanosleep ($nanoseconds);
16 ualarm ($microseconds);
18 ualarm ($microseconds, $interval_microseconds);
19 $t0 = [gettimeofday];
21 ($seconds, $microseconds) = gettimeofday;
22 $elapsed = tv_interval ( $t0, [$seconds, $microseconds]);
24 $elapsed = tv_interval ( $t0, [gettimeofday]);
25 $elapsed = tv_interval ( $t0 );
26 use Time::HiRes qw ( time alarm sleep );
28 $now_fractions = time;
30 sleep ($floating_seconds);
31 alarm ($floating_seconds);
32 alarm ($floating_seconds, $floating_interval);
33 use Time::HiRes qw( setitimer getitimer );
35 setitimer ($which, $floating_seconds, $floating_interval );
37 getitimer ($which);
38 use Time::HiRes qw( clock_gettime clock_getres clock_nanosleep
40 ITIMER_REAL ITIMER_VIRTUAL ITIMER_PROF ITIMER_REALPROF );
41 $realtime = clock_gettime(CLOCK_REALTIME);
43 $resolution = clock_getres(CLOCK_REALTIME);
44 clock_nanosleep(CLOCK_REALTIME, 1.5e9);
46 clock_nanosleep(CLOCK_REALTIME, time()*1e9 + 10e9, TIMER_ABSTIME);
47 my $ticktock = clock();
49 use Time::HiRes qw( stat );
51 my @stat = stat("file");
53 my @stat = stat(FH);
54
56 The "Time::HiRes" module implements a Perl interface to the "usleep",
57 "nanosleep", "ualarm", "gettimeofday", and "setitimer"/"getitimer"
58 system calls, in other words, high resolution time and timers. See the
59 "EXAMPLES" section below and the test scripts for usage; see your
60 system documentation for the description of the underlying "nanosleep"
61 or "usleep", "ualarm", "gettimeofday", and "setitimer"/"getitimer"
62 calls.
63 If your system lacks "gettimeofday()" or an emulation of it you don't
65 get "gettimeofday()" or the one-argument form of "tv_interval()". If
66 your system lacks all of "nanosleep()", "usleep()", "select()", and
67 "poll", you don't get "Time::HiRes::usleep()",
68 "Time::HiRes::nanosleep()", or "Time::HiRes::sleep()". If your system
69 lacks both "ualarm()" and "setitimer()" you don't get
70 "Time::HiRes::ualarm()" or "Time::HiRes::alarm()".
71 If you try to import an unimplemented function in the "use" statement
73 it will fail at compile time.
74 If your subsecond sleeping is implemented with "nanosleep()" instead of
76 "usleep()", you can mix subsecond sleeping with signals since
77 "nanosleep()" does not use signals. This, however, is not portable,
78 and you should first check for the truth value of
79 &Time::HiRes::d_nanosleep to see whether you have nanosleep, and then
80 carefully read your "nanosleep()" C API documentation for any
81 peculiarities.
82 If you are using "nanosleep" for something else than mixing sleeping
84 with signals, give some thought to whether Perl is the tool you should
85 be using for work requiring nanosecond accuracies.
86 Remember that unless you are working on a hard realtime system, any
88 clocks and timers will be imprecise, especially so if you are working
89 in a pre-emptive multiuser system. Understand the difference between
90 wallclock time and process time (in UNIX-like systems the sum of user
91 and system times). Any attempt to sleep for X seconds will most
92 probably end up sleeping more than that, but don't be surpised if you
93 end up sleeping slightly less.
94 The following functions can be imported from this module. No functions
96 are exported by default.
97 gettimeofday ()
99 In array context returns a two-element array with the seconds and
100 microseconds since the epoch. In scalar context returns floating
101 seconds like "Time::HiRes::time()" (see below).
102 usleep ( $useconds )
104 Sleeps for the number of microseconds (millionths of a second)
105 specified. Returns the number of microseconds actually slept. Can
106 sleep for more than one second, unlike the "usleep" system call.
107 Can also sleep for zero seconds, which often works like a thread
108 yield. See also "Time::HiRes::usleep()", "Time::HiRes::sleep()",
109 and "Time::HiRes::clock_nanosleep()".
110 Do not expect usleep() to be exact down to one microsecond.
112 nanosleep ( $nanoseconds )
114 Sleeps for the number of nanoseconds (1e9ths of a second)
115 specified. Returns the number of nanoseconds actually slept
116 (accurate only to microseconds, the nearest thousand of them). Can
117 sleep for more than one second. Can also sleep for zero seconds,
118 which often works like a thread yield. See also
119 "Time::HiRes::sleep()", "Time::HiRes::usleep()", and
120 "Time::HiRes::clock_nanosleep()".
121 Do not expect nanosleep() to be exact down to one nanosecond.
123 Getting even accuracy of one thousand nanoseconds is good.
124 ualarm ( $useconds [, $interval_useconds ] )
126 Issues a "ualarm" call; the $interval_useconds is optional and will
127 be zero if unspecified, resulting in "alarm"-like behaviour.
128 Returns the remaining time in the alarm in microseconds, or "undef"
130 if an error occurred.
131 ualarm(0) will cancel an outstanding ualarm().
133 Note that the interaction between alarms and sleeps is unspecified.
135 tv_interval
137 tv_interval ( $ref_to_gettimeofday [, $ref_to_later_gettimeofday] )
138 Returns the floating seconds between the two times, which should
140 have been returned by "gettimeofday()". If the second argument is
141 omitted, then the current time is used.
142 time ()
144 Returns a floating seconds since the epoch. This function can be
145 imported, resulting in a nice drop-in replacement for the "time"
146 provided with core Perl; see the "EXAMPLES" below.
147 NOTE 1: This higher resolution timer can return values either less
149 or more than the core "time()", depending on whether your platform
150 rounds the higher resolution timer values up, down, or to the
151 nearest second to get the core "time()", but naturally the
152 difference should be never more than half a second. See also
153 "clock_getres", if available in your system.
154 NOTE 2: Since Sunday, September 9th, 2001 at 01:46:40 AM GMT, when
156 the "time()" seconds since epoch rolled over to 1_000_000_000, the
157 default floating point format of Perl and the seconds since epoch
158 have conspired to produce an apparent bug: if you print the value
159 of "Time::HiRes::time()" you seem to be getting only five decimals,
160 not six as promised (microseconds). Not to worry, the microseconds
161 are there (assuming your platform supports such granularity in the
162 first place). What is going on is that the default floating point
163 format of Perl only outputs 15 digits. In this case that means ten
164 digits before the decimal separator and five after. To see the
165 microseconds you can use either "printf"/"sprintf" with "%.6f", or
166 the "gettimeofday()" function in list context, which will give you
167 the seconds and microseconds as two separate values.
168 sleep ( $floating_seconds )
170 Sleeps for the specified amount of seconds. Returns the number of
171 seconds actually slept (a floating point value). This function can
172 be imported, resulting in a nice drop-in replacement for the
173 "sleep" provided with perl, see the "EXAMPLES" below.
174 Note that the interaction between alarms and sleeps is unspecified.
176 alarm ( $floating_seconds [, $interval_floating_seconds ] )
178 The "SIGALRM" signal is sent after the specified number of seconds.
179 Implemented using "setitimer()" if available, "ualarm()" if not.
180 The $interval_floating_seconds argument is optional and will be
181 zero if unspecified, resulting in "alarm()"-like behaviour. This
182 function can be imported, resulting in a nice drop-in replacement
183 for the "alarm" provided with perl, see the "EXAMPLES" below.
184 Returns the remaining time in the alarm in seconds, or "undef" if
186 an error occurred.
187 NOTE 1: With some combinations of operating systems and Perl
189 releases "SIGALRM" restarts "select()", instead of interrupting it.
190 This means that an "alarm()" followed by a "select()" may together
191 take the sum of the times specified for the "alarm()" and the
192 "select()", not just the time of the "alarm()".
193 Note that the interaction between alarms and sleeps is unspecified.
195 setitimer ( $which, $floating_seconds [, $interval_floating_seconds ] )
197 Start up an interval timer: after a certain time, a signal ($which)
198 arrives, and more signals may keep arriving at certain intervals.
199 To disable an "itimer", use $floating_seconds of zero. If the
200 $interval_floating_seconds is set to zero (or unspecified), the
201 timer is disabled after the next delivered signal.
202 Use of interval timers may interfere with "alarm()", "sleep()", and
204 "usleep()". In standard-speak the "interaction is unspecified",
205 which means that anything may happen: it may work, it may not.
206 In scalar context, the remaining time in the timer is returned.
208 In list context, both the remaining time and the interval are
210 returned.
211 There are usually three or four interval timers (signals)
213 available: the $which can be "ITIMER_REAL", "ITIMER_VIRTUAL",
214 "ITIMER_PROF", or "ITIMER_REALPROF". Note that which ones are
215 available depends: true UNIX platforms usually have the first
216 three, but only Solaris seems to have "ITIMER_REALPROF" (which is
217 used to profile multithreaded programs). Win32 unfortunately does
218 not haveinterval timers.
219 "ITIMER_REAL" results in "alarm()"-like behaviour. Time is counted
221 in real time; that is, wallclock time. "SIGALRM" is delivered when
222 the timer expires.
223 "ITIMER_VIRTUAL" counts time in (process) virtual time; that is,
225 only when the process is running. In multiprocessor/user/CPU
226 systems this may be more or less than real or wallclock time.
227 (This time is also known as the user time.) "SIGVTALRM" is
228 delivered when the timer expires.
229 "ITIMER_PROF" counts time when either the process virtual time or
231 when the operating system is running on behalf of the process (such
232 as I/O). (This time is also known as the system time.) (The sum
233 of user time and system time is known as the CPU time.) "SIGPROF"
234 is delivered when the timer expires. "SIGPROF" can interrupt
235 system calls.
236 The semantics of interval timers for multithreaded programs are
238 system-specific, and some systems may support additional interval
239 timers. For example, it is unspecified which thread gets the
240 signals. See your "setitimer()" documentation.
241 getitimer ( $which )
243 Return the remaining time in the interval timer specified by
244 $which.
245 In scalar context, the remaining time is returned.
247 In list context, both the remaining time and the interval are
249 returned. The interval is always what you put in using
250 "setitimer()".
251 clock_gettime ( $which )
253 Return as seconds the current value of the POSIX high resolution
254 timer specified by $which. All implementations that support POSIX
255 high resolution timers are supposed to support at least the $which
256 value of "CLOCK_REALTIME", which is supposed to return results
257 close to the results of "gettimeofday", or the number of seconds
258 since 00:00:00:00 January 1, 1970 Greenwich Mean Time (GMT). Do
259 not assume that CLOCK_REALTIME is zero, it might be one, or
260 something else. Another potentially useful (but not available
261 everywhere) value is "CLOCK_MONOTONIC", which guarantees a
262 monotonically increasing time value (unlike time() or
263 gettimeofday(), which can be adjusted). See your system
264 documentation for other possibly supported values.
265 clock_getres ( $which )
267 Return as seconds the resolution of the POSIX high resolution timer
268 specified by $which. All implementations that support POSIX high
269 resolution timers are supposed to support at least the $which value
270 of "CLOCK_REALTIME", see "clock_gettime".
271 clock_nanosleep ( $which, $nanoseconds, $flags = 0)
273 Sleeps for the number of nanoseconds (1e9ths of a second)
274 specified. Returns the number of nanoseconds actually slept. The
275 $which is the "clock id", as with clock_gettime() and
276 clock_getres(). The flags default to zero but "TIMER_ABSTIME" can
277 specified (must be exported explicitly) which means that
278 $nanoseconds is not a time interval (as is the default) but instead
279 an absolute time. Can sleep for more than one second. Can also
280 sleep for zero seconds, which often works like a thread yield. See
281 also "Time::HiRes::sleep()", "Time::HiRes::usleep()", and
282 "Time::HiRes::nanosleep()".
283 Do not expect clock_nanosleep() to be exact down to one nanosecond.
285 Getting even accuracy of one thousand nanoseconds is good.
286 clock()
288 Return as seconds the process time (user + system time) spent by
289 the process since the first call to clock() (the definition is not
290 "since the start of the process", though if you are lucky these
291 times may be quite close to each other, depending on the system).
292 What this means is that you probably need to store the result of
293 your first call to clock(), and subtract that value from the
294 following results of clock().
295 The time returned also includes the process times of the terminated
297 child processes for which wait() has been executed. This value is
298 somewhat like the second value returned by the times() of core
299 Perl, but not necessarily identical. Note that due to backward
300 compatibility limitations the returned value may wrap around at
301 about 2147 seconds or at about 36 minutes.
302 stat
304 stat FH
305 stat EXPR
306 As "stat" in perlfunc but with the access/modify/change file
307 timestamps in subsecond resolution, if the operating system and the
308 filesystem both support such timestamps. To override the standard
309 stat():
310 use Time::HiRes qw(stat);
312 Test for the value of &Time::HiRes::d_hires_stat to find out
314 whether the operating system supports subsecond file timestamps: a
315 value larger than zero means yes. There are unfortunately no easy
316 ways to find out whether the filesystem supports such timestamps.
317 UNIX filesystems often do; NTFS does; FAT doesn't (FAT timestamp
318 granularity is two seconds).
319 A zero return value of &Time::HiRes::d_hires_stat means that
321 Time::HiRes::stat is a no-op passthrough for CORE::stat(), and
322 therefore the timestamps will stay integers. The same thing will
323 happen if the filesystem does not do subsecond timestamps, even if
324 the &Time::HiRes::d_hires_stat is non-zero.
325 In any case do not expect nanosecond resolution, or even a
327 microsecond resolution. Also note that the modify/access
328 timestamps might have different resolutions, and that they need not
329 be synchronized, e.g. if the operations are
330 write
332 stat # t1
333 read
334 stat # t2
335 the access time stamp from t2 need not be greater-than the modify
337 time stamp from t1: it may be equal or less.
338
340 use Time::HiRes qw(usleep ualarm gettimeofday tv_interval);
341 $microseconds = 750_000;
343 usleep($microseconds);
344 # signal alarm in 2.5s & every .1s thereafter
346 ualarm(2_500_000, 100_000);
347 # cancel that ualarm
348 ualarm(0);
349 # get seconds and microseconds since the epoch
351 ($s, $usec) = gettimeofday();
352 # measure elapsed time
354 # (could also do by subtracting 2 gettimeofday return values)
355 $t0 = [gettimeofday];
356 # do bunch of stuff here
357 $t1 = [gettimeofday];
358 # do more stuff here
359 $t0_t1 = tv_interval $t0, $t1;
360 $elapsed = tv_interval ($t0, [gettimeofday]);
362 $elapsed = tv_interval ($t0); # equivalent code
363 #
365 # replacements for time, alarm and sleep that know about
366 # floating seconds
367 #
368 use Time::HiRes;
369 $now_fractions = Time::HiRes::time;
370 Time::HiRes::sleep (2.5);
371 Time::HiRes::alarm (10.6666666);
372 use Time::HiRes qw ( time alarm sleep );
374 $now_fractions = time;
375 sleep (2.5);
376 alarm (10.6666666);
377 # Arm an interval timer to go off first at 10 seconds and
379 # after that every 2.5 seconds, in process virtual time
380 use Time::HiRes qw ( setitimer ITIMER_VIRTUAL time );
382 $SIG{VTALRM} = sub { print time, "\n" };
384 setitimer(ITIMER_VIRTUAL, 10, 2.5);
385 use Time::HiRes qw( clock_gettime clock_getres CLOCK_REALTIME );
387 # Read the POSIX high resolution timer.
388 my $high = clock_getres(CLOCK_REALTIME);
389 # But how accurate we can be, really?
390 my $reso = clock_getres(CLOCK_REALTIME);
391 use Time::HiRes qw( clock_nanosleep TIMER_ABSTIME );
393 clock_nanosleep(CLOCK_REALTIME, 1e6);
394 clock_nanosleep(CLOCK_REALTIME, 2e9, TIMER_ABSTIME);
395 use Time::HiRes qw( clock );
397 my $clock0 = clock();
398 ... # Do something.
399 my $clock1 = clock();
400 my $clockd = $clock1 - $clock0;
401 use Time::HiRes qw( stat );
403 my ($atime, $mtime, $ctime) = (stat("istics"))[8, 9, 10];
404
406 In addition to the perl API described above, a C API is available for
407 extension writers. The following C functions are available in the
408 modglobal hash:
409 name C prototype
411 --------------- ----------------------
412 Time::NVtime double (*)()
413 Time::U2time void (*)(pTHX_ UV ret[2])
414 Both functions return equivalent information (like "gettimeofday") but
416 with different representations. The names "NVtime" and "U2time" were
417 selected mainly because they are operating system independent.
418 ("gettimeofday" is Unix-centric, though some platforms like Win32 and
419 VMS have emulations for it.)
420 Here is an example of using "NVtime" from C:
422 double (*myNVtime)(); /* Returns -1 on failure. */
424 SV **svp = hv_fetch(PL_modglobal, "Time::NVtime", 12, 0);
425 if (!svp) croak("Time::HiRes is required");
426 if (!SvIOK(*svp)) croak("Time::NVtime isn't a function pointer");
427 myNVtime = INT2PTR(double(*)(), SvIV(*svp));
428 printf("The current time is: %f\n", (*myNVtime)());
429
431 useconds or interval more than ...
432 In ualarm() you tried to use number of microseconds or interval (also
433 in microseconds) more than 1_000_000 and setitimer() is not available
434 in your system to emulate that case.
435 negative time not invented yet
437 You tried to use a negative time argument.
438 internal error: useconds < 0 (unsigned ... signed ...)
440 Something went horribly wrong-- the number of microseconds that cannot
441 become negative just became negative. Maybe your compiler is broken?
442 useconds or uinterval equal to or more than 1000000
444 In some platforms it is not possible to get an alarm with subsecond
445 resolution and later than one second.
446 unimplemented in this platform
448 Some calls simply aren't available, real or emulated, on every
449 platform.
450
452 Notice that the core "time()" maybe rounding rather than truncating.
453 What this means is that the core "time()" may be reporting the time as
454 one second later than "gettimeofday()" and "Time::HiRes::time()".
455 Adjusting the system clock (either manually or by services like ntp)
457 may cause problems, especially for long running programs that assume a
458 monotonously increasing time (note that all platforms do not adjust
459 time as gracefully as UNIX ntp does). For example in Win32 (and
460 derived platforms like Cygwin and MinGW) the Time::HiRes::time() may
461 temporarily drift off from the system clock (and the original time())
462 by up to 0.5 seconds. Time::HiRes will notice this eventually and
463 recalibrate. Note that since Time::HiRes 1.77 the
464 clock_gettime(CLOCK_MONOTONIC) might help in this (in case your system
465 supports CLOCK_MONOTONIC).
466 Some systems have APIs but not implementations: for example QNX and
468 Haiku have the interval timer APIs but not the functionality.
469
471 Perl modules BSD::Resource, Time::TAI64.
472 Your system documentation for "clock", "clock_gettime", "clock_getres",
474 "clock_nanosleep", "clock_settime", "getitimer", "gettimeofday",
475 "setitimer", "sleep", "stat", "ualarm".
476
478 D. Wegscheid <wegscd@whirlpool.com> R. Schertler <roderick@argon.org>
479 J. Hietaniemi <jhi@iki.fi> G. Aas <gisle@aas.no>
480
482 Copyright (c) 1996-2002 Douglas E. Wegscheid. All rights reserved.
483 Copyright (c) 2002, 2003, 2004, 2005, 2006, 2007, 2008 Jarkko
485 Hietaniemi. All rights reserved.
486 Copyright (C) 2011, 2012 Andrew Main (Zefram) <zefram@fysh.org>
488 This program is free software; you can redistribute it and/or modify it
490 under the same terms as Perl itself.
491perl v5.16.3 2012-02-01 HiRes(3)