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