1Time::HiRes(3pm) Perl Programmers Reference Guide Time::HiRes(3pm)
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 usleep ($microseconds);
14 nanosleep ($nanoseconds);
15 ualarm ($microseconds);
17 ualarm ($microseconds, $interval_microseconds);
18 $t0 = [gettimeofday];
20 ($seconds, $microseconds) = gettimeofday;
21 $elapsed = tv_interval ( $t0, [$seconds, $microseconds]);
23 $elapsed = tv_interval ( $t0, [gettimeofday]);
24 $elapsed = tv_interval ( $t0 );
25 use Time::HiRes qw ( time alarm sleep );
27 $now_fractions = time;
29 sleep ($floating_seconds);
30 alarm ($floating_seconds);
31 alarm ($floating_seconds, $floating_interval);
32 use Time::HiRes qw( setitimer getitimer
34 ITIMER_REAL ITIMER_VIRTUAL ITIMER_PROF ITIMER_REALPROF );
35 setitimer ($which, $floating_seconds, $floating_interval );
37 getitimer ($which);
38 $realtime = clock_gettime(CLOCK_REALTIME);
40 $resolution = clock_getres(CLOCK_REALTIME);
41 clock_nanosleep(CLOCK_REALTIME, 1.5);
43 clock_nanosleep(CLOCK_REALTIME, time() + 10, TIMER_ABSTIME);
44 my $ticktock = clock();
46
48 The "Time::HiRes" module implements a Perl interface to the "usleep",
49 "nanosleep", "ualarm", "gettimeofday", and "setitimer"/"getitimer" sys‐
50 tem calls, in other words, high resolution time and timers. See the
51 "EXAMPLES" section below and the test scripts for usage; see your sys‐
52 tem documentation for the description of the underlying "nanosleep" or
53 "usleep", "ualarm", "gettimeofday", and "setitimer"/"getitimer" calls.
54 If your system lacks "gettimeofday()" or an emulation of it you don't
56 get "gettimeofday()" or the one-argument form of "tv_interval()". If
57 your system lacks all of "nanosleep()", "usleep()", "select()", and
58 "poll", you don't get "Time::HiRes::usleep()",
59 "Time::HiRes::nanosleep()", or "Time::HiRes::sleep()". If your system
60 lacks both "ualarm()" and "setitimer()" you don't get
61 "Time::HiRes::ualarm()" or "Time::HiRes::alarm()".
62 If you try to import an unimplemented function in the "use" statement
64 it will fail at compile time.
65 If your subsecond sleeping is implemented with "nanosleep()" instead of
67 "usleep()", you can mix subsecond sleeping with signals since
68 "nanosleep()" does not use signals. This, however, is not portable,
69 and you should first check for the truth value of
70 &Time::HiRes::d_nanosleep to see whether you have nanosleep, and then
71 carefully read your "nanosleep()" C API documentation for any peculiar‐
72 ities.
73 If you are using "nanosleep" for something else than mixing sleeping
75 with signals, give some thought to whether Perl is the tool you should
76 be using for work requiring nanosecond accuracies.
77 The following functions can be imported from this module. No functions
79 are exported by default.
80 gettimeofday ()
82 In array context returns a two-element array with the seconds and
83 microseconds since the epoch. In scalar context returns floating
84 seconds like "Time::HiRes::time()" (see below).
85 usleep ( $useconds )
87 Sleeps for the number of microseconds (millionths of a second)
88 specified. Returns the number of microseconds actually slept. Can
89 sleep for more than one second, unlike the "usleep" system call.
90 Can also sleep for zero seconds, which often works like a thread
91 yield. See also "Time::HiRes::usleep()", "Time::HiRes::sleep()",
92 and "Time::HiRes::clock_nanosleep()".
93 Do not expect usleep() to be exact down to one microsecond.
95 nanosleep ( $nanoseconds )
97 Sleeps for the number of nanoseconds (1e9ths of a second) speci‐
98 fied. Returns the number of nanoseconds actually slept (accurate
99 only to microseconds, the nearest thousand of them). Can sleep for
100 more than one second. Can also sleep for zero seconds, which often
101 works like a thread yield. See also "Time::HiRes::sleep()",
102 "Time::HiRes::usleep()", and "Time::HiRes::clock_nanosleep()".
103 Do not expect nanosleep() to be exact down to one nanosecond. Get‐
105 ting even accuracy of one thousand nanoseconds is good.
106 ualarm ( $useconds [, $interval_useconds ] )
108 Issues a "ualarm" call; the $interval_useconds is optional and will
109 be zero if unspecified, resulting in "alarm"-like behaviour.
110 Note that the interaction between alarms and sleeps is unspecified.
112 tv_interval
114 tv_interval ( $ref_to_gettimeofday [, $ref_to_later_gettimeofday] )
115 Returns the floating seconds between the two times, which should
117 have been returned by "gettimeofday()". If the second argument is
118 omitted, then the current time is used.
119 time ()
121 Returns a floating seconds since the epoch. This function can be
122 imported, resulting in a nice drop-in replacement for the "time"
123 provided with core Perl; see the "EXAMPLES" below.
124 NOTE 1: This higher resolution timer can return values either less
126 or more than the core "time()", depending on whether your platform
127 rounds the higher resolution timer values up, down, or to the near‐
128 est second to get the core "time()", but naturally the difference
129 should be never more than half a second. See also "clock_getres",
130 if available in your system.
131 NOTE 2: Since Sunday, September 9th, 2001 at 01:46:40 AM GMT, when
133 the "time()" seconds since epoch rolled over to 1_000_000_000, the
134 default floating point format of Perl and the seconds since epoch
135 have conspired to produce an apparent bug: if you print the value
136 of "Time::HiRes::time()" you seem to be getting only five decimals,
137 not six as promised (microseconds). Not to worry, the microseconds
138 are there (assuming your platform supports such granularity in the
139 first place). What is going on is that the default floating point
140 format of Perl only outputs 15 digits. In this case that means ten
141 digits before the decimal separator and five after. To see the
142 microseconds you can use either "printf"/"sprintf" with "%.6f", or
143 the "gettimeofday()" function in list context, which will give you
144 the seconds and microseconds as two separate values.
145 sleep ( $floating_seconds )
147 Sleeps for the specified amount of seconds. Returns the number of
148 seconds actually slept (a floating point value). This function can
149 be imported, resulting in a nice drop-in replacement for the
150 "sleep" provided with perl, see the "EXAMPLES" below.
151 Note that the interaction between alarms and sleeps is unspecified.
153 alarm ( $floating_seconds [, $interval_floating_seconds ] )
155 The "SIGALRM" signal is sent after the specified number of seconds.
156 Implemented using "ualarm()". The $interval_floating_seconds argu‐
157 ment is optional and will be zero if unspecified, resulting in
158 "alarm()"-like behaviour. This function can be imported, resulting
159 in a nice drop-in replacement for the "alarm" provided with perl,
160 see the "EXAMPLES" below.
161 NOTE 1: With some combinations of operating systems and Perl
163 releases "SIGALRM" restarts "select()", instead of interrupting it.
164 This means that an "alarm()" followed by a "select()" may together
165 take the sum of the times specified for the the "alarm()" and the
166 "select()", not just the time of the "alarm()".
167 Note that the interaction between alarms and sleeps is unspecified.
169 setitimer ( $which, $floating_seconds [, $interval_floating_seconds ] )
171 Start up an interval timer: after a certain time, a signal arrives,
172 and more signals may keep arriving at certain intervals. To dis‐
173 able an "itimer", use $floating_seconds of zero. If the $inter‐
174 val_floating_seconds is set to zero (or unspecified), the timer is
175 disabled after the next delivered signal.
176 Use of interval timers may interfere with "alarm()", "sleep()", and
178 "usleep()". In standard-speak the "interaction is unspecified",
179 which means that anything may happen: it may work, it may not.
180 In scalar context, the remaining time in the timer is returned.
182 In list context, both the remaining time and the interval are
184 returned.
185 There are usually three or four interval timers available: the
187 $which can be "ITIMER_REAL", "ITIMER_VIRTUAL", "ITIMER_PROF", or
188 "ITIMER_REALPROF". Note that which ones are available depends:
189 true UNIX platforms usually have the first three, but (for example)
190 Win32 and Cygwin have only "ITIMER_REAL", and only Solaris seems to
191 have "ITIMER_REALPROF" (which is used to profile multithreaded pro‐
192 grams).
193 "ITIMER_REAL" results in "alarm()"-like behaviour. Time is counted
195 in real time; that is, wallclock time. "SIGALRM" is delivered when
196 the timer expires.
197 "ITIMER_VIRTUAL" counts time in (process) virtual time; that is,
199 only when the process is running. In multiprocessor/user/CPU sys‐
200 tems this may be more or less than real or wallclock time. (This
201 time is also known as the user time.) "SIGVTALRM" is delivered
202 when the timer expires.
203 "ITIMER_PROF" counts time when either the process virtual time or
205 when the operating system is running on behalf of the process (such
206 as I/O). (This time is also known as the system time.) (The sum
207 of user time and system time is known as the CPU time.) "SIGPROF"
208 is delivered when the timer expires. "SIGPROF" can interrupt sys‐
209 tem calls.
210 The semantics of interval timers for multithreaded programs are
212 system-specific, and some systems may support additional interval
213 timers. See your "setitimer()" documentation.
214 getitimer ( $which )
216 Return the remaining time in the interval timer specified by
217 $which.
218 In scalar context, the remaining time is returned.
220 In list context, both the remaining time and the interval are
222 returned. The interval is always what you put in using
223 "setitimer()".
224 clock_gettime ( $which )
226 Return as seconds the current value of the POSIX high resolution
227 timer specified by $which. All implementations that support POSIX
228 high resolution timers are supposed to support at least the $which
229 value of "CLOCK_REALTIME", which is supposed to return results
230 close to the results of "gettimeofday", or the number of seconds
231 since 00:00:00:00 January 1, 1970 Greenwich Mean Time (GMT). Do
232 not assume that CLOCK_REALTIME is zero, it might be one, or some‐
233 thing else. Another potentially useful (but not available every‐
234 where) value is "CLOCK_MONOTONIC", which guarantees a monotonically
235 increasing time value (unlike time(), which can be adjusted). See
236 your system documentation for other possibly supported values.
237 clock_getres ( $which )
239 Return as seconds the resolution of the POSIX high resolution timer
240 specified by $which. All implementations that support POSIX high
241 resolution timers are supposed to support at least the $which value
242 of "CLOCK_REALTIME", see "clock_gettime".
243 clock_nanosleep ( $which, $seconds, $flags = 0)
245 Sleeps for the number of seconds (1e9ths of a second) specified.
246 Returns the number of seconds actually slept. The $which is the
247 "clock id", as with clock_gettime() and clock_getres(). The flags
248 default to zero but "TIMER_ABSTIME" can specified (must be exported
249 explicitly) which means that $nanoseconds is not a time interval
250 (as is the default) but instead an absolute time. Can sleep for
251 more than one second. Can also sleep for zero seconds, which often
252 works like a thread yield. See also "Time::HiRes::sleep()",
253 "Time::HiRes::usleep()", and "Time::HiRes::nanosleep()".
254 Do not expect clock_nanosleep() to be exact down to one nanosecond.
256 Getting even accuracy of one thousand nanoseconds is good.
257 clock()
259 Return as seconds the process time (user + system time) spent by
260 the process since the first call to clock() (the definition is not
261 "since the start of the process", though if you are lucky these
262 times may be quite close to each other, depending on the system).
263 What this means is that you probably need to store the result of
264 your first call to clock(), and subtract that value from the fol‐
265 lowing results of clock().
266 The time returned also includes the process times of the terminated
268 child processes for which wait() has been executed. This value is
269 somewhat like the second value returned by the times() of core
270 Perl, but not necessarily identical. Note that due to backward
271 compatibility limitations the returned value may wrap around at
272 about 2147 seconds or at about 36 minutes.
273
275 use Time::HiRes qw(usleep ualarm gettimeofday tv_interval);
276 $microseconds = 750_000;
278 usleep($microseconds);
279 # signal alarm in 2.5s & every .1s thereafter
281 ualarm(2_500_000, 100_000);
282 # get seconds and microseconds since the epoch
284 ($s, $usec) = gettimeofday();
285 # measure elapsed time
287 # (could also do by subtracting 2 gettimeofday return values)
288 $t0 = [gettimeofday];
289 # do bunch of stuff here
290 $t1 = [gettimeofday];
291 # do more stuff here
292 $t0_t1 = tv_interval $t0, $t1;
293 $elapsed = tv_interval ($t0, [gettimeofday]);
295 $elapsed = tv_interval ($t0); # equivalent code
296 #
298 # replacements for time, alarm and sleep that know about
299 # floating seconds
300 #
301 use Time::HiRes;
302 $now_fractions = Time::HiRes::time;
303 Time::HiRes::sleep (2.5);
304 Time::HiRes::alarm (10.6666666);
305 use Time::HiRes qw ( time alarm sleep );
307 $now_fractions = time;
308 sleep (2.5);
309 alarm (10.6666666);
310 # Arm an interval timer to go off first at 10 seconds and
312 # after that every 2.5 seconds, in process virtual time
313 use Time::HiRes qw ( setitimer ITIMER_VIRTUAL time );
315 $SIG{VTALRM} = sub { print time, "\n" };
317 setitimer(ITIMER_VIRTUAL, 10, 2.5);
318 use Time::HiRes qw( clock_gettime clock_getres CLOCK_REALTIME );
320 # Read the POSIX high resolution timer.
321 my $high = clock_getres(CLOCK_REALTIME);
322 # But how accurate we can be, really?
323 my $reso = clock_getres(CLOCK_REALTIME);
324 use Time::HiRes qw( clock_nanosleep TIMER_ABSTIME );
326 clock_nanosleep(CLOCK_REALTIME, 1e6);
327 clock_nanosleep(CLOCK_REALTIME, 2e9, TIMER_ABSTIME);
328 use Time::HiRes qw( clock );
330 my $clock0 = clock();
331 ... # Do something.
332 my $clock1 = clock();
333 my $clockd = $clock1 - $clock0;
334
336 In addition to the perl API described above, a C API is available for
337 extension writers. The following C functions are available in the mod‐
338 global hash:
339 name C prototype
341 --------------- ----------------------
342 Time::NVtime double (*)()
343 Time::U2time void (*)(pTHX_ UV ret[2])
344 Both functions return equivalent information (like "gettimeofday") but
346 with different representations. The names "NVtime" and "U2time" were
347 selected mainly because they are operating system independent. ("get‐
348 timeofday" is Unix-centric, though some platforms like Win32 and VMS
349 have emulations for it.)
350 Here is an example of using "NVtime" from C:
352 double (*myNVtime)(); /* Returns -1 on failure. */
354 SV **svp = hv_fetch(PL_modglobal, "Time::NVtime", 12, 0);
355 if (!svp) croak("Time::HiRes is required");
356 if (!SvIOK(*svp)) croak("Time::NVtime isn't a function pointer");
357 myNVtime = INT2PTR(double(*)(), SvIV(*svp));
358 printf("The current time is: %f\n", (*myNVtime)());
359
361 negative time not invented yet
362 You tried to use a negative time argument.
364 internal error: useconds < 0 (unsigned ... signed ...)
366 Something went horribly wrong-- the number of microseconds that cannot
368 become negative just became negative. Maybe your compiler is broken?
369
371 Notice that the core "time()" maybe rounding rather than truncating.
372 What this means is that the core "time()" may be reporting the time as
373 one second later than "gettimeofday()" and "Time::HiRes::time()".
374 Adjusting the system clock (either manually or by services like ntp)
376 may cause problems, especially for long running programs that assume a
377 monotonously increasing time (note that all platforms do not adjust
378 time as gracefully as UNIX ntp does). For example in Win32 (and
379 derived platforms like Cygwin and MinGW) the Time::HiRes::time() may
380 temporarily drift off from the system clock (and the original time())
381 by up to 0.5 seconds. Time::HiRes will notice this eventually and
382 recalibrate. Note that since Time::HiRes 1.77 the clock_get‐
383 time(CLOCK_MONOTONIC) might help in this (in case your system supports
384 CLOCK_MONOTONIC).
385
387 Perl modules BSD::Resource, Time::TAI64.
388 Your system documentation for "clock_gettime", "clock_settime", "get‐
390 timeofday", "getitimer", "setitimer", "ualarm".
391
393 D. Wegscheid <wegscd@whirlpool.com> R. Schertler <roderick@argon.org>
394 J. Hietaniemi <jhi@iki.fi> G. Aas <gisle@aas.no>
395
397 Copyright (c) 1996-2002 Douglas E. Wegscheid. All rights reserved.
398 Copyright (c) 2002, 2003, 2004, 2005 Jarkko Hietaniemi. All rights
400 reserved.
401 This program is free software; you can redistribute it and/or modify it
403 under the same terms as Perl itself.
404perl v5.8.8 2001-09-21 Time::HiRes(3pm)