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