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