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