Commit | Line | Data |
dcf686c9 |
1 | package Time::HiRes; |
2 | |
3 | use strict; |
3c72ec00 |
4 | use vars qw($VERSION @ISA @EXPORT @EXPORT_OK $AUTOLOAD); |
dcf686c9 |
5 | |
6 | require Exporter; |
3c72ec00 |
7 | use XSLoader; |
dcf686c9 |
8 | |
3c72ec00 |
9 | @ISA = qw(Exporter); |
dcf686c9 |
10 | |
11 | @EXPORT = qw( ); |
3c72ec00 |
12 | @EXPORT_OK = qw (usleep sleep ualarm alarm gettimeofday time tv_interval |
13 | getitimer setitimer ITIMER_REAL ITIMER_VIRTUAL ITIMER_PROF); |
14 | |
76fbd8c4 |
15 | $VERSION = '1.20_00'; |
3c72ec00 |
16 | |
17 | sub AUTOLOAD { |
18 | my $constname; |
19 | ($constname= $AUTOLOAD) =~ s/.*:://; |
20 | my $val = constant($constname, @_ ? $_[0] : 0); |
21 | if ($!) { |
22 | my ($pack,$file,$line) = caller; |
23 | die "Your vendor has not defined Time::HiRes macro $constname, used at $file line $line.\n"; |
24 | } |
25 | { |
26 | no strict 'refs'; |
27 | *$AUTOLOAD = sub { $val }; |
28 | } |
29 | goto &$AUTOLOAD; |
30 | } |
dcf686c9 |
31 | |
3c72ec00 |
32 | XSLoader::load 'Time::HiRes', $VERSION; |
dcf686c9 |
33 | |
34 | # Preloaded methods go here. |
35 | |
36 | sub tv_interval { |
37 | # probably could have been done in C |
38 | my ($a, $b) = @_; |
39 | $b = [gettimeofday()] unless defined($b); |
40 | (${$b}[0] - ${$a}[0]) + ((${$b}[1] - ${$a}[1]) / 1_000_000); |
41 | } |
42 | |
dcf686c9 |
43 | # Autoload methods go after =cut, and are processed by the autosplit program. |
44 | |
45 | 1; |
46 | __END__ |
47 | |
48 | =head1 NAME |
49 | |
50 | Time::HiRes - High resolution ualarm, usleep, and gettimeofday |
51 | |
52 | =head1 SYNOPSIS |
53 | |
54 | use Time::HiRes qw( usleep ualarm gettimeofday tv_interval ); |
55 | |
56 | usleep ($microseconds); |
57 | |
58 | ualarm ($microseconds); |
59 | ualarm ($microseconds, $interval_microseconds); |
60 | |
61 | $t0 = [gettimeofday]; |
62 | ($seconds, $microseconds) = gettimeofday; |
63 | |
64 | $elapsed = tv_interval ( $t0, [$seconds, $microseconds]); |
65 | $elapsed = tv_interval ( $t0, [gettimeofday]); |
66 | $elapsed = tv_interval ( $t0 ); |
67 | |
68 | use Time::HiRes qw ( time alarm sleep ); |
3c72ec00 |
69 | |
dcf686c9 |
70 | $now_fractions = time; |
71 | sleep ($floating_seconds); |
72 | alarm ($floating_seconds); |
73 | alarm ($floating_seconds, $floating_interval); |
74 | |
3c72ec00 |
75 | use Time::HiRes qw( setitimer getitimer |
76 | ITIMER_REAL ITIMER_VIRTUAL ITIMER_PROF ); |
77 | |
78 | setitimer ($which, $floating_seconds, $floating_interval ); |
79 | getitimer ($which); |
80 | |
dcf686c9 |
81 | =head1 DESCRIPTION |
82 | |
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. |
87 | |
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) |
3c72ec00 |
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. |
dcf686c9 |
94 | |
3c72ec00 |
95 | The following functions can be imported from this module. |
96 | No functions are exported by default. |
dcf686c9 |
97 | |
98 | =over 4 |
99 | |
100 | =item gettimeofday () |
101 | |
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). |
105 | |
106 | =item usleep ( $useconds ) |
107 | |
52d72fba |
108 | Issues a usleep for the number of microseconds specified. Returns the |
109 | number of microseconds actually slept. The number of microseconds |
110 | B<must> be between 0 and 1_000_0000 (inclusive): you B<cannot> sleep |
111 | a minute by usleep(60_000_000). See also Time::HiRes::sleep() below. |
dcf686c9 |
112 | |
113 | =item ualarm ( $useconds [, $interval_useconds ] ) |
114 | |
115 | Issues a ualarm call; interval_useconds is optional and will be 0 if |
116 | unspecified, resulting in alarm-like behaviour. |
117 | |
443572f5 |
118 | =item tv_interval |
119 | |
120 | S<tv_interval ( $ref_to_gettimeofday [, $ref_to_later_gettimeofday] )> |
dcf686c9 |
121 | |
122 | Returns the floating seconds between the two times, which should have been |
123 | returned by gettimeofday(). If the second argument is omitted, then the |
124 | current time is used. |
125 | |
126 | =item time () |
127 | |
128 | Returns a floating seconds since the epoch. This function can be imported, |
129 | resulting in a nice drop-in replacement for the C<time> provided with perl, |
130 | see the EXAMPLES below. |
131 | |
b8ec5d27 |
132 | B<NOTE>: Since Sunday, September 9th, 2001 at 01:46:40 AM GMT |
133 | (when the time() seconds since epoch rolled over to 1_000_000_000), |
134 | the default floating point format of Perl and the seconds since epoch |
135 | have conspired to produce an apparent bug: if you print the value of |
136 | Time::HiRes::time() you seem to be getting only five decimals, not six |
137 | as promised (microseconds). Not to worry, the microseconds are there |
138 | (assuming your platform supports such granularity). What is going on |
139 | is that the default floating point format of Perl only outputs 15 |
140 | digits. In this case that means ten digits before the decimal |
141 | separator and five after. To see the microseconds you can use either |
142 | printf/sprintf with C<%.6f>, or the gettimeofday() function in list |
143 | context, which will give you the seconds and microseconds as two |
389199d8 |
144 | separate values. |
145 | |
dcf686c9 |
146 | =item sleep ( $floating_seconds ) |
147 | |
52d72fba |
148 | Converts $floating_seconds to microseconds and issues a usleep for the |
149 | result. Returns the number of seconds actually slept (a floating |
150 | point value). This function can be imported, resulting in a nice |
151 | drop-in replacement for the C<sleep> provided with perl, see the |
152 | EXAMPLES below. |
dcf686c9 |
153 | |
154 | =item alarm ( $floating_seconds [, $interval_floating_seconds ] ) |
155 | |
156 | Converts $floating_seconds and $interval_floating_seconds and issues |
157 | a ualarm for the results. The $interval_floating_seconds argument |
158 | is optional and will be 0 if unspecified, resulting in alarm-like |
159 | behaviour. This function can be imported, resulting in a nice drop-in |
160 | replacement for the C<alarm> provided with perl, see the EXAMPLES below. |
161 | |
443572f5 |
162 | =item setitimer |
163 | |
164 | S<setitimer ( $which, $floating_seconds [, $interval_floating_seconds ] )> |
3c72ec00 |
165 | |
166 | Start up an interval timer: after a certain time, a signal is arrives, |
167 | and more may keep arriving at certain intervals. To disable a timer, |
168 | use time of zero. If interval is set to zero (or unspecified), the |
169 | timer is disabled after the next delivered signal. |
170 | |
171 | Use of interval timers may interfere with alarm(), sleep(), and usleep(). |
172 | In standard-speak the "interaction is unspecified", which means that |
173 | I<anything> may happen: it may work, it may not. |
174 | |
175 | In scalar context, the remaining time in the timer is returned. |
176 | |
177 | In list context, both the remaining time and the interval are returned. |
178 | |
179 | There are three interval timers: the $which can be ITIMER_REAL, |
180 | ITIMER_VIRTUAL, or ITIMER_PROF. |
181 | |
182 | ITIMER_REAL results in alarm()-like behavior. Time is counted in |
183 | I<real time>, that is, wallclock time. SIGALRM is delivered when |
184 | the timer expires. |
185 | |
186 | ITIMER_VIRTUAL counts time in (process) I<virtual time>, that is, only |
187 | when the process is running. In multiprocessing/user/CPU systems this |
188 | may be much less than real time. (This time is also known as the |
189 | I<user time>.) SIGVTALRM is delivered when the timer expires. |
190 | |
191 | ITIMER_PROF counts time when either the process virtual time or when |
192 | the operating system is running on behalf of the process (such as |
193 | I/O). (This time is also known as the I<system time>.) (Collectively |
194 | these times are also known as the I<CPU time>.) SIGPROF is delivered |
195 | when the timer expires. SIGPROF can interrupt system calls. |
196 | |
197 | The semantics of interval timers for multithreaded programs are |
198 | system-specific, and some systems may support additional interval |
199 | timers. See your setitimer() documentation. |
200 | |
201 | =item getitimer ( $which ) |
202 | |
203 | Return the remaining time in the interval timer specified by $which. |
204 | |
205 | In scalar context, the remaining time is returned. |
206 | |
207 | In list context, both the remaining time and the interval are returned. |
208 | The interval is always what you put in using setitimer(). |
209 | |
dcf686c9 |
210 | =back |
211 | |
212 | =head1 EXAMPLES |
213 | |
214 | use Time::HiRes qw(usleep ualarm gettimeofday tv_interval); |
215 | |
216 | $microseconds = 750_000; |
217 | usleep $microseconds; |
218 | |
219 | # signal alarm in 2.5s & every .1s thereafter |
220 | ualarm 2_500_000, 100_000; |
221 | |
222 | # get seconds and microseconds since the epoch |
223 | ($s, $usec) = gettimeofday; |
224 | |
225 | # measure elapsed time |
226 | # (could also do by subtracting 2 gettimeofday return values) |
227 | $t0 = [gettimeofday]; |
228 | # do bunch of stuff here |
229 | $t1 = [gettimeofday]; |
230 | # do more stuff here |
231 | $t0_t1 = tv_interval $t0, $t1; |
232 | |
233 | $elapsed = tv_interval ($t0, [gettimeofday]); |
234 | $elapsed = tv_interval ($t0); # equivalent code |
235 | |
236 | # |
237 | # replacements for time, alarm and sleep that know about |
238 | # floating seconds |
239 | # |
240 | use Time::HiRes; |
241 | $now_fractions = Time::HiRes::time; |
242 | Time::HiRes::sleep (2.5); |
243 | Time::HiRes::alarm (10.6666666); |
244 | |
245 | use Time::HiRes qw ( time alarm sleep ); |
246 | $now_fractions = time; |
247 | sleep (2.5); |
248 | alarm (10.6666666); |
249 | |
3c72ec00 |
250 | # Arm an interval timer to go off first at 10 seconds and |
251 | # after that every 2.5 seconds, in process virtual time |
252 | |
253 | use Time::HiRes qw ( setitimer ITIMER_VIRTUAL time ); |
254 | |
255 | $SIG{VTLARM} = sub { print time, "\n" }; |
256 | setitimer(ITIMER_VIRTUAL, 10, 2.5); |
257 | |
dcf686c9 |
258 | =head1 C API |
259 | |
260 | In addition to the perl API described above, a C API is available for |
261 | extension writers. The following C functions are available in the |
262 | modglobal hash: |
263 | |
264 | name C prototype |
265 | --------------- ---------------------- |
266 | Time::NVtime double (*)() |
267 | Time::U2time void (*)(UV ret[2]) |
268 | |
269 | Both functions return equivalent information (like C<gettimeofday>) |
270 | but with different representations. The names C<NVtime> and C<U2time> |
271 | were selected mainly because they are operating system independent. |
272 | (C<gettimeofday> is Un*x-centric.) |
273 | |
274 | Here is an example of using NVtime from C: |
275 | |
276 | double (*myNVtime)(); |
277 | SV **svp = hv_fetch(PL_modglobal, "Time::NVtime", 12, 0); |
278 | if (!svp) croak("Time::HiRes is required"); |
279 | if (!SvIOK(*svp)) croak("Time::NVtime isn't a function pointer"); |
280 | myNVtime = (double(*)()) SvIV(*svp); |
281 | printf("The current time is: %f\n", (*myNVtime)()); |
282 | |
f03b998d |
283 | =head1 CAVEATS |
284 | |
285 | Notice that the core time() maybe rounding rather than truncating. |
286 | What this means that the core time() may be giving time one second |
287 | later than gettimeofday(), also known as Time::HiRes::time(). |
288 | |
dcf686c9 |
289 | =head1 AUTHORS |
290 | |
291 | D. Wegscheid <wegscd@whirlpool.com> |
292 | R. Schertler <roderick@argon.org> |
293 | J. Hietaniemi <jhi@iki.fi> |
294 | G. Aas <gisle@aas.no> |
295 | |
296 | =head1 REVISION |
297 | |
298 | $Id: HiRes.pm,v 1.20 1999/03/16 02:26:13 wegscd Exp $ |
299 | |
300 | $Log: HiRes.pm,v $ |
301 | Revision 1.20 1999/03/16 02:26:13 wegscd |
302 | Add documentation for NVTime and U2Time. |
303 | |
304 | Revision 1.19 1998/09/30 02:34:42 wegscd |
305 | No changes, bump version. |
306 | |
307 | Revision 1.18 1998/07/07 02:41:35 wegscd |
308 | No changes, bump version. |
309 | |
310 | Revision 1.17 1998/07/02 01:45:13 wegscd |
311 | Bump version to 1.17 |
312 | |
313 | Revision 1.16 1997/11/13 02:06:36 wegscd |
314 | version bump to accomodate HiRes.xs fix. |
315 | |
316 | Revision 1.15 1997/11/11 02:17:59 wegscd |
317 | POD editing, courtesy of Gisle Aas. |
318 | |
319 | Revision 1.14 1997/11/06 03:14:35 wegscd |
320 | Update version # for Makefile.PL and HiRes.xs changes. |
321 | |
322 | Revision 1.13 1997/11/05 05:36:25 wegscd |
323 | change version # for Makefile.pl and HiRes.xs changes. |
324 | |
325 | Revision 1.12 1997/10/13 20:55:33 wegscd |
326 | Force a new version for Makefile.PL changes. |
327 | |
328 | Revision 1.11 1997/09/05 19:59:33 wegscd |
329 | New version to bump version for README and Makefile.PL fixes. |
330 | Fix bad RCS log. |
331 | |
332 | Revision 1.10 1997/05/23 01:11:38 wegscd |
333 | Conditional compilation; EXPORT_FAIL fixes. |
334 | |
335 | Revision 1.2 1996/12/30 13:28:40 wegscd |
336 | Update documentation for what to do when missing ualarm() and friends. |
337 | |
338 | Revision 1.1 1996/10/17 20:53:31 wegscd |
339 | Fix =head1 being next to __END__ so pod2man works |
340 | |
341 | Revision 1.0 1996/09/03 18:25:15 wegscd |
342 | Initial revision |
343 | |
344 | =head1 COPYRIGHT |
345 | |
346 | Copyright (c) 1996-1997 Douglas E. Wegscheid. |
347 | All rights reserved. This program is free software; you can |
348 | redistribute it and/or modify it under the same terms as Perl itself. |
349 | |
350 | =cut |