| 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 |