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