4 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK $AUTOLOAD);
12 @EXPORT_OK = qw (usleep sleep ualarm alarm gettimeofday time tv_interval
13 getitimer setitimer ITIMER_REAL ITIMER_VIRTUAL ITIMER_PROF);
19 ($constname= $AUTOLOAD) =~ s/.*:://;
20 my $val = constant($constname, @_ ? $_[0] : 0);
22 my ($pack,$file,$line) = caller;
23 die "Your vendor has not defined Time::HiRes macro $constname, used at $file line $line.\n";
27 *$AUTOLOAD = sub { $val };
32 XSLoader::load 'Time::HiRes', $VERSION;
34 # Preloaded methods go here.
37 # probably could have been done in C
39 $b = [gettimeofday()] unless defined($b);
40 (${$b}[0] - ${$a}[0]) + ((${$b}[1] - ${$a}[1]) / 1_000_000);
43 # Autoload methods go after =cut, and are processed by the autosplit program.
50 Time::HiRes - High resolution ualarm, usleep, and gettimeofday
54 use Time::HiRes qw( usleep ualarm gettimeofday tv_interval );
56 usleep ($microseconds);
58 ualarm ($microseconds);
59 ualarm ($microseconds, $interval_microseconds);
62 ($seconds, $microseconds) = gettimeofday;
64 $elapsed = tv_interval ( $t0, [$seconds, $microseconds]);
65 $elapsed = tv_interval ( $t0, [gettimeofday]);
66 $elapsed = tv_interval ( $t0 );
68 use Time::HiRes qw ( time alarm sleep );
70 $now_fractions = time;
71 sleep ($floating_seconds);
72 alarm ($floating_seconds);
73 alarm ($floating_seconds, $floating_interval);
75 use Time::HiRes qw( setitimer getitimer
76 ITIMER_REAL ITIMER_VIRTUAL ITIMER_PROF );
78 setitimer ($which, $floating_seconds, $floating_interval );
83 The C<Time::HiRes> module implements a Perl interface to the usleep, ualarm,
84 and gettimeofday system calls. See the EXAMPLES section below and the test
85 scripts for usage; see your system documentation for the description of
86 the underlying gettimeofday, usleep, and ualarm calls.
88 If your system lacks gettimeofday(2) you don't get gettimeofday() or the
89 one-arg form of tv_interval(). If you don't have usleep(3) or select(2)
90 you don't get usleep() or sleep(). If your system don't have ualarm(3)
91 or setitimer(2) you don't get ualarm() or alarm().
92 If you try to import an unimplemented function in the C<use> statement
93 it will fail at compile time.
95 The following functions can be imported from this module.
96 No functions are exported by default.
100 =item gettimeofday ()
102 In array context it returns a 2 element array with the seconds and
103 microseconds since the epoch. In scalar context it returns floating
104 seconds like Time::HiRes::time() (see below).
106 =item usleep ( $useconds )
108 Issues a usleep for the number of microseconds specified. See also
109 Time::HiRes::sleep() below.
111 =item ualarm ( $useconds [, $interval_useconds ] )
113 Issues a ualarm call; interval_useconds is optional and will be 0 if
114 unspecified, resulting in alarm-like behaviour.
116 =item tv_interval ( $ref_to_gettimeofday [, $ref_to_later_gettimeofday] )
118 Returns the floating seconds between the two times, which should have been
119 returned by gettimeofday(). If the second argument is omitted, then the
120 current time is used.
124 Returns a floating seconds since the epoch. This function can be imported,
125 resulting in a nice drop-in replacement for the C<time> provided with perl,
126 see the EXAMPLES below.
128 =item sleep ( $floating_seconds )
130 Converts $floating_seconds to microseconds and issues a usleep for the
131 result. This function can be imported, resulting in a nice drop-in
132 replacement for the C<sleep> provided with perl, see the EXAMPLES below.
134 =item alarm ( $floating_seconds [, $interval_floating_seconds ] )
136 Converts $floating_seconds and $interval_floating_seconds and issues
137 a ualarm for the results. The $interval_floating_seconds argument
138 is optional and will be 0 if unspecified, resulting in alarm-like
139 behaviour. This function can be imported, resulting in a nice drop-in
140 replacement for the C<alarm> provided with perl, see the EXAMPLES below.
142 =item setitimer ( $which, $floating_seconds [, $interval_floating_seconds ] )
144 Start up an interval timer: after a certain time, a signal is arrives,
145 and more may keep arriving at certain intervals. To disable a timer,
146 use time of zero. If interval is set to zero (or unspecified), the
147 timer is disabled after the next delivered signal.
149 Use of interval timers may interfere with alarm(), sleep(), and usleep().
150 In standard-speak the "interaction is unspecified", which means that
151 I<anything> may happen: it may work, it may not.
153 In scalar context, the remaining time in the timer is returned.
155 In list context, both the remaining time and the interval are returned.
157 There are three interval timers: the $which can be ITIMER_REAL,
158 ITIMER_VIRTUAL, or ITIMER_PROF.
160 ITIMER_REAL results in alarm()-like behavior. Time is counted in
161 I<real time>, that is, wallclock time. SIGALRM is delivered when
164 ITIMER_VIRTUAL counts time in (process) I<virtual time>, that is, only
165 when the process is running. In multiprocessing/user/CPU systems this
166 may be much less than real time. (This time is also known as the
167 I<user time>.) SIGVTALRM is delivered when the timer expires.
169 ITIMER_PROF counts time when either the process virtual time or when
170 the operating system is running on behalf of the process (such as
171 I/O). (This time is also known as the I<system time>.) (Collectively
172 these times are also known as the I<CPU time>.) SIGPROF is delivered
173 when the timer expires. SIGPROF can interrupt system calls.
175 The semantics of interval timers for multithreaded programs are
176 system-specific, and some systems may support additional interval
177 timers. See your setitimer() documentation.
179 =item getitimer ( $which )
181 Return the remaining time in the interval timer specified by $which.
183 In scalar context, the remaining time is returned.
185 In list context, both the remaining time and the interval are returned.
186 The interval is always what you put in using setitimer().
192 use Time::HiRes qw(usleep ualarm gettimeofday tv_interval);
194 $microseconds = 750_000;
195 usleep $microseconds;
197 # signal alarm in 2.5s & every .1s thereafter
198 ualarm 2_500_000, 100_000;
200 # get seconds and microseconds since the epoch
201 ($s, $usec) = gettimeofday;
203 # measure elapsed time
204 # (could also do by subtracting 2 gettimeofday return values)
205 $t0 = [gettimeofday];
206 # do bunch of stuff here
207 $t1 = [gettimeofday];
209 $t0_t1 = tv_interval $t0, $t1;
211 $elapsed = tv_interval ($t0, [gettimeofday]);
212 $elapsed = tv_interval ($t0); # equivalent code
215 # replacements for time, alarm and sleep that know about
219 $now_fractions = Time::HiRes::time;
220 Time::HiRes::sleep (2.5);
221 Time::HiRes::alarm (10.6666666);
223 use Time::HiRes qw ( time alarm sleep );
224 $now_fractions = time;
228 # Arm an interval timer to go off first at 10 seconds and
229 # after that every 2.5 seconds, in process virtual time
231 use Time::HiRes qw ( setitimer ITIMER_VIRTUAL time );
233 $SIG{VTLARM} = sub { print time, "\n" };
234 setitimer(ITIMER_VIRTUAL, 10, 2.5);
238 In addition to the perl API described above, a C API is available for
239 extension writers. The following C functions are available in the
243 --------------- ----------------------
244 Time::NVtime double (*)()
245 Time::U2time void (*)(UV ret[2])
247 Both functions return equivalent information (like C<gettimeofday>)
248 but with different representations. The names C<NVtime> and C<U2time>
249 were selected mainly because they are operating system independent.
250 (C<gettimeofday> is Un*x-centric.)
252 Here is an example of using NVtime from C:
254 double (*myNVtime)();
255 SV **svp = hv_fetch(PL_modglobal, "Time::NVtime", 12, 0);
256 if (!svp) croak("Time::HiRes is required");
257 if (!SvIOK(*svp)) croak("Time::NVtime isn't a function pointer");
258 myNVtime = (double(*)()) SvIV(*svp);
259 printf("The current time is: %f\n", (*myNVtime)());
263 D. Wegscheid <wegscd@whirlpool.com>
264 R. Schertler <roderick@argon.org>
265 J. Hietaniemi <jhi@iki.fi>
266 G. Aas <gisle@aas.no>
270 $Id: HiRes.pm,v 1.20 1999/03/16 02:26:13 wegscd Exp $
273 Revision 1.20 1999/03/16 02:26:13 wegscd
274 Add documentation for NVTime and U2Time.
276 Revision 1.19 1998/09/30 02:34:42 wegscd
277 No changes, bump version.
279 Revision 1.18 1998/07/07 02:41:35 wegscd
280 No changes, bump version.
282 Revision 1.17 1998/07/02 01:45:13 wegscd
285 Revision 1.16 1997/11/13 02:06:36 wegscd
286 version bump to accomodate HiRes.xs fix.
288 Revision 1.15 1997/11/11 02:17:59 wegscd
289 POD editing, courtesy of Gisle Aas.
291 Revision 1.14 1997/11/06 03:14:35 wegscd
292 Update version # for Makefile.PL and HiRes.xs changes.
294 Revision 1.13 1997/11/05 05:36:25 wegscd
295 change version # for Makefile.pl and HiRes.xs changes.
297 Revision 1.12 1997/10/13 20:55:33 wegscd
298 Force a new version for Makefile.PL changes.
300 Revision 1.11 1997/09/05 19:59:33 wegscd
301 New version to bump version for README and Makefile.PL fixes.
304 Revision 1.10 1997/05/23 01:11:38 wegscd
305 Conditional compilation; EXPORT_FAIL fixes.
307 Revision 1.2 1996/12/30 13:28:40 wegscd
308 Update documentation for what to do when missing ualarm() and friends.
310 Revision 1.1 1996/10/17 20:53:31 wegscd
311 Fix =head1 being next to __END__ so pod2man works
313 Revision 1.0 1996/09/03 18:25:15 wegscd
318 Copyright (c) 1996-1997 Douglas E. Wegscheid.
319 All rights reserved. This program is free software; you can
320 redistribute it and/or modify it under the same terms as Perl itself.