4 use vars qw($VERSION $XS_VERSION @ISA @EXPORT @EXPORT_OK $AUTOLOAD);
9 @ISA = qw(Exporter DynaLoader);
12 @EXPORT_OK = qw (usleep sleep ualarm alarm gettimeofday time tv_interval
14 ITIMER_REAL ITIMER_VIRTUAL ITIMER_PROF ITIMER_REALPROF
15 d_usleep d_ualarm d_gettimeofday d_getitimer d_setitimer
19 $XS_VERSION = $VERSION;
20 $VERSION = eval $VERSION;
24 ($constname = $AUTOLOAD) =~ s/.*:://;
25 die "&Time::HiRes::constant not defined" if $constname eq 'constant';
26 my ($error, $val) = constant($constname);
27 if ($error) { die $error; }
30 *$AUTOLOAD = sub { $val };
35 bootstrap Time::HiRes;
37 # Preloaded methods go here.
40 # probably could have been done in C
42 $b = [gettimeofday()] unless defined($b);
43 (${$b}[0] - ${$a}[0]) + ((${$b}[1] - ${$a}[1]) / 1_000_000);
46 # Autoload methods go after =cut, and are processed by the autosplit program.
53 Time::HiRes - High resolution alarm, sleep, gettimeofday, interval timers
57 use Time::HiRes qw( usleep ualarm gettimeofday tv_interval );
59 usleep ($microseconds);
61 ualarm ($microseconds);
62 ualarm ($microseconds, $interval_microseconds);
65 ($seconds, $microseconds) = gettimeofday;
67 $elapsed = tv_interval ( $t0, [$seconds, $microseconds]);
68 $elapsed = tv_interval ( $t0, [gettimeofday]);
69 $elapsed = tv_interval ( $t0 );
71 use Time::HiRes qw ( time alarm sleep );
73 $now_fractions = time;
74 sleep ($floating_seconds);
75 alarm ($floating_seconds);
76 alarm ($floating_seconds, $floating_interval);
78 use Time::HiRes qw( setitimer getitimer
79 ITIMER_REAL ITIMER_VIRTUAL ITIMER_PROF ITIMER_REALPROF );
81 setitimer ($which, $floating_seconds, $floating_interval );
86 The Time::HiRes module implements a Perl interface to the usleep,
87 ualarm, gettimeofday, and setitimer/getitimer system calls, in other
88 words, high resolution time and timers. See the EXAMPLES section below
89 and the test scripts for usage; see your system documentation for the
90 description of the underlying nanosleep or usleep, ualarm,
91 gettimeofday, and setitimer/getitimer calls.
93 If your system lacks gettimeofday() or an emulation of it you don't
94 get gettimeofday() or the one-arg form of tv_interval(). If you don't
95 have any of the nanosleep() or usleep() or select() you don't get
96 Time::HiRes::usleep() or Time::HiRes::sleep(). If your system don't
97 have either ualarm() or setitimer() you don't get
98 Time::HiRes::ualarm() or Time::HiRes::alarm().
100 If you try to import an unimplemented function in the C<use> statement
101 it will fail at compile time.
103 If your subsecond sleeping is implemented with nanosleep() instead of
104 usleep(), you can mix subsecond sleeping with signals since
105 nanosleep() does not use signals. This however is unportable, and you
106 should first check for the truth value of &Time::HiRes::d_nanosleep to
107 see whether you have nanosleep, and then read carefully your
108 nanosleep() C API documentation for any peculiarities. (There is no
109 separate interface to call nanosleep(); just use Time::HiRes::sleep()
110 or Time::HiRes::usleep() with small enough values.)
112 Unless using nanosleep for mixing sleeping with signals, also give
113 some thought to whether Perl is the tool you should be using for work
114 requiring nanosecond accuracies.
116 The following functions can be imported from this module.
117 No functions are exported by default.
121 =item gettimeofday ()
123 In array context returns a two-element array with the seconds and
124 microseconds since the epoch. In scalar context returns floating
125 seconds like Time::HiRes::time() (see below).
127 =item usleep ( $useconds )
129 Sleeps for the number of microseconds specified. Returns the number
130 of microseconds actually slept. Can sleep for more than one second
131 unlike the usleep system call. See also Time::HiRes::sleep() below.
133 =item ualarm ( $useconds [, $interval_useconds ] )
135 Issues a ualarm call; the $interval_useconds is optional and
136 will be zero if unspecified, resulting in alarm-like behaviour.
140 tv_interval ( $ref_to_gettimeofday [, $ref_to_later_gettimeofday] )
142 Returns the floating seconds between the two times, which should have
143 been returned by gettimeofday(). If the second argument is omitted,
144 then the current time is used.
148 Returns a floating seconds since the epoch. This function can be
149 imported, resulting in a nice drop-in replacement for the time
150 provided with core Perl, see the EXAMPLES below.
152 B<NOTE 1>: this higher resolution timer can return values either less
153 or more than the core time(), depending on whether your platforms
154 rounds the higher resolution timer values up, down, or to the nearest
155 to get the core time(), but naturally the difference should be never
156 more than half a second.
158 B<NOTE 2>: Since Sunday, September 9th, 2001 at 01:46:40 AM GMT (when
159 the time() seconds since epoch rolled over to 1_000_000_000), the
160 default floating point format of Perl and the seconds since epoch have
161 conspired to produce an apparent bug: if you print the value of
162 Time::HiRes::time() you seem to be getting only five decimals, not six
163 as promised (microseconds). Not to worry, the microseconds are there
164 (assuming your platform supports such granularity in first place).
165 What is going on is that the default floating point format of Perl
166 only outputs 15 digits. In this case that means ten digits before the
167 decimal separator and five after. To see the microseconds you can use
168 either printf/sprintf with "%.6f", or the gettimeofday() function in
169 list context, which will give you the seconds and microseconds as two
172 =item sleep ( $floating_seconds )
174 Sleeps for the specified amount of seconds. Returns the number of
175 seconds actually slept (a floating point value). This function can be
176 imported, resulting in a nice drop-in replacement for the sleep
177 provided with perl, see the EXAMPLES below.
179 =item alarm ( $floating_seconds [, $interval_floating_seconds ] )
181 The SIGALRM signal is sent after the specified number of seconds.
182 Implemented using ualarm(). The $interval_floating_seconds argument
183 is optional and will be zero if unspecified, resulting in alarm()-like
184 behaviour. This function can be imported, resulting in a nice drop-in
185 replacement for the alarm provided with perl, see the EXAMPLES below.
187 B<NOTE 1>: With some operating system and Perl release combinations
188 select() gets restarted by SIGALRM, instead of dropping out of
189 select(). This means that an alarm() followed by a select()
190 may together take the sum of the times specified for the the
191 alarm() and the select(), not just the time of the alarm().
195 setitimer ( $which, $floating_seconds [, $interval_floating_seconds ] )
197 Start up an interval timer: after a certain time, a signal arrives,
198 and more signals may keep arriving at certain intervals. To disable a
199 timer, use $floating_seconds of zero. If the $interval_floating_seconds
200 is set to zero (or unspecified), the timer is disabled B<after> the
201 next delivered signal.
203 Use of interval timers may interfere with alarm(), sleep(),
204 and usleep(). In standard-speak the "interaction is unspecified",
205 which means that I<anything> may happen: it may work, it may not.
207 In scalar context, the remaining time in the timer is returned.
209 In list context, both the remaining time and the interval are returned.
211 There are usually three or four interval timers available: the $which
212 can be ITIMER_REAL, ITIMER_VIRTUAL, ITIMER_PROF, or ITIMER_REALPROF.
213 Note that which ones are available depends: true UNIX platforms have
214 usually all first three, but for example Win32 and Cygwin only have
215 ITIMER_REAL, and only Solaris seems to have ITIMER_REALPROF (which is
216 used to profile multithreaded programs).
218 ITIMER_REAL results in alarm()-like behavior. Time is counted in
219 I<real time>, that is, wallclock time. SIGALRM is delivered when
222 ITIMER_VIRTUAL counts time in (process) I<virtual time>, that is, only
223 when the process is running. In multiprocessor/user/CPU systems this
224 may be more or less than real or wallclock time. (This time is also
225 known as the I<user time>.) SIGVTALRM is delivered when the timer expires.
227 ITIMER_PROF counts time when either the process virtual time or when
228 the operating system is running on behalf of the process (such as I/O).
229 (This time is also known as the I<system time>.) (The sum of user
230 time and system time is known as the I<CPU time>.) SIGPROF is
231 delivered when the timer expires. SIGPROF can interrupt system calls.
233 The semantics of interval timers for multithreaded programs are
234 system-specific, and some systems may support additional interval
235 timers. See your setitimer() documentation.
237 =item getitimer ( $which )
239 Return the remaining time in the interval timer specified by $which.
241 In scalar context, the remaining time is returned.
243 In list context, both the remaining time and the interval are returned.
244 The interval is always what you put in using setitimer().
250 use Time::HiRes qw(usleep ualarm gettimeofday tv_interval);
252 $microseconds = 750_000;
253 usleep $microseconds;
255 # signal alarm in 2.5s & every .1s thereafter
256 ualarm 2_500_000, 100_000;
258 # get seconds and microseconds since the epoch
259 ($s, $usec) = gettimeofday;
261 # measure elapsed time
262 # (could also do by subtracting 2 gettimeofday return values)
263 $t0 = [gettimeofday];
264 # do bunch of stuff here
265 $t1 = [gettimeofday];
267 $t0_t1 = tv_interval $t0, $t1;
269 $elapsed = tv_interval ($t0, [gettimeofday]);
270 $elapsed = tv_interval ($t0); # equivalent code
273 # replacements for time, alarm and sleep that know about
277 $now_fractions = Time::HiRes::time;
278 Time::HiRes::sleep (2.5);
279 Time::HiRes::alarm (10.6666666);
281 use Time::HiRes qw ( time alarm sleep );
282 $now_fractions = time;
286 # Arm an interval timer to go off first at 10 seconds and
287 # after that every 2.5 seconds, in process virtual time
289 use Time::HiRes qw ( setitimer ITIMER_VIRTUAL time );
291 $SIG{VTLARM} = sub { print time, "\n" };
292 setitimer(ITIMER_VIRTUAL, 10, 2.5);
296 In addition to the perl API described above, a C API is available for
297 extension writers. The following C functions are available in the
301 --------------- ----------------------
302 Time::NVtime double (*)()
303 Time::U2time void (*)(UV ret[2])
305 Both functions return equivalent information (like gettimeofday)
306 but with different representations. The names NVtime and U2time
307 were selected mainly because they are operating system independent.
308 (gettimeofday is Unix-centric, though some platforms like VMS have
311 Here is an example of using NVtime from C:
313 double (*myNVtime)();
314 SV **svp = hv_fetch(PL_modglobal, "Time::NVtime", 12, 0);
315 if (!svp) croak("Time::HiRes is required");
316 if (!SvIOK(*svp)) croak("Time::NVtime isn't a function pointer");
317 myNVtime = INT2PTR(double(*)(), SvIV(*svp));
318 printf("The current time is: %f\n", (*myNVtime)());
322 Notice that the core time() maybe rounding rather than truncating.
323 What this means that the core time() may be giving time one second
324 later than gettimeofday(), also known as Time::HiRes::time().
328 D. Wegscheid <wegscd@whirlpool.com>
329 R. Schertler <roderick@argon.org>
330 J. Hietaniemi <jhi@iki.fi>
331 G. Aas <gisle@aas.no>
333 =head1 COPYRIGHT AND LICENSE
335 Copyright (c) 1996-2002 Douglas E. Wegscheid. All rights reserved.
337 Copyright (c) 2002,2003 Jarkko Hietaniemi. All rights reserved.
339 This program is free software; you can redistribute it and/or modify
340 it under the same terms as Perl itself.