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 use XSLoader;
   8
   9 @ISA = qw(Exporter);
  10
  11 @EXPORT = qw( );
  12 @EXPORT_OK = qw (usleep sleep ualarm alarm gettimeofday time tv_interval
  13                  getitimer setitimer ITIMER_REAL ITIMER_VIRTUAL ITIMER_PROF);
  14
  15 $VERSION = '1.20_00';
  16 $XS_VERSION = $VERSION;
  17 $VERSION = eval $VERSION;
  18
  19 sub AUTOLOAD {
  20     my $constname;
  21     ($constname= $AUTOLOAD) =~ s/.*:://;
  22     my $val = constant($constname, @_ ? $_[0] : 0);
  23     if ($!) {
  24         my ($pack,$file,$line) = caller;
  25         die "Your vendor has not defined Time::HiRes macro $constname, used at $file line $line.\n";
  26     }
  27     {
  28         no strict 'refs';
  29         *$AUTOLOAD = sub { $val };
  30     }
  31     goto &$AUTOLOAD;
  32 }
  33
  34 XSLoader::load 'Time::HiRes', $XS_VERSION;
  35
  36 # Preloaded methods go here.
  37
  38 sub tv_interval {
  39     # probably could have been done in C
  40     my ($a, $b) = @_;
  41     $b = [gettimeofday()] unless defined($b);
  42     (${$b}[0] - ${$a}[0]) + ((${$b}[1] - ${$a}[1]) / 1_000_000);
  43 }
  44
  45 # Autoload methods go after =cut, and are processed by the autosplit program.
  46
  47 1;
  48 __END__
  49
  50 =head1 NAME
  51
  52 Time::HiRes - High resolution alarm, sleep, gettimeofday, interval timers
  53
  54 =head1 SYNOPSIS
  55
  56   use Time::HiRes qw( usleep ualarm gettimeofday tv_interval );
  57
  58   usleep ($microseconds);
  59
  60   ualarm ($microseconds);
  61   ualarm ($microseconds, $interval_microseconds);
  62
  63   $t0 = [gettimeofday];
  64   ($seconds, $microseconds) = gettimeofday;
  65
  66   $elapsed = tv_interval ( $t0, [$seconds, $microseconds]);
  67   $elapsed = tv_interval ( $t0, [gettimeofday]);
  68   $elapsed = tv_interval ( $t0 );
  69
  70   use Time::HiRes qw ( time alarm sleep );
  71
  72   $now_fractions = time;
  73   sleep ($floating_seconds);
  74   alarm ($floating_seconds);
  75   alarm ($floating_seconds, $floating_interval);
  76
  77   use Time::HiRes qw( setitimer getitimer
  78                       ITIMER_REAL ITIMER_VIRTUAL ITIMER_PROF );
  79
  80   setitimer ($which, $floating_seconds, $floating_interval );
  81   getitimer ($which);
  82
  83 =head1 DESCRIPTION
  84
  85 The C<Time::HiRes> module implements a Perl interface to the usleep,
  86 ualarm, gettimeofday, and setitimer/getitimer system calls. See the
  87 EXAMPLES section below and the test scripts for usage; see your system
  88 documentation for the description of the underlying usleep, ualarm,
  89 gettimeofday, and setitimer/getitimer calls.
  90
  91 If your system lacks gettimeofday(2) or an emulation of it you don't
  92 get gettimeofday() or the one-arg form of tv_interval().
  93 If you don't have usleep(3) or select(2) you don't get usleep()
  94 or sleep().  If your system don't have ualarm(3) or setitimer(2) you
  95 don't get ualarm() or alarm().  If you try to import an unimplemented
  96 function in the C<use> statement it will fail at compile time.
  97
  98 The following functions can be imported from this module.
  99 No functions are exported by default.
 100
 101 =over 4
 102
 103 =item gettimeofday ()
 104
 105 In array context returns a 2 element array with the seconds and
 106 microseconds since the epoch.  In scalar context returns floating
 107 seconds like Time::HiRes::time() (see below).
 108
 109 =item usleep ( $useconds )
 110
 111 Sleeps for the number of microseconds specified.  Returns the number
 112 of microseconds actually slept.  Can sleep for more than one second
 113 unlike the usleep system call. See also Time::HiRes::sleep() below.
 114
 115 =item ualarm ( $useconds [, $interval_useconds ] )
 116
 117 Issues a ualarm call; interval_useconds is optional and will be 0 if
 118 unspecified, resulting in alarm-like behaviour.
 119
 120 =item tv_interval
 121
 122 C<tv_interval ( $ref_to_gettimeofday [, $ref_to_later_gettimeofday] )>
 123
 124 Returns the floating seconds between the two times, which should have
 125 been returned by gettimeofday(). If the second argument is omitted,
 126 then the current time is used.
 127
 128 =item time ()
 129
 130 Returns a floating seconds since the epoch. This function can be
 131 imported, resulting in a nice drop-in replacement for the C<time>
 132 provided with core Perl, see the EXAMPLES below.
 133
 134 B<NOTE 1>: this higher resolution timer can return values either less or
 135 more than the core time(), depending on whether your platforms rounds
 136 the higher resolution timer values up, down, or to the nearest to get
 137 the core time(), but naturally the difference should be never more than
 138 half a second.
 139
 140 B<NOTE 2>: Since Sunday, September 9th, 2001 at 01:46:40 AM GMT
 141 (when the time() seconds since epoch rolled over to 1_000_000_000),
 142 the default floating point format of Perl and the seconds since epoch
 143 have conspired to produce an apparent bug: if you print the value of
 144 Time::HiRes::time() you seem to be getting only five decimals, not six
 145 as promised (microseconds).  Not to worry, the microseconds are there
 146 (assuming your platform supports such granularity).  What is going on
 147 is that the default floating point format of Perl only outputs 15
 148 digits.  In this case that means ten digits before the decimal
 149 separator and five after.  To see the microseconds you can use either
 150 printf/sprintf with C<%.6f>, or the gettimeofday() function in list
 151 context, which will give you the seconds and microseconds as two
 152 separate values.
 153
 154 =item sleep ( $floating_seconds )
 155
 156 Sleeps for the specified amount of seconds.  Returns the number of
 157 seconds actually slept (a floating point value).  This function can be
 158 imported, resulting in a nice drop-in replacement for the C<sleep>
 159 provided with perl, see the EXAMPLES below.
 160
 161 =item alarm ( $floating_seconds [, $interval_floating_seconds ] )
 162
 163 The SIGALRM signal is sent after the specfified number of seconds.
 164 Implemented using ualarm().  The $interval_floating_seconds argument
 165 is optional and will be 0 if unspecified, resulting in alarm()-like
 166 behaviour.  This function can be imported, resulting in a nice drop-in
 167 replacement for the C<alarm> provided with perl, see the EXAMPLES below.
 168
 169 =item setitimer
 170
 171 C<setitimer ( $which, $floating_seconds [, $interval_floating_seconds ] )>
 172
 173 Start up an interval timer: after a certain time, a signal arrives,
 174 and more signals may keep arriving at certain intervals.  To disable
 175 a timer, use time of zero.  If interval is set to zero (or unspecified),
 176 the timer is disabled B<after> the next delivered signal.
 177
 178 Use of interval timers may interfere with alarm(), sleep(), and usleep().
 179 In standard-speak the "interaction is unspecified", which means that
 180 I<anything> may happen: it may work, it may not.
 181
 182 In scalar context, the remaining time in the timer is returned.
 183
 184 In list context, both the remaining time and the interval are returned.
 185
 186 There are three interval timers: the $which can be ITIMER_REAL,
 187 ITIMER_VIRTUAL, or ITIMER_PROF.
 188
 189 ITIMER_REAL results in alarm()-like behavior.  Time is counted in
 190 I<real time>, that is, wallclock time.  SIGALRM is delivered when
 191 the timer expires.
 192
 193 ITIMER_VIRTUAL counts time in (process) I<virtual time>, that is, only
 194 when the process is running.  In multiprocessor/user/CPU systems this
 195 may be more or less than real or wallclock time.  (This time is also
 196 known as the I<user time>.)  SIGVTALRM is delivered when the timer expires.
 197
 198 ITIMER_PROF counts time when either the process virtual time or when
 199 the operating system is running on behalf of the process (such as
 200 I/O).  (This time is also known as the I<system time>.)  (Collectively
 201 these times are also known as the I<CPU time>.)  SIGPROF is delivered
 202 when the timer expires.  SIGPROF can interrupt system calls.
 203
 204 The semantics of interval timers for multithreaded programs are
 205 system-specific, and some systems may support additional interval
 206 timers.  See your setitimer() documentation.
 207
 208 =item getitimer ( $which )
 209
 210 Return the remaining time in the interval timer specified by $which.
 211
 212 In scalar context, the remaining time is returned.
 213
 214 In list context, both the remaining time and the interval are returned.
 215 The interval is always what you put in using setitimer().
 216
 217 =back
 218
 219 =head1 EXAMPLES
 220
 221   use Time::HiRes qw(usleep ualarm gettimeofday tv_interval);
 222
 223   $microseconds = 750_000;
 224   usleep $microseconds;
 225
 226   # signal alarm in 2.5s & every .1s thereafter
 227   ualarm 2_500_000, 100_000;
 228
 229   # get seconds and microseconds since the epoch
 230   ($s, $usec) = gettimeofday;
 231
 232   # measure elapsed time
 233   # (could also do by subtracting 2 gettimeofday return values)
 234   $t0 = [gettimeofday];
 235   # do bunch of stuff here
 236   $t1 = [gettimeofday];
 237   # do more stuff here
 238   $t0_t1 = tv_interval $t0, $t1;
 239
 240   $elapsed = tv_interval ($t0, [gettimeofday]);
 241   $elapsed = tv_interval ($t0); # equivalent code
 242
 243   #
 244   # replacements for time, alarm and sleep that know about
 245   # floating seconds
 246   #
 247   use Time::HiRes;
 248   $now_fractions = Time::HiRes::time;
 249   Time::HiRes::sleep (2.5);
 250   Time::HiRes::alarm (10.6666666);
 251
 252   use Time::HiRes qw ( time alarm sleep );
 253   $now_fractions = time;
 254   sleep (2.5);
 255   alarm (10.6666666);
 256
 257   # Arm an interval timer to go off first at 10 seconds and
 258   # after that every 2.5 seconds, in process virtual time
 259
 260   use Time::HiRes qw ( setitimer ITIMER_VIRTUAL time );
 261
 262   $SIG{VTLARM} = sub { print time, "\n" };
 263   setitimer(ITIMER_VIRTUAL, 10, 2.5);
 264
 265 =head1 C API
 266
 267 In addition to the perl API described above, a C API is available for
 268 extension writers.  The following C functions are available in the
 269 modglobal hash:
 270
 271   name             C prototype
 272   ---------------  ----------------------
 273   Time::NVtime     double (*)()
 274   Time::U2time     void (*)(UV ret[2])
 275
 276 Both functions return equivalent information (like C<gettimeofday>)
 277 but with different representations.  The names C<NVtime> and C<U2time>
 278 were selected mainly because they are operating system independent.
 279 (C<gettimeofday> is Un*x-centric.)
 280
 281 Here is an example of using NVtime from C:
 282
 283   double (*myNVtime)();
 284   SV **svp = hv_fetch(PL_modglobal, "Time::NVtime", 12, 0);
 285   if (!svp)         croak("Time::HiRes is required");
 286   if (!SvIOK(*svp)) croak("Time::NVtime isn't a function pointer");
 287   myNVtime = INT2PTR(double(*)(), SvIV(*svp));
 288   printf("The current time is: %f\n", (*myNVtime)());
 289
 290 =head1 CAVEATS
 291
 292 Notice that the core time() maybe rounding rather than truncating.
 293 What this means that the core time() may be giving time one second
 294 later than gettimeofday(), also known as Time::HiRes::time().
 295
 296 =head1 AUTHORS
 297
 298 D. Wegscheid <wegscd@whirlpool.com>
 299 R. Schertler <roderick@argon.org>
 300 J. Hietaniemi <jhi@iki.fi>
 301 G. Aas <gisle@aas.no>
 302
 303 =head1 REVISION
 304
 305 $Id: HiRes.pm,v 1.20 1999/03/16 02:26:13 wegscd Exp $
 306
 307 $Log: HiRes.pm,v $
 308 Revision 1.20  1999/03/16 02:26:13  wegscd
 309 Add documentation for NVTime and U2Time.
 310
 311 Revision 1.19  1998/09/30 02:34:42  wegscd
 312 No changes, bump version.
 313
 314 Revision 1.18  1998/07/07 02:41:35  wegscd
 315 No changes, bump version.
 316
 317 Revision 1.17  1998/07/02 01:45:13  wegscd
 318 Bump version to 1.17
 319
 320 Revision 1.16  1997/11/13 02:06:36  wegscd
 321 version bump to accomodate HiRes.xs fix.
 322
 323 Revision 1.15  1997/11/11 02:17:59  wegscd
 324 POD editing, courtesy of Gisle Aas.
 325
 326 Revision 1.14  1997/11/06 03:14:35  wegscd
 327 Update version # for Makefile.PL and HiRes.xs changes.
 328
 329 Revision 1.13  1997/11/05 05:36:25  wegscd
 330 change version # for Makefile.pl and HiRes.xs changes.
 331
 332 Revision 1.12  1997/10/13 20:55:33  wegscd
 333 Force a new version for Makefile.PL changes.
 334
 335 Revision 1.11  1997/09/05 19:59:33  wegscd
 336 New version to bump version for README and Makefile.PL fixes.
 337 Fix bad RCS log.
 338
 339 Revision 1.10  1997/05/23 01:11:38  wegscd
 340 Conditional compilation; EXPORT_FAIL fixes.
 341
 342 Revision 1.2  1996/12/30 13:28:40  wegscd
 343 Update documentation for what to do when missing ualarm() and friends.
 344
 345 Revision 1.1  1996/10/17 20:53:31  wegscd
 346 Fix =head1 being next to __END__ so pod2man works
 347
 348 Revision 1.0  1996/09/03 18:25:15  wegscd
 349 Initial revision
 350
 351 =head1 COPYRIGHT
 352
 353 Copyright (c) 1996-1997 Douglas E. Wegscheid.
 354 All rights reserved. This program is free software; you can
 355 redistribute it and/or modify it under the same terms as Perl itself.
 356
 357 =cut