ext/Time/HiRes/HiRes.pm

   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 require DynaLoader;
   8
   9 @ISA = qw(Exporter DynaLoader);
  10
  11 @EXPORT = qw( );
  12 @EXPORT_OK = qw (usleep sleep ualarm alarm gettimeofday time tv_interval
  13                  getitimer setitimer nanosleep clock_gettime clock_getres
  14                  CLOCK_HIGHRES CLOCK_MONOTONIC CLOCK_PROCESS_CPUTIME_ID
  15                  CLOCK_REALTIME CLOCK_THREAD_CPUTIME_ID CLOCK_TIMEOFDAY
  16                  ITIMER_REAL ITIMER_VIRTUAL ITIMER_PROF ITIMER_REALPROF
  17                  d_usleep d_ualarm d_gettimeofday d_getitimer d_setitimer
  18                  d_nanosleep d_clock_gettime d_clock_getres);
  19
  20 $VERSION = '1.81';
  21 $XS_VERSION = $VERSION;
  22 $VERSION = eval $VERSION;
  23
  24 sub AUTOLOAD {
  25     my $constname;
  26     ($constname = $AUTOLOAD) =~ s/.*:://;
  27     # print "AUTOLOAD: constname = $constname ($AUTOLOAD)\n";
  28     die "&Time::HiRes::constant not defined" if $constname eq 'constant';
  29     my ($error, $val) = constant($constname);
  30     # print "AUTOLOAD: error = $error, val = $val\n";
  31     if ($error) {
  32         my (undef,$file,$line) = caller;
  33         die "$error at $file line $line.\n";
  34     }
  35     {
  36         no strict 'refs';
  37         *$AUTOLOAD = sub { $val };
  38     }
  39     goto &$AUTOLOAD;
  40 }
  41
  42 sub import {
  43     my $this = shift;
  44     for my $i (@_) {
  45         if (($i eq 'clock_getres'  && !&d_clock_getres)  ||
  46             ($i eq 'clock_gettime' && !&d_clock_gettime) ||
  47             ($i eq 'nanosleep'     && !&d_nanosleep)     ||
  48             ($i eq 'usleep'        && !&d_usleep)        ||
  49             ($i eq 'ualarm'        && !&d_ualarm)) {
  50             require Carp;
  51             Carp::croak("Time::HiRes::$i(): unimplemented in this platform");
  52         }
  53     }
  54     Time::HiRes->export_to_level(1, $this, @_);
  55 }
  56
  57 bootstrap Time::HiRes;
  58
  59 # Preloaded methods go here.
  60
  61 sub tv_interval {
  62     # probably could have been done in C
  63     my ($a, $b) = @_;
  64     $b = [gettimeofday()] unless defined($b);
  65     (${$b}[0] - ${$a}[0]) + ((${$b}[1] - ${$a}[1]) / 1_000_000);
  66 }
  67
  68 # Autoload methods go after =cut, and are processed by the autosplit program.
  69
  70 1;
  71 __END__
  72
  73 =head1 NAME
  74
  75 Time::HiRes - High resolution alarm, sleep, gettimeofday, interval timers
  76
  77 =head1 SYNOPSIS
  78
  79   use Time::HiRes qw( usleep ualarm gettimeofday tv_interval nanosleep
  80                       clock_gettime clock_getres );
  81
  82   usleep ($microseconds);
  83   nanosleep ($nanoseconds);
  84
  85   ualarm ($microseconds);
  86   ualarm ($microseconds, $interval_microseconds);
  87
  88   $t0 = [gettimeofday];
  89   ($seconds, $microseconds) = gettimeofday;
  90
  91   $elapsed = tv_interval ( $t0, [$seconds, $microseconds]);
  92   $elapsed = tv_interval ( $t0, [gettimeofday]);
  93   $elapsed = tv_interval ( $t0 );
  94
  95   use Time::HiRes qw ( time alarm sleep );
  96
  97   $now_fractions = time;
  98   sleep ($floating_seconds);
  99   alarm ($floating_seconds);
 100   alarm ($floating_seconds, $floating_interval);
 101
 102   use Time::HiRes qw( setitimer getitimer
 103                       ITIMER_REAL ITIMER_VIRTUAL ITIMER_PROF ITIMER_REALPROF );
 104
 105   setitimer ($which, $floating_seconds, $floating_interval );
 106   getitimer ($which);
 107
 108   $realtime = clock_gettime(CLOCK_REALTIME);
 109
 110 =head1 DESCRIPTION
 111
 112 The C<Time::HiRes> module implements a Perl interface to the
 113 C<usleep>, C<nanosleep>, C<ualarm>, C<gettimeofday>, and
 114 C<setitimer>/C<getitimer> system calls, in other words, high
 115 resolution time and timers. See the L</EXAMPLES> section below and the
 116 test scripts for usage; see your system documentation for the
 117 description of the underlying C<nanosleep> or C<usleep>, C<ualarm>,
 118 C<gettimeofday>, and C<setitimer>/C<getitimer> calls.
 119
 120 If your system lacks C<gettimeofday()> or an emulation of it you don't
 121 get C<gettimeofday()> or the one-argument form of C<tv_interval()>.
 122 If your system lacks all of C<nanosleep()>, C<usleep()>, C<select()>,
 123 and C<poll()>, you don't get C<Time::HiRes::usleep()>,
 124 C<Time::HiRes::nanosleep()>, or C<Time::HiRes::sleep()>.  If your
 125 system lacks both C<ualarm()> and C<setitimer()> you don't get
 126 C<Time::HiRes::ualarm()> or C<Time::HiRes::alarm()>.
 127
 128 If you try to import an unimplemented function in the C<use> statement
 129 it will fail at compile time.
 130
 131 If your subsecond sleeping is implemented with C<nanosleep()> instead
 132 of C<usleep()>, you can mix subsecond sleeping with signals since
 133 C<nanosleep()> does not use signals.  This, however, is not portable,
 134 and you should first check for the truth value of
 135 C<&Time::HiRes::d_nanosleep> to see whether you have nanosleep, and
 136 then carefully read your C<nanosleep()> C API documentation for any
 137 peculiarities.
 138
 139 If you are using C<nanosleep> for something else than mixing sleeping
 140 with signals, give some thought to whether Perl is the tool you should
 141 be using for work requiring nanosecond accuracies.
 142
 143 The following functions can be imported from this module.
 144 No functions are exported by default.
 145
 146 =over 4
 147
 148 =item gettimeofday ()
 149
 150 In array context returns a two-element array with the seconds and
 151 microseconds since the epoch.  In scalar context returns floating
 152 seconds like C<Time::HiRes::time()> (see below).
 153
 154 =item usleep ( $useconds )
 155
 156 Sleeps for the number of microseconds (millionths of a second)
 157 specified.  Returns the number of microseconds actually slept.  Can
 158 sleep for more than one second, unlike the C<usleep> system call. See
 159 also C<Time::HiRes::usleep()> and C<Time::HiRes::sleep()>.
 160
 161 Do not expect usleep() to be exact down to one microsecond.
 162
 163 =item nanosleep ( $nanoseconds )
 164
 165 Sleeps for the number of nanoseconds (1e9ths of a second) specified.
 166 Returns the number of nanoseconds actually slept (accurate only to
 167 microseconds, the nearest thousand of them).  Can sleep for more than
 168 one second.  See also C<Time::HiRes::sleep()> and
 169 C<Time::HiRes::usleep()>.
 170
 171 Do not expect nanosleep() to be exact down to one nanosecond.
 172 Getting even accuracy of one thousand nanoseconds is good.
 173
 174 =item ualarm ( $useconds [, $interval_useconds ] )
 175
 176 Issues a C<ualarm> call; the C<$interval_useconds> is optional and
 177 will be zero if unspecified, resulting in C<alarm>-like behaviour.
 178
 179 Note that the interaction between alarms and sleeps is unspecified.
 180
 181 =item tv_interval
 182
 183 tv_interval ( $ref_to_gettimeofday [, $ref_to_later_gettimeofday] )
 184
 185 Returns the floating seconds between the two times, which should have
 186 been returned by C<gettimeofday()>. If the second argument is omitted,
 187 then the current time is used.
 188
 189 =item time ()
 190
 191 Returns a floating seconds since the epoch. This function can be
 192 imported, resulting in a nice drop-in replacement for the C<time>
 193 provided with core Perl; see the L</EXAMPLES> below.
 194
 195 B<NOTE 1>: This higher resolution timer can return values either less
 196 or more than the core C<time()>, depending on whether your platform
 197 rounds the higher resolution timer values up, down, or to the nearest second
 198 to get the core C<time()>, but naturally the difference should be never
 199 more than half a second.  See also L</clock_getres>, if available
 200 in your system.
 201
 202 B<NOTE 2>: Since Sunday, September 9th, 2001 at 01:46:40 AM GMT, when
 203 the C<time()> seconds since epoch rolled over to 1_000_000_000, the
 204 default floating point format of Perl and the seconds since epoch have
 205 conspired to produce an apparent bug: if you print the value of
 206 C<Time::HiRes::time()> you seem to be getting only five decimals, not
 207 six as promised (microseconds).  Not to worry, the microseconds are
 208 there (assuming your platform supports such granularity in the first
 209 place).  What is going on is that the default floating point format of
 210 Perl only outputs 15 digits.  In this case that means ten digits
 211 before the decimal separator and five after.  To see the microseconds
 212 you can use either C<printf>/C<sprintf> with C<"%.6f">, or the
 213 C<gettimeofday()> function in list context, which will give you the
 214 seconds and microseconds as two separate values.
 215
 216 =item sleep ( $floating_seconds )
 217
 218 Sleeps for the specified amount of seconds.  Returns the number of
 219 seconds actually slept (a floating point value).  This function can
 220 be imported, resulting in a nice drop-in replacement for the C<sleep>
 221 provided with perl, see the L</EXAMPLES> below.
 222
 223 Note that the interaction between alarms and sleeps is unspecified.
 224
 225 =item alarm ( $floating_seconds [, $interval_floating_seconds ] )
 226
 227 The C<SIGALRM> signal is sent after the specified number of seconds.
 228 Implemented using C<ualarm()>.  The C<$interval_floating_seconds> argument
 229 is optional and will be zero if unspecified, resulting in C<alarm()>-like
 230 behaviour.  This function can be imported, resulting in a nice drop-in
 231 replacement for the C<alarm> provided with perl, see the L</EXAMPLES> below.
 232
 233 B<NOTE 1>: With some combinations of operating systems and Perl
 234 releases C<SIGALRM> restarts C<select()>, instead of interrupting it.
 235 This means that an C<alarm()> followed by a C<select()> may together
 236 take the sum of the times specified for the the C<alarm()> and the
 237 C<select()>, not just the time of the C<alarm()>.
 238
 239 Note that the interaction between alarms and sleeps is unspecified.
 240
 241 =item setitimer ( $which, $floating_seconds [, $interval_floating_seconds ] )
 242
 243 Start up an interval timer: after a certain time, a signal arrives,
 244 and more signals may keep arriving at certain intervals.  To disable
 245 an "itimer", use C<$floating_seconds> of zero.  If the
 246 C<$interval_floating_seconds> is set to zero (or unspecified), the
 247 timer is disabled B<after> the next delivered signal.
 248
 249 Use of interval timers may interfere with C<alarm()>, C<sleep()>,
 250 and C<usleep()>.  In standard-speak the "interaction is unspecified",
 251 which means that I<anything> may happen: it may work, it may not.
 252
 253 In scalar context, the remaining time in the timer is returned.
 254
 255 In list context, both the remaining time and the interval are returned.
 256
 257 There are usually three or four interval timers available: the
 258 C<$which> can be C<ITIMER_REAL>, C<ITIMER_VIRTUAL>, C<ITIMER_PROF>, or
 259 C<ITIMER_REALPROF>.  Note that which ones are available depends: true
 260 UNIX platforms usually have the first three, but (for example) Win32
 261 and Cygwin have only C<ITIMER_REAL>, and only Solaris seems to have
 262 C<ITIMER_REALPROF> (which is used to profile multithreaded programs).
 263
 264 C<ITIMER_REAL> results in C<alarm()>-like behaviour.  Time is counted in
 265 I<real time>; that is, wallclock time.  C<SIGALRM> is delivered when
 266 the timer expires.
 267
 268 C<ITIMER_VIRTUAL> counts time in (process) I<virtual time>; that is,
 269 only when the process is running.  In multiprocessor/user/CPU systems
 270 this may be more or less than real or wallclock time.  (This time is
 271 also known as the I<user time>.)  C<SIGVTALRM> is delivered when the
 272 timer expires.
 273
 274 C<ITIMER_PROF> counts time when either the process virtual time or when
 275 the operating system is running on behalf of the process (such as I/O).
 276 (This time is also known as the I<system time>.)  (The sum of user
 277 time and system time is known as the I<CPU time>.)  C<SIGPROF> is
 278 delivered when the timer expires.  C<SIGPROF> can interrupt system calls.
 279
 280 The semantics of interval timers for multithreaded programs are
 281 system-specific, and some systems may support additional interval
 282 timers.  See your C<setitimer()> documentation.
 283
 284 =item getitimer ( $which )
 285
 286 Return the remaining time in the interval timer specified by C<$which>.
 287
 288 In scalar context, the remaining time is returned.
 289
 290 In list context, both the remaining time and the interval are returned.
 291 The interval is always what you put in using C<setitimer()>.
 292
 293 =item clock_gettime ( $which )
 294
 295 Return as seconds the current value of the POSIX high resolution timer
 296 specified by C<$which>.  All implementations that support POSIX high
 297 resolution timers are supposed to support at least the C<$which> value
 298 of C<CLOCK_REALTIME>, which is supposed to return results close to the
 299 results of C<gettimeofday>, or the number of seconds since 00:00:00:00
 300 January 1, 1970 Greenwich Mean Time (GMT).  Do not assume that
 301 CLOCK_REALTIME is zero, it might be one, or something else.
 302 Another potentially useful (but not available everywhere) value is
 303 C<CLOCK_MONOTONIC>, which guarantees a monotonically increasing time
 304 value (unlike time(), which can be adjusted).  See your system
 305 documentation for other possibly supported values.
 306
 307 =item clock_getres ( $which )
 308
 309 Return as seconds the resolution of the POSIX high resolution timer
 310 specified by C<$which>.  All implementations that support POSIX high
 311 resolution timers are supposed to support at least the C<$which> value
 312 of C<CLOCK_REALTIME>,  see L</clock_gettime>.
 313
 314 =back
 315
 316 =head1 EXAMPLES
 317
 318   use Time::HiRes qw(usleep ualarm gettimeofday tv_interval);
 319
 320   $microseconds = 750_000;
 321   usleep($microseconds);
 322
 323   # signal alarm in 2.5s & every .1s thereafter
 324   ualarm(2_500_000, 100_000);
 325
 326   # get seconds and microseconds since the epoch
 327   ($s, $usec) = gettimeofday();
 328
 329   # measure elapsed time
 330   # (could also do by subtracting 2 gettimeofday return values)
 331   $t0 = [gettimeofday];
 332   # do bunch of stuff here
 333   $t1 = [gettimeofday];
 334   # do more stuff here
 335   $t0_t1 = tv_interval $t0, $t1;
 336
 337   $elapsed = tv_interval ($t0, [gettimeofday]);
 338   $elapsed = tv_interval ($t0); # equivalent code
 339
 340   #
 341   # replacements for time, alarm and sleep that know about
 342   # floating seconds
 343   #
 344   use Time::HiRes;
 345   $now_fractions = Time::HiRes::time;
 346   Time::HiRes::sleep (2.5);
 347   Time::HiRes::alarm (10.6666666);
 348
 349   use Time::HiRes qw ( time alarm sleep );
 350   $now_fractions = time;
 351   sleep (2.5);
 352   alarm (10.6666666);
 353
 354   # Arm an interval timer to go off first at 10 seconds and
 355   # after that every 2.5 seconds, in process virtual time
 356
 357   use Time::HiRes qw ( setitimer ITIMER_VIRTUAL time );
 358
 359   $SIG{VTALRM} = sub { print time, "\n" };
 360   setitimer(ITIMER_VIRTUAL, 10, 2.5);
 361
 362   use Time::HiRes qw( clock_gettime clock_getres CLOCK_REALTIME );
 363   # Read the POSIX high resolution timer.
 364   my $high = clock_getres(CLOCK_REALTIME);
 365   # But how accurate we can be, really?
 366   my $reso = clock_getres(CLOCK_REALTIME);
 367
 368 =head1 C API
 369
 370 In addition to the perl API described above, a C API is available for
 371 extension writers.  The following C functions are available in the
 372 modglobal hash:
 373
 374   name             C prototype
 375   ---------------  ----------------------
 376   Time::NVtime     double (*)()
 377   Time::U2time     void (*)(pTHX_ UV ret[2])
 378
 379 Both functions return equivalent information (like C<gettimeofday>)
 380 but with different representations.  The names C<NVtime> and C<U2time>
 381 were selected mainly because they are operating system independent.
 382 (C<gettimeofday> is Unix-centric, though some platforms like Win32 and
 383 VMS have emulations for it.)
 384
 385 Here is an example of using C<NVtime> from C:
 386
 387   double (*myNVtime)(); /* Returns -1 on failure. */
 388   SV **svp = hv_fetch(PL_modglobal, "Time::NVtime", 12, 0);
 389   if (!svp)         croak("Time::HiRes is required");
 390   if (!SvIOK(*svp)) croak("Time::NVtime isn't a function pointer");
 391   myNVtime = INT2PTR(double(*)(), SvIV(*svp));
 392   printf("The current time is: %f\n", (*myNVtime)());
 393
 394 =head1 DIAGNOSTICS
 395
 396 =head2 negative time not invented yet
 397
 398 You tried to use a negative time argument.
 399
 400 =head2 internal error: useconds < 0 (unsigned ... signed ...)
 401
 402 Something went horribly wrong-- the number of microseconds that cannot
 403 become negative just became negative.  Maybe your compiler is broken?
 404
 405 =head1 CAVEATS
 406
 407 Notice that the core C<time()> maybe rounding rather than truncating.
 408 What this means is that the core C<time()> may be reporting the time
 409 as one second later than C<gettimeofday()> and C<Time::HiRes::time()>.
 410
 411 Adjusting the system clock (either manually or by services like ntp)
 412 may cause problems, especially for long running programs that assume
 413 a monotonously increasing time (note that all platforms do not adjust
 414 time as gracefully as UNIX ntp does).  For example in Win32 (and derived
 415 platforms like Cygwin and MinGW) the Time::HiRes::time() may temporarily
 416 drift off from the system clock (and the original time())  by up to 0.5
 417 seconds. Time::HiRes will notice this eventually and recalibrate.
 418 Note that since Time::HiRes 1.77 the clock_gettime(CLOCK_MONOTONIC)
 419 might help in this (in case your system supports CLOCK_MONOTONIC).
 420
 421 =head1 SEE ALSO
 422
 423 Perl modules L<BSD::Resource>, L<Time::TAI64>.
 424
 425 Your system documentation for C<clock_gettime>, C<clock_settime>,
 426 C<gettimeofday>, C<getitimer>, C<setitimer>, C<ualarm>.
 427
 428 =head1 AUTHORS
 429
 430 D. Wegscheid <wegscd@whirlpool.com>
 431 R. Schertler <roderick@argon.org>
 432 J. Hietaniemi <jhi@iki.fi>
 433 G. Aas <gisle@aas.no>
 434
 435 =head1 COPYRIGHT AND LICENSE
 436
 437 Copyright (c) 1996-2002 Douglas E. Wegscheid.  All rights reserved.
 438
 439 Copyright (c) 2002, 2003, 2004, 2005 Jarkko Hietaniemi.  All rights reserved.
 440
 441 This program is free software; you can redistribute it and/or modify
 442 it under the same terms as Perl itself.
 443
 444 =cut