Commit | Line | Data |
dcf686c9 |
1 | package Time::HiRes; |
2 | |
3 | use strict; |
105cd853 |
4 | use vars qw($VERSION $XS_VERSION @ISA @EXPORT @EXPORT_OK $AUTOLOAD); |
dcf686c9 |
5 | |
6 | require Exporter; |
3f2ee006 |
7 | require DynaLoader; |
dcf686c9 |
8 | |
3f2ee006 |
9 | @ISA = qw(Exporter DynaLoader); |
dcf686c9 |
10 | |
11 | @EXPORT = qw( ); |
3c72ec00 |
12 | @EXPORT_OK = qw (usleep sleep ualarm alarm gettimeofday time tv_interval |
3f2ee006 |
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 | |
0be47ac6 |
18 | $VERSION = '1.44'; |
105cd853 |
19 | $XS_VERSION = $VERSION; |
20 | $VERSION = eval $VERSION; |
3c72ec00 |
21 | |
22 | sub AUTOLOAD { |
23 | my $constname; |
98b50af3 |
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 |
28 | { |
29 | no strict 'refs'; |
30 | *$AUTOLOAD = sub { $val }; |
31 | } |
32 | goto &$AUTOLOAD; |
33 | } |
dcf686c9 |
34 | |
3f2ee006 |
35 | bootstrap Time::HiRes; |
dcf686c9 |
36 | |
37 | # Preloaded methods go here. |
38 | |
39 | sub 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 |
46 | # Autoload methods go after =cut, and are processed by the autosplit program. |
47 | |
48 | 1; |
49 | __END__ |
50 | |
51 | =head1 NAME |
52 | |
f7916ddb |
53 | Time::HiRes - High resolution alarm, sleep, gettimeofday, interval timers |
dcf686c9 |
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 |
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 |
80 | |
81 | setitimer ($which, $floating_seconds, $floating_interval ); |
82 | getitimer ($which); |
83 | |
dcf686c9 |
84 | =head1 DESCRIPTION |
85 | |
0be47ac6 |
86 | The Time::HiRes module implements a Perl interface to the usleep, |
87 | ualarm, gettimeofday, and setitimer/getitimer system calls, in other |
88 | words, high resolution time and timers. See the EXAMPLES section below |
89 | and the test scripts for usage; see your system documentation for the |
90 | description of the underlying nanosleep or usleep, ualarm, |
91 | gettimeofday, and setitimer/getitimer calls. |
dcf686c9 |
92 | |
0be47ac6 |
93 | If your system lacks gettimeofday() or an emulation of it you don't |
3f2ee006 |
94 | get gettimeofday() or the one-arg form of tv_interval(). If you don't |
0be47ac6 |
95 | have any of the nanosleep() or usleep() or select() you don't get |
96 | Time::HiRes::usleep() or Time::HiRes::sleep(). If your system don't |
97 | have either ualarm() or setitimer() you don't get |
98 | Time::HiRes::ualarm() or Time::HiRes::alarm(). |
3f2ee006 |
99 | |
100 | If you try to import an unimplemented function in the C<use> statement |
101 | it will fail at compile time. |
102 | |
103 | If your subsecond sleeping is implemented with nanosleep() instead of |
104 | usleep(), you can mix subsecond sleeping with signals since |
0be47ac6 |
105 | nanosleep() does not use signals. This however is unportable, and you |
106 | should first check for the truth value of &Time::HiRes::d_nanosleep to |
107 | see whether you have nanosleep, and then read carefully your |
108 | nanosleep() C API documentation for any peculiarities. (There is no |
109 | separate interface to call nanosleep(); just use Time::HiRes::sleep() |
110 | or Time::HiRes::usleep() with small enough values.) |
111 | |
112 | Unless using nanosleep for mixing sleeping with signals, also give |
113 | some thought to whether Perl is the tool you should be using for work |
114 | requiring nanosecond accuracies. |
dcf686c9 |
115 | |
3c72ec00 |
116 | The following functions can be imported from this module. |
117 | No functions are exported by default. |
dcf686c9 |
118 | |
119 | =over 4 |
120 | |
121 | =item gettimeofday () |
122 | |
0be47ac6 |
123 | In array context returns a two-element array with the seconds and |
f7916ddb |
124 | microseconds since the epoch. In scalar context returns floating |
dcf686c9 |
125 | seconds like Time::HiRes::time() (see below). |
126 | |
127 | =item usleep ( $useconds ) |
128 | |
f7916ddb |
129 | Sleeps for the number of microseconds specified. Returns the number |
130 | of microseconds actually slept. Can sleep for more than one second |
131 | unlike the usleep system call. See also Time::HiRes::sleep() below. |
dcf686c9 |
132 | |
133 | =item ualarm ( $useconds [, $interval_useconds ] ) |
134 | |
0be47ac6 |
135 | Issues a ualarm call; the $interval_useconds is optional and |
136 | will be zero if unspecified, resulting in alarm-like behaviour. |
dcf686c9 |
137 | |
443572f5 |
138 | =item tv_interval |
139 | |
0be47ac6 |
140 | tv_interval ( $ref_to_gettimeofday [, $ref_to_later_gettimeofday] ) |
dcf686c9 |
141 | |
f7916ddb |
142 | Returns the floating seconds between the two times, which should have |
143 | been returned by gettimeofday(). If the second argument is omitted, |
144 | then the current time is used. |
dcf686c9 |
145 | |
146 | =item time () |
147 | |
f7916ddb |
148 | Returns a floating seconds since the epoch. This function can be |
0be47ac6 |
149 | imported, resulting in a nice drop-in replacement for the time |
f7916ddb |
150 | provided with core Perl, see the EXAMPLES below. |
dcf686c9 |
151 | |
0be47ac6 |
152 | B<NOTE 1>: this higher resolution timer can return values either less |
153 | or more than the core time(), depending on whether your platforms |
154 | rounds the higher resolution timer values up, down, or to the nearest |
155 | to get the core time(), but naturally the difference should be never |
156 | more than half a second. |
f7916ddb |
157 | |
0be47ac6 |
158 | B<NOTE 2>: Since Sunday, September 9th, 2001 at 01:46:40 AM GMT (when |
159 | the time() seconds since epoch rolled over to 1_000_000_000), the |
160 | default floating point format of Perl and the seconds since epoch have |
161 | conspired to produce an apparent bug: if you print the value of |
b8ec5d27 |
162 | Time::HiRes::time() you seem to be getting only five decimals, not six |
163 | as promised (microseconds). Not to worry, the microseconds are there |
0be47ac6 |
164 | (assuming your platform supports such granularity in first place). |
165 | What is going on is that the default floating point format of Perl |
166 | only outputs 15 digits. In this case that means ten digits before the |
167 | decimal separator and five after. To see the microseconds you can use |
168 | either printf/sprintf with "%.6f", or the gettimeofday() function in |
169 | list context, which will give you the seconds and microseconds as two |
389199d8 |
170 | separate values. |
171 | |
dcf686c9 |
172 | =item sleep ( $floating_seconds ) |
173 | |
f7916ddb |
174 | Sleeps for the specified amount of seconds. Returns the number of |
175 | seconds actually slept (a floating point value). This function can be |
0be47ac6 |
176 | imported, resulting in a nice drop-in replacement for the sleep |
f7916ddb |
177 | provided with perl, see the EXAMPLES below. |
dcf686c9 |
178 | |
179 | =item alarm ( $floating_seconds [, $interval_floating_seconds ] ) |
180 | |
3f2ee006 |
181 | The SIGALRM signal is sent after the specified number of seconds. |
f7916ddb |
182 | Implemented using ualarm(). The $interval_floating_seconds argument |
0be47ac6 |
183 | is optional and will be zero if unspecified, resulting in alarm()-like |
dcf686c9 |
184 | behaviour. This function can be imported, resulting in a nice drop-in |
0be47ac6 |
185 | replacement for the alarm provided with perl, see the EXAMPLES below. |
dcf686c9 |
186 | |
0be47ac6 |
187 | B<NOTE 1>: With some operating system and Perl release combinations |
188 | select() gets restarted by SIGALRM, instead of dropping out of |
189 | select(). This means that an alarm() followed by a select() |
190 | may together take the sum of the times specified for the the |
191 | alarm() and the select(), not just the time of the alarm(). |
3f2ee006 |
192 | |
443572f5 |
193 | =item setitimer |
194 | |
0be47ac6 |
195 | setitimer ( $which, $floating_seconds [, $interval_floating_seconds ] ) |
3c72ec00 |
196 | |
09fa32a4 |
197 | Start up an interval timer: after a certain time, a signal arrives, |
0be47ac6 |
198 | and more signals may keep arriving at certain intervals. To disable a |
199 | timer, use $floating_seconds of zero. If the $interval_floating_seconds |
200 | is set to zero (or unspecified), the timer is disabled B<after> the |
201 | next delivered signal. |
3c72ec00 |
202 | |
0be47ac6 |
203 | Use of interval timers may interfere with alarm(), sleep(), |
204 | and usleep(). In standard-speak the "interaction is unspecified", |
205 | which means that I<anything> may happen: it may work, it may not. |
3c72ec00 |
206 | |
207 | In scalar context, the remaining time in the timer is returned. |
208 | |
209 | In list context, both the remaining time and the interval are returned. |
210 | |
3f2ee006 |
211 | There are usually three or four interval timers available: the $which |
212 | can be ITIMER_REAL, ITIMER_VIRTUAL, ITIMER_PROF, or ITIMER_REALPROF. |
213 | Note that which ones are available depends: true UNIX platforms have |
214 | usually all first three, but for example Win32 and Cygwin only have |
215 | ITIMER_REAL, and only Solaris seems to have ITIMER_REALPROF (which is |
216 | used to profile multithreaded programs). |
3c72ec00 |
217 | |
218 | ITIMER_REAL results in alarm()-like behavior. Time is counted in |
219 | I<real time>, that is, wallclock time. SIGALRM is delivered when |
220 | the timer expires. |
221 | |
222 | ITIMER_VIRTUAL counts time in (process) I<virtual time>, that is, only |
09fa32a4 |
223 | when the process is running. In multiprocessor/user/CPU systems this |
224 | may be more or less than real or wallclock time. (This time is also |
225 | known as the I<user time>.) SIGVTALRM is delivered when the timer expires. |
3c72ec00 |
226 | |
227 | ITIMER_PROF counts time when either the process virtual time or when |
0be47ac6 |
228 | the 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 |
230 | time and system time is known as the I<CPU time>.) SIGPROF is |
231 | delivered when the timer expires. SIGPROF can interrupt system calls. |
3c72ec00 |
232 | |
233 | The semantics of interval timers for multithreaded programs are |
234 | system-specific, and some systems may support additional interval |
235 | timers. See your setitimer() documentation. |
236 | |
237 | =item getitimer ( $which ) |
238 | |
239 | Return the remaining time in the interval timer specified by $which. |
240 | |
241 | In scalar context, the remaining time is returned. |
242 | |
243 | In list context, both the remaining time and the interval are returned. |
244 | The interval is always what you put in using setitimer(). |
245 | |
dcf686c9 |
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 |
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 |
281 | use Time::HiRes qw ( time alarm sleep ); |
282 | $now_fractions = time; |
283 | sleep (2.5); |
284 | alarm (10.6666666); |
285 | |
3c72ec00 |
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 | |
291 | $SIG{VTLARM} = sub { print time, "\n" }; |
292 | setitimer(ITIMER_VIRTUAL, 10, 2.5); |
293 | |
dcf686c9 |
294 | =head1 C API |
295 | |
296 | In addition to the perl API described above, a C API is available for |
297 | extension writers. The following C functions are available in the |
298 | modglobal hash: |
299 | |
300 | name C prototype |
301 | --------------- ---------------------- |
302 | Time::NVtime double (*)() |
303 | Time::U2time void (*)(UV ret[2]) |
304 | |
0be47ac6 |
305 | Both functions return equivalent information (like gettimeofday) |
306 | but with different representations. The names NVtime and U2time |
dcf686c9 |
307 | were selected mainly because they are operating system independent. |
0be47ac6 |
308 | (gettimeofday is Unix-centric, though some platforms like VMS have |
309 | emulations for it.) |
dcf686c9 |
310 | |
311 | Here 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 |
318 | printf("The current time is: %f\n", (*myNVtime)()); |
319 | |
f03b998d |
320 | =head1 CAVEATS |
321 | |
322 | Notice that the core time() maybe rounding rather than truncating. |
323 | What this means that the core time() may be giving time one second |
324 | later than gettimeofday(), also known as Time::HiRes::time(). |
325 | |
dcf686c9 |
326 | =head1 AUTHORS |
327 | |
328 | D. Wegscheid <wegscd@whirlpool.com> |
329 | R. Schertler <roderick@argon.org> |
330 | J. Hietaniemi <jhi@iki.fi> |
331 | G. Aas <gisle@aas.no> |
332 | |
3f2ee006 |
333 | =head1 COPYRIGHT AND LICENSE |
dcf686c9 |
334 | |
3f2ee006 |
335 | Copyright (c) 1996-2002 Douglas E. Wegscheid. All rights reserved. |
dcf686c9 |
336 | |
0be47ac6 |
337 | Copyright (c) 2002,2003 Jarkko Hietaniemi. All rights reserved. |
dcf686c9 |
338 | |
3f2ee006 |
339 | This program is free software; you can redistribute it and/or modify |
340 | it under the same terms as Perl itself. |
dcf686c9 |
341 | |
342 | =cut |