1Time::HiRes(3pm)       Perl Programmers Reference Guide       Time::HiRes(3pm)
2
3
4

NAME

6       Time::HiRes - High resolution alarm, sleep, gettimeofday, interval
7       timers
8

SYNOPSIS

10         use Time::HiRes qw( usleep ualarm gettimeofday tv_interval nanosleep
11                             clock_gettime clock_getres clock_nanosleep clock
12                             stat );
13
14         usleep ($microseconds);
15         nanosleep ($nanoseconds);
16
17         ualarm ($microseconds);
18         ualarm ($microseconds, $interval_microseconds);
19
20         $t0 = [gettimeofday];
21         ($seconds, $microseconds) = gettimeofday;
22
23         $elapsed = tv_interval ( $t0, [$seconds, $microseconds]);
24         $elapsed = tv_interval ( $t0, [gettimeofday]);
25         $elapsed = tv_interval ( $t0 );
26
27         use Time::HiRes qw ( time alarm sleep );
28
29         $now_fractions = time;
30         sleep ($floating_seconds);
31         alarm ($floating_seconds);
32         alarm ($floating_seconds, $floating_interval);
33
34         use Time::HiRes qw( setitimer getitimer );
35
36         setitimer ($which, $floating_seconds, $floating_interval );
37         getitimer ($which);
38
39         use Time::HiRes qw( clock_gettime clock_getres clock_nanosleep
40                             ITIMER_REAL ITIMER_VIRTUAL ITIMER_PROF ITIMER_REALPROF );
41
42         $realtime   = clock_gettime(CLOCK_REALTIME);
43         $resolution = clock_getres(CLOCK_REALTIME);
44
45         clock_nanosleep(CLOCK_REALTIME, 1.5e9);
46         clock_nanosleep(CLOCK_REALTIME, time()*1e9 + 10e9, TIMER_ABSTIME);
47
48         my $ticktock = clock();
49
50         use Time::HiRes qw( stat );
51
52         my @stat = stat("file");
53         my @stat = stat(FH);
54

DESCRIPTION

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
64       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
72       If you try to import an unimplemented function in the "use" statement
73       it will fail at compile time.
74
75       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
83       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
87       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
95       The following functions can be imported from this module.  No functions
96       are exported by default.
97
98       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
103       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
111           Do not expect usleep() to be exact down to one microsecond.
112
113       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
122           Do not expect nanosleep() to be exact down to one nanosecond.
123           Getting even accuracy of one thousand nanoseconds is good.
124
125       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
129           Returns the remaining time in the alarm in microseconds, or "undef"
130           if an error occurred.
131
132           ualarm(0) will cancel an outstanding ualarm().
133
134           Note that the interaction between alarms and sleeps is unspecified.
135
136       tv_interval
137           tv_interval ( $ref_to_gettimeofday [, $ref_to_later_gettimeofday] )
138
139           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
143       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
148           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
155           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
169       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
175           Note that the interaction between alarms and sleeps is unspecified.
176
177       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
185           Returns the remaining time in the alarm in seconds, or "undef" if
186           an error occurred.
187
188           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 the "alarm()" and the
192           "select()", not just the time of the "alarm()".
193
194           Note that the interaction between alarms and sleeps is unspecified.
195
196       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
203           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
207           In scalar context, the remaining time in the timer is returned.
208
209           In list context, both the remaining time and the interval are
210           returned.
211
212           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
220           "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
224           "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
230           "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
237           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
242       getitimer ( $which )
243           Return the remaining time in the interval timer specified by
244           $which.
245
246           In scalar context, the remaining time is returned.
247
248           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
252       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
266       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
272       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
284           Do not expect clock_nanosleep() to be exact down to one nanosecond.
285           Getting even accuracy of one thousand nanoseconds is good.
286
287       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
296           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
303       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
311               use Time::HiRes qw(stat);
312
313           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
320           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
326           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
331               write
332               stat # t1
333               read
334               stat # t2
335
336           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

EXAMPLES

340         use Time::HiRes qw(usleep ualarm gettimeofday tv_interval);
341
342         $microseconds = 750_000;
343         usleep($microseconds);
344
345         # signal alarm in 2.5s & every .1s thereafter
346         ualarm(2_500_000, 100_000);
347         # cancel that ualarm
348         ualarm(0);
349
350         # get seconds and microseconds since the epoch
351         ($s, $usec) = gettimeofday();
352
353         # 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
361         $elapsed = tv_interval ($t0, [gettimeofday]);
362         $elapsed = tv_interval ($t0); # equivalent code
363
364         #
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
373         use Time::HiRes qw ( time alarm sleep );
374         $now_fractions = time;
375         sleep (2.5);
376         alarm (10.6666666);
377
378         # Arm an interval timer to go off first at 10 seconds and
379         # after that every 2.5 seconds, in process virtual time
380
381         use Time::HiRes qw ( setitimer ITIMER_VIRTUAL time );
382
383         $SIG{VTALRM} = sub { print time, "\n" };
384         setitimer(ITIMER_VIRTUAL, 10, 2.5);
385
386         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
392         use Time::HiRes qw( clock_nanosleep TIMER_ABSTIME );
393         clock_nanosleep(CLOCK_REALTIME, 1e6);
394         clock_nanosleep(CLOCK_REALTIME, 2e9, TIMER_ABSTIME);
395
396         use Time::HiRes qw( clock );
397         my $clock0 = clock();
398         ... # Do something.
399         my $clock1 = clock();
400         my $clockd = $clock1 - $clock0;
401
402         use Time::HiRes qw( stat );
403         my ($atime, $mtime, $ctime) = (stat("istics"))[8, 9, 10];
404

C API

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
410         name             C prototype
411         ---------------  ----------------------
412         Time::NVtime     double (*)()
413         Time::U2time     void (*)(pTHX_ UV ret[2])
414
415       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
421       Here is an example of using "NVtime" from C:
422
423         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

DIAGNOSTICS

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
436   negative time not invented yet
437       You tried to use a negative time argument.
438
439   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
443   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
447   unimplemented in this platform
448       Some calls simply aren't available, real or emulated, on every
449       platform.
450

CAVEATS

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
456       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
467       Some systems have APIs but not implementations: for example QNX and
468       Haiku have the interval timer APIs but not the functionality.
469

SEE ALSO

471       Perl modules BSD::Resource, Time::TAI64.
472
473       Your system documentation for "clock", "clock_gettime", "clock_getres",
474       "clock_nanosleep", "clock_settime", "getitimer", "gettimeofday",
475       "setitimer", "sleep", "stat", "ualarm".
476

AUTHORS

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
484       Copyright (c) 2002, 2003, 2004, 2005, 2006, 2007, 2008 Jarkko
485       Hietaniemi.  All rights reserved.
486
487       This program is free software; you can redistribute it and/or modify it
488       under the same terms as Perl itself.
489
490
491
492perl v5.12.4                      2011-06-07                  Time::HiRes(3pm)
Impressum