This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Patch 3945 was a bit overkeen - the effective parameter to cando() and
[perl5.git] / ext / Time / HiRes / HiRes.pm
CommitLineData
dcf686c9
JH
1package Time::HiRes;
2
3use strict;
105cd853 4use vars qw($VERSION $XS_VERSION @ISA @EXPORT @EXPORT_OK $AUTOLOAD);
dcf686c9
JH
5
6require Exporter;
3f2ee006 7require DynaLoader;
dcf686c9 8
0cf8ddea 9@ISA = qw(Exporter DynaLoader);
dcf686c9
JH
10
11@EXPORT = qw( );
3c72ec00 12@EXPORT_OK = qw (usleep sleep ualarm alarm gettimeofday time tv_interval
44d3ce20 13 getitimer setitimer nanosleep
3f2ee006
HS
14 ITIMER_REAL ITIMER_VIRTUAL ITIMER_PROF ITIMER_REALPROF
15 d_usleep d_ualarm d_gettimeofday d_getitimer d_setitimer
16 d_nanosleep);
17
3d0346a5 18$VERSION = '1.76';
105cd853
YST
19$XS_VERSION = $VERSION;
20$VERSION = eval $VERSION;
3c72ec00
JH
21
22sub AUTOLOAD {
23 my $constname;
98b50af3
JH
24 ($constname = $AUTOLOAD) =~ s/.*:://;
25 die "&Time::HiRes::constant not defined" if $constname eq 'constant';
26 my ($error, $val) = constant($constname);
0cf8ddea
RGS
27 if ($error) {
28 my (undef,$file,$line) = caller;
29 die "$error at $file line $line.\n";
30 }
3c72ec00
JH
31 {
32 no strict 'refs';
33 *$AUTOLOAD = sub { $val };
34 }
35 goto &$AUTOLOAD;
36}
dcf686c9 37
0cf8ddea 38bootstrap Time::HiRes;
dcf686c9
JH
39
40# Preloaded methods go here.
41
42sub tv_interval {
43 # probably could have been done in C
44 my ($a, $b) = @_;
45 $b = [gettimeofday()] unless defined($b);
46 (${$b}[0] - ${$a}[0]) + ((${$b}[1] - ${$a}[1]) / 1_000_000);
47}
48
dcf686c9
JH
49# Autoload methods go after =cut, and are processed by the autosplit program.
50
511;
52__END__
53
54=head1 NAME
55
f7916ddb 56Time::HiRes - High resolution alarm, sleep, gettimeofday, interval timers
dcf686c9
JH
57
58=head1 SYNOPSIS
59
44d3ce20 60 use Time::HiRes qw( usleep ualarm gettimeofday tv_interval nanosleep );
dcf686c9
JH
61
62 usleep ($microseconds);
44d3ce20 63 nanosleep ($nanoseconds);
dcf686c9
JH
64
65 ualarm ($microseconds);
66 ualarm ($microseconds, $interval_microseconds);
67
68 $t0 = [gettimeofday];
69 ($seconds, $microseconds) = gettimeofday;
70
71 $elapsed = tv_interval ( $t0, [$seconds, $microseconds]);
72 $elapsed = tv_interval ( $t0, [gettimeofday]);
73 $elapsed = tv_interval ( $t0 );
74
75 use Time::HiRes qw ( time alarm sleep );
3c72ec00 76
dcf686c9
JH
77 $now_fractions = time;
78 sleep ($floating_seconds);
79 alarm ($floating_seconds);
80 alarm ($floating_seconds, $floating_interval);
81
3c72ec00 82 use Time::HiRes qw( setitimer getitimer
3f2ee006 83 ITIMER_REAL ITIMER_VIRTUAL ITIMER_PROF ITIMER_REALPROF );
3c72ec00
JH
84
85 setitimer ($which, $floating_seconds, $floating_interval );
86 getitimer ($which);
87
dcf686c9
JH
88=head1 DESCRIPTION
89
4ed0e2d4 90The C<Time::HiRes> module implements a Perl interface to the
44d3ce20
RGS
91C<usleep>, C<nanosleep>, C<ualarm>, C<gettimeofday>, and
92C<setitimer>/C<getitimer> system calls, in other words, high
93resolution time and timers. See the L</EXAMPLES> section below and the
94test scripts for usage; see your system documentation for the
95description of the underlying C<nanosleep> or C<usleep>, C<ualarm>,
96C<gettimeofday>, and C<setitimer>/C<getitimer> calls.
dcf686c9 97
6937b144 98If your system lacks C<gettimeofday()> or an emulation of it you don't
4ed0e2d4
RGS
99get C<gettimeofday()> or the one-argument form of C<tv_interval()>.
100If your system lacks all of C<nanosleep()>, C<usleep()>, and
44d3ce20
RGS
101C<select()>, you don't get C<Time::HiRes::usleep()>,
102C<Time::HiRes::nanosleep()>, or C<Time::HiRes::sleep()>. If your
103system lacks both C<ualarm()> and C<setitimer()> you don't get
104C<Time::HiRes::ualarm()> or C<Time::HiRes::alarm()>.
3f2ee006
HS
105
106If you try to import an unimplemented function in the C<use> statement
107it will fail at compile time.
108
4ed0e2d4
RGS
109If your subsecond sleeping is implemented with C<nanosleep()> instead
110of C<usleep()>, you can mix subsecond sleeping with signals since
64a7a97c
RGS
111C<nanosleep()> does not use signals. This, however, is not portable,
112and you should first check for the truth value of
4ed0e2d4
RGS
113C<&Time::HiRes::d_nanosleep> to see whether you have nanosleep, and
114then carefully read your C<nanosleep()> C API documentation for any
44d3ce20 115peculiarities.
0be47ac6 116
0cf8ddea
RGS
117If you are using C<nanosleep> for something else than mixing sleeping
118with signals, give some thought to whether Perl is the tool you should
119be using for work requiring nanosecond accuracies.
dcf686c9 120
3c72ec00
JH
121The following functions can be imported from this module.
122No functions are exported by default.
dcf686c9
JH
123
124=over 4
125
126=item gettimeofday ()
127
0be47ac6 128In array context returns a two-element array with the seconds and
f7916ddb 129microseconds since the epoch. In scalar context returns floating
6937b144 130seconds like C<Time::HiRes::time()> (see below).
dcf686c9
JH
131
132=item usleep ( $useconds )
133
44d3ce20
RGS
134Sleeps for the number of microseconds (millionths of a second)
135specified. Returns the number of microseconds actually slept. Can
136sleep for more than one second, unlike the C<usleep> system call. See
137also C<Time::HiRes::usleep()> and C<Time::HiRes::sleep()>.
138
139Do not expect usleep() to be exact down to one microsecond.
140
141=item nanosleep ( $nanoseconds )
142
143Sleeps for the number of nanoseconds (1e9ths of a second) specified.
144Returns the number of nanoseconds actually slept (accurate only to
145microseconds, the nearest thousand of them). Can sleep for more than
146one second. See also C<Time::HiRes::sleep()> and
147C<Time::HiRes::usleep()>.
148
149Do not expect nanosleep() to be exact down to one nanosecond.
150Getting even accuracy of one thousand nanoseconds is good.
dcf686c9
JH
151
152=item ualarm ( $useconds [, $interval_useconds ] )
153
6937b144
MJD
154Issues a C<ualarm> call; the C<$interval_useconds> is optional and
155will be zero if unspecified, resulting in C<alarm>-like behaviour.
dcf686c9 156
993164ab 157Note that the interaction between alarms and sleeps is unspecified.
64a7a97c 158
443572f5
RB
159=item tv_interval
160
0be47ac6 161tv_interval ( $ref_to_gettimeofday [, $ref_to_later_gettimeofday] )
dcf686c9 162
f7916ddb 163Returns the floating seconds between the two times, which should have
6937b144 164been returned by C<gettimeofday()>. If the second argument is omitted,
f7916ddb 165then the current time is used.
dcf686c9
JH
166
167=item time ()
168
f7916ddb 169Returns a floating seconds since the epoch. This function can be
6937b144
MJD
170imported, resulting in a nice drop-in replacement for the C<time>
171provided with core Perl; see the L</EXAMPLES> below.
dcf686c9 172
6937b144
MJD
173B<NOTE 1>: This higher resolution timer can return values either less
174or more than the core C<time()>, depending on whether your platform
175rounds the higher resolution timer values up, down, or to the nearest second
176to get the core C<time()>, but naturally the difference should be never
0be47ac6 177more than half a second.
f7916ddb 178
6937b144
MJD
179B<NOTE 2>: Since Sunday, September 9th, 2001 at 01:46:40 AM GMT, when
180the C<time()> seconds since epoch rolled over to 1_000_000_000, the
0be47ac6
JH
181default floating point format of Perl and the seconds since epoch have
182conspired to produce an apparent bug: if you print the value of
4ed0e2d4
RGS
183C<Time::HiRes::time()> you seem to be getting only five decimals, not
184six as promised (microseconds). Not to worry, the microseconds are
64a7a97c 185there (assuming your platform supports such granularity in the first
4ed0e2d4
RGS
186place). What is going on is that the default floating point format of
187Perl only outputs 15 digits. In this case that means ten digits
188before the decimal separator and five after. To see the microseconds
189you can use either C<printf>/C<sprintf> with C<"%.6f">, or the
190C<gettimeofday()> function in list context, which will give you the
191seconds and microseconds as two separate values.
389199d8 192
dcf686c9
JH
193=item sleep ( $floating_seconds )
194
f7916ddb 195Sleeps for the specified amount of seconds. Returns the number of
64a7a97c
RGS
196seconds actually slept (a floating point value). This function can
197be imported, resulting in a nice drop-in replacement for the C<sleep>
6937b144 198provided with perl, see the L</EXAMPLES> below.
dcf686c9 199
993164ab 200Note that the interaction between alarms and sleeps is unspecified.
64a7a97c 201
dcf686c9
JH
202=item alarm ( $floating_seconds [, $interval_floating_seconds ] )
203
6937b144
MJD
204The C<SIGALRM> signal is sent after the specified number of seconds.
205Implemented using C<ualarm()>. The C<$interval_floating_seconds> argument
206is optional and will be zero if unspecified, resulting in C<alarm()>-like
dcf686c9 207behaviour. This function can be imported, resulting in a nice drop-in
6937b144 208replacement for the C<alarm> provided with perl, see the L</EXAMPLES> below.
dcf686c9 209
64a7a97c
RGS
210B<NOTE 1>: With some combinations of operating systems and Perl
211releases C<SIGALRM> restarts C<select()>, instead of interrupting it.
212This means that an C<alarm()> followed by a C<select()> may together
213take the sum of the times specified for the the C<alarm()> and the
214C<select()>, not just the time of the C<alarm()>.
215
993164ab 216Note that the interaction between alarms and sleeps is unspecified.
3f2ee006 217
6937b144 218=item setitimer ( $which, $floating_seconds [, $interval_floating_seconds ] )
3c72ec00 219
09fa32a4 220Start up an interval timer: after a certain time, a signal arrives,
64a7a97c
RGS
221and more signals may keep arriving at certain intervals. To disable
222an "itimer", use C<$floating_seconds> of zero. If the
223C<$interval_floating_seconds> is set to zero (or unspecified), the
224timer is disabled B<after> the next delivered signal.
3c72ec00 225
6937b144
MJD
226Use of interval timers may interfere with C<alarm()>, C<sleep()>,
227and C<usleep()>. In standard-speak the "interaction is unspecified",
0be47ac6 228which means that I<anything> may happen: it may work, it may not.
3c72ec00
JH
229
230In scalar context, the remaining time in the timer is returned.
231
232In list context, both the remaining time and the interval are returned.
233
4ed0e2d4
RGS
234There are usually three or four interval timers available: the
235C<$which> can be C<ITIMER_REAL>, C<ITIMER_VIRTUAL>, C<ITIMER_PROF>, or
236C<ITIMER_REALPROF>. Note that which ones are available depends: true
237UNIX platforms usually have the first three, but (for example) Win32
238and Cygwin have only C<ITIMER_REAL>, and only Solaris seems to have
239C<ITIMER_REALPROF> (which is used to profile multithreaded programs).
3c72ec00 240
993164ab 241C<ITIMER_REAL> results in C<alarm()>-like behaviour. Time is counted in
6937b144 242I<real time>; that is, wallclock time. C<SIGALRM> is delivered when
3c72ec00
JH
243the timer expires.
244
4ed0e2d4
RGS
245C<ITIMER_VIRTUAL> counts time in (process) I<virtual time>; that is,
246only when the process is running. In multiprocessor/user/CPU systems
247this may be more or less than real or wallclock time. (This time is
248also known as the I<user time>.) C<SIGVTALRM> is delivered when the
249timer expires.
3c72ec00 250
6937b144 251C<ITIMER_PROF> counts time when either the process virtual time or when
0be47ac6
JH
252the operating system is running on behalf of the process (such as I/O).
253(This time is also known as the I<system time>.) (The sum of user
6937b144
MJD
254time and system time is known as the I<CPU time>.) C<SIGPROF> is
255delivered when the timer expires. C<SIGPROF> can interrupt system calls.
3c72ec00
JH
256
257The semantics of interval timers for multithreaded programs are
258system-specific, and some systems may support additional interval
6937b144 259timers. See your C<setitimer()> documentation.
3c72ec00
JH
260
261=item getitimer ( $which )
262
6937b144 263Return the remaining time in the interval timer specified by C<$which>.
3c72ec00
JH
264
265In scalar context, the remaining time is returned.
266
267In list context, both the remaining time and the interval are returned.
6937b144 268The interval is always what you put in using C<setitimer()>.
3c72ec00 269
dcf686c9
JH
270=back
271
272=head1 EXAMPLES
273
274 use Time::HiRes qw(usleep ualarm gettimeofday tv_interval);
275
276 $microseconds = 750_000;
277 usleep $microseconds;
278
279 # signal alarm in 2.5s & every .1s thereafter
280 ualarm 2_500_000, 100_000;
281
282 # get seconds and microseconds since the epoch
283 ($s, $usec) = gettimeofday;
284
285 # measure elapsed time
286 # (could also do by subtracting 2 gettimeofday return values)
287 $t0 = [gettimeofday];
288 # do bunch of stuff here
289 $t1 = [gettimeofday];
290 # do more stuff here
291 $t0_t1 = tv_interval $t0, $t1;
0be47ac6 292
dcf686c9
JH
293 $elapsed = tv_interval ($t0, [gettimeofday]);
294 $elapsed = tv_interval ($t0); # equivalent code
295
296 #
297 # replacements for time, alarm and sleep that know about
298 # floating seconds
299 #
300 use Time::HiRes;
301 $now_fractions = Time::HiRes::time;
302 Time::HiRes::sleep (2.5);
303 Time::HiRes::alarm (10.6666666);
0be47ac6 304
dcf686c9
JH
305 use Time::HiRes qw ( time alarm sleep );
306 $now_fractions = time;
307 sleep (2.5);
308 alarm (10.6666666);
309
3c72ec00
JH
310 # Arm an interval timer to go off first at 10 seconds and
311 # after that every 2.5 seconds, in process virtual time
312
313 use Time::HiRes qw ( setitimer ITIMER_VIRTUAL time );
314
36d6c396 315 $SIG{VTALRM} = sub { print time, "\n" };
3c72ec00
JH
316 setitimer(ITIMER_VIRTUAL, 10, 2.5);
317
dcf686c9
JH
318=head1 C API
319
320In addition to the perl API described above, a C API is available for
321extension writers. The following C functions are available in the
322modglobal hash:
323
324 name C prototype
325 --------------- ----------------------
326 Time::NVtime double (*)()
06252d99 327 Time::U2time void (*)(pTHX_ UV ret[2])
dcf686c9 328
6937b144
MJD
329Both functions return equivalent information (like C<gettimeofday>)
330but with different representations. The names C<NVtime> and C<U2time>
dcf686c9 331were selected mainly because they are operating system independent.
56c1b3bd
RGS
332(C<gettimeofday> is Unix-centric, though some platforms like Win32 and
333VMS have emulations for it.)
dcf686c9 334
6937b144 335Here is an example of using C<NVtime> from C:
dcf686c9 336
993164ab 337 double (*myNVtime)(); /* Returns -1 on failure. */
dcf686c9
JH
338 SV **svp = hv_fetch(PL_modglobal, "Time::NVtime", 12, 0);
339 if (!svp) croak("Time::HiRes is required");
340 if (!SvIOK(*svp)) croak("Time::NVtime isn't a function pointer");
356234a5 341 myNVtime = INT2PTR(double(*)(), SvIV(*svp));
dcf686c9
JH
342 printf("The current time is: %f\n", (*myNVtime)());
343
db0b859f
JH
344=head1 DIAGNOSTICS
345
346=head2 negative time not invented yet
347
348You tried to use a negative time argument.
349
350=head2 internal error: useconds < 0 (unsigned ... signed ...)
351
352Something went horribly wrong-- the number of microseconds that cannot
353become negative just became negative. Maybe your compiler is broken?
354
f03b998d
JH
355=head1 CAVEATS
356
6937b144 357Notice that the core C<time()> maybe rounding rather than truncating.
d8cb5b61
RGS
358What this means is that the core C<time()> may be reporting the time
359as one second later than C<gettimeofday()> and C<Time::HiRes::time()>.
360
361Adjusting the system clock (either manually or by services like ntp)
362may cause problems, especially for long running programs that assume
363a monotonously increasing time (note that all platforms do not adjust
364time as gracefully as UNIX ntp does). For example in Win32 (and derived
365platforms like Cygwin and MinGW) the Time::HiRes::time() may temporarily
366drift off from the system clock (and the original time()) by up to 0.5
367seconds. Time::HiRes will notice this eventually and recalibrate.
f03b998d 368
26e22fd9
RGS
369=head1 SEE ALSO
370
371L<BSD::Resource>, L<Time::TAI64>.
372
dcf686c9
JH
373=head1 AUTHORS
374
375D. Wegscheid <wegscd@whirlpool.com>
376R. Schertler <roderick@argon.org>
377J. Hietaniemi <jhi@iki.fi>
378G. Aas <gisle@aas.no>
379
3f2ee006 380=head1 COPYRIGHT AND LICENSE
dcf686c9 381
3f2ee006 382Copyright (c) 1996-2002 Douglas E. Wegscheid. All rights reserved.
dcf686c9 383
0cf8ddea 384Copyright (c) 2002, 2003, 2004, 2005 Jarkko Hietaniemi. All rights reserved.
dcf686c9 385
3f2ee006
HS
386This program is free software; you can redistribute it and/or modify
387it under the same terms as Perl itself.
dcf686c9
JH
388
389=cut