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