This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Re: win32.c bug - handle leak
[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
98718de3 18$VERSION = '1.50';
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
0be47ac6
JH
86The Time::HiRes module implements a Perl interface to the usleep,
87ualarm, gettimeofday, and setitimer/getitimer system calls, in other
88words, high resolution time and timers. See the EXAMPLES section below
89and the test scripts for usage; see your system documentation for the
90description of the underlying nanosleep or usleep, ualarm,
91gettimeofday, and setitimer/getitimer calls.
dcf686c9 92
0be47ac6 93If your system lacks gettimeofday() or an emulation of it you don't
3f2ee006 94get gettimeofday() or the one-arg form of tv_interval(). If you don't
0be47ac6
JH
95have any of the nanosleep() or usleep() or select() you don't get
96Time::HiRes::usleep() or Time::HiRes::sleep(). If your system don't
97have either ualarm() or setitimer() you don't get
98Time::HiRes::ualarm() or 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
103If your subsecond sleeping is implemented with nanosleep() instead of
104usleep(), you can mix subsecond sleeping with signals since
0be47ac6
JH
105nanosleep() does not use signals. This however is unportable, and you
106should first check for the truth value of &Time::HiRes::d_nanosleep to
107see whether you have nanosleep, and then read carefully your
108nanosleep() C API documentation for any peculiarities. (There is no
109separate interface to call nanosleep(); just use Time::HiRes::sleep()
110or Time::HiRes::usleep() with small enough values.)
111
112Unless using nanosleep for mixing sleeping with signals, also give
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
dcf686c9
JH
125seconds like Time::HiRes::time() (see below).
126
127=item usleep ( $useconds )
128
f7916ddb
JH
129Sleeps for the number of microseconds specified. Returns the number
130of microseconds actually slept. Can sleep for more than one second
131unlike the usleep system call. See also Time::HiRes::sleep() below.
dcf686c9
JH
132
133=item ualarm ( $useconds [, $interval_useconds ] )
134
0be47ac6
JH
135Issues a ualarm call; the $interval_useconds is optional and
136will be zero if unspecified, resulting in 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
JH
142Returns the floating seconds between the two times, which should have
143been returned by gettimeofday(). If the second argument is omitted,
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
0be47ac6 149imported, resulting in a nice drop-in replacement for the time
f7916ddb 150provided with core Perl, see the EXAMPLES below.
dcf686c9 151
0be47ac6
JH
152B<NOTE 1>: this higher resolution timer can return values either less
153or more than the core time(), depending on whether your platforms
154rounds the higher resolution timer values up, down, or to the nearest
155to get the core time(), but naturally the difference should be never
156more than half a second.
f7916ddb 157
0be47ac6
JH
158B<NOTE 2>: Since Sunday, September 9th, 2001 at 01:46:40 AM GMT (when
159the time() seconds since epoch rolled over to 1_000_000_000), the
160default floating point format of Perl and the seconds since epoch have
161conspired to produce an apparent bug: if you print the value of
b8ec5d27
JH
162Time::HiRes::time() you seem to be getting only five decimals, not six
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
168either printf/sprintf with "%.6f", or the gettimeofday() function in
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
0be47ac6 176imported, resulting in a nice drop-in replacement for the sleep
f7916ddb 177provided with perl, see the EXAMPLES below.
dcf686c9
JH
178
179=item alarm ( $floating_seconds [, $interval_floating_seconds ] )
180
3f2ee006 181The SIGALRM signal is sent after the specified number of seconds.
f7916ddb 182Implemented using ualarm(). The $interval_floating_seconds argument
0be47ac6 183is optional and will be zero if unspecified, resulting in alarm()-like
dcf686c9 184behaviour. This function can be imported, resulting in a nice drop-in
0be47ac6 185replacement for the alarm provided with perl, see the EXAMPLES below.
dcf686c9 186
0be47ac6
JH
187B<NOTE 1>: With some operating system and Perl release combinations
188select() gets restarted by SIGALRM, instead of dropping out of
189select(). This means that an alarm() followed by a select()
190may together take the sum of the times specified for the the
191alarm() and the select(), not just the time of the alarm().
3f2ee006 192
443572f5
RB
193=item setitimer
194
0be47ac6 195setitimer ( $which, $floating_seconds [, $interval_floating_seconds ] )
3c72ec00 196
09fa32a4 197Start up an interval timer: after a certain time, a signal arrives,
0be47ac6
JH
198and more signals may keep arriving at certain intervals. To disable a
199timer, use $floating_seconds of zero. If the $interval_floating_seconds
200is set to zero (or unspecified), the timer is disabled B<after> the
201next delivered signal.
3c72ec00 202
0be47ac6
JH
203Use of interval timers may interfere with alarm(), sleep(),
204and usleep(). In standard-speak the "interaction is unspecified",
205which means that I<anything> may happen: it may work, it may not.
3c72ec00
JH
206
207In scalar context, the remaining time in the timer is returned.
208
209In list context, both the remaining time and the interval are returned.
210
3f2ee006
HS
211There are usually three or four interval timers available: the $which
212can be ITIMER_REAL, ITIMER_VIRTUAL, ITIMER_PROF, or ITIMER_REALPROF.
213Note that which ones are available depends: true UNIX platforms have
214usually all first three, but for example Win32 and Cygwin only have
215ITIMER_REAL, and only Solaris seems to have ITIMER_REALPROF (which is
216used to profile multithreaded programs).
3c72ec00
JH
217
218ITIMER_REAL results in alarm()-like behavior. Time is counted in
219I<real time>, that is, wallclock time. SIGALRM is delivered when
220the timer expires.
221
222ITIMER_VIRTUAL counts time in (process) I<virtual time>, that is, only
09fa32a4
JH
223when the process is running. In multiprocessor/user/CPU systems this
224may be more or less than real or wallclock time. (This time is also
225known as the I<user time>.) SIGVTALRM is delivered when the timer expires.
3c72ec00
JH
226
227ITIMER_PROF counts time when either the process virtual time or when
0be47ac6
JH
228the 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
230time and system time is known as the I<CPU time>.) SIGPROF is
231delivered when the timer expires. SIGPROF can interrupt system calls.
3c72ec00
JH
232
233The semantics of interval timers for multithreaded programs are
234system-specific, and some systems may support additional interval
235timers. See your setitimer() documentation.
236
237=item getitimer ( $which )
238
239Return the remaining time in the interval timer specified by $which.
240
241In scalar context, the remaining time is returned.
242
243In list context, both the remaining time and the interval are returned.
244The interval is always what you put in using setitimer().
245
dcf686c9
JH
246=back
247
248=head1 EXAMPLES
249
250 use Time::HiRes qw(usleep ualarm gettimeofday tv_interval);
251
252 $microseconds = 750_000;
253 usleep $microseconds;
254
255 # signal alarm in 2.5s & every .1s thereafter
256 ualarm 2_500_000, 100_000;
257
258 # get seconds and microseconds since the epoch
259 ($s, $usec) = gettimeofday;
260
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];
266 # do more stuff here
267 $t0_t1 = tv_interval $t0, $t1;
0be47ac6 268
dcf686c9
JH
269 $elapsed = tv_interval ($t0, [gettimeofday]);
270 $elapsed = tv_interval ($t0); # equivalent code
271
272 #
273 # replacements for time, alarm and sleep that know about
274 # floating seconds
275 #
276 use Time::HiRes;
277 $now_fractions = Time::HiRes::time;
278 Time::HiRes::sleep (2.5);
279 Time::HiRes::alarm (10.6666666);
0be47ac6 280
dcf686c9
JH
281 use Time::HiRes qw ( time alarm sleep );
282 $now_fractions = time;
283 sleep (2.5);
284 alarm (10.6666666);
285
3c72ec00
JH
286 # Arm an interval timer to go off first at 10 seconds and
287 # after that every 2.5 seconds, in process virtual time
288
289 use Time::HiRes qw ( setitimer ITIMER_VIRTUAL time );
290
36d6c396 291 $SIG{VTALRM} = sub { print time, "\n" };
3c72ec00
JH
292 setitimer(ITIMER_VIRTUAL, 10, 2.5);
293
dcf686c9
JH
294=head1 C API
295
296In addition to the perl API described above, a C API is available for
297extension writers. The following C functions are available in the
298modglobal hash:
299
300 name C prototype
301 --------------- ----------------------
302 Time::NVtime double (*)()
303 Time::U2time void (*)(UV ret[2])
304
0be47ac6
JH
305Both functions return equivalent information (like gettimeofday)
306but with different representations. The names NVtime and U2time
dcf686c9 307were selected mainly because they are operating system independent.
0be47ac6
JH
308(gettimeofday is Unix-centric, though some platforms like VMS have
309emulations for it.)
dcf686c9
JH
310
311Here is an example of using NVtime from C:
312
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");
356234a5 317 myNVtime = INT2PTR(double(*)(), SvIV(*svp));
dcf686c9
JH
318 printf("The current time is: %f\n", (*myNVtime)());
319
db0b859f
JH
320=head1 DIAGNOSTICS
321
322=head2 negative time not invented yet
323
324You tried to use a negative time argument.
325
326=head2 internal error: useconds < 0 (unsigned ... signed ...)
327
328Something went horribly wrong-- the number of microseconds that cannot
329become negative just became negative. Maybe your compiler is broken?
330
f03b998d
JH
331=head1 CAVEATS
332
333Notice that the core time() maybe rounding rather than truncating.
334What this means that the core time() may be giving time one second
335later than gettimeofday(), also known as Time::HiRes::time().
336
dcf686c9
JH
337=head1 AUTHORS
338
339D. Wegscheid <wegscd@whirlpool.com>
340R. Schertler <roderick@argon.org>
341J. Hietaniemi <jhi@iki.fi>
342G. Aas <gisle@aas.no>
343
3f2ee006 344=head1 COPYRIGHT AND LICENSE
dcf686c9 345
3f2ee006 346Copyright (c) 1996-2002 Douglas E. Wegscheid. All rights reserved.
dcf686c9 347
0be47ac6 348Copyright (c) 2002,2003 Jarkko Hietaniemi. All rights reserved.
dcf686c9 349
3f2ee006
HS
350This program is free software; you can redistribute it and/or modify
351it under the same terms as Perl itself.
dcf686c9
JH
352
353=cut