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