ext/Time/HiRes/HiRes.pm

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