ext/Time/HiRes/HiRes.pm

   1 package Time::HiRes;
   2
   3 use strict;
   4 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK @EXPORT_FAIL);
   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
  14 $VERSION = do{my@r=q$Revision: 1.20 $=~/\d+/g;sprintf '%02d.'.'%02d'x$#r,@r};
  15
  16 bootstrap Time::HiRes $VERSION;
  17
  18 @EXPORT_FAIL = grep { ! defined &$_ } @EXPORT_OK;
  19
  20 # Preloaded methods go here.
  21
  22 sub tv_interval {
  23     # probably could have been done in C
  24     my ($a, $b) = @_;
  25     $b = [gettimeofday()] unless defined($b);
  26     (${$b}[0] - ${$a}[0]) + ((${$b}[1] - ${$a}[1]) / 1_000_000);
  27 }
  28
  29 # I'm only supplying this because the version of it in 5.003's Export.pm
  30 # is buggy (it doesn't shift off the class name).
  31
  32 sub export_fail {
  33     my $self = shift;
  34     @_;
  35 }
  36
  37 # Autoload methods go after =cut, and are processed by the autosplit program.
  38
  39 1;
  40 __END__
  41
  42 =head1 NAME
  43
  44 Time::HiRes - High resolution ualarm, usleep, and gettimeofday
  45
  46 =head1 SYNOPSIS
  47
  48   use Time::HiRes qw( usleep ualarm gettimeofday tv_interval );
  49
  50   usleep ($microseconds);
  51
  52   ualarm ($microseconds);
  53   ualarm ($microseconds, $interval_microseconds);
  54
  55   $t0 = [gettimeofday];
  56   ($seconds, $microseconds) = gettimeofday;
  57
  58   $elapsed = tv_interval ( $t0, [$seconds, $microseconds]);
  59   $elapsed = tv_interval ( $t0, [gettimeofday]);
  60   $elapsed = tv_interval ( $t0 );
  61
  62   use Time::HiRes qw ( time alarm sleep );
  63   $now_fractions = time;
  64   sleep ($floating_seconds);
  65   alarm ($floating_seconds);
  66   alarm ($floating_seconds, $floating_interval);
  67
  68 =head1 DESCRIPTION
  69
  70 The C<Time::HiRes> module implements a Perl interface to the usleep, ualarm,
  71 and gettimeofday system calls. See the EXAMPLES section below and the test
  72 scripts for usage; see your system documentation for the description of
  73 the underlying gettimeofday, usleep, and ualarm calls.
  74
  75 If your system lacks gettimeofday(2) you don't get gettimeofday() or the
  76 one-arg form of tv_interval().  If you don't have usleep(3) or select(2)
  77 you don't get usleep() or sleep().  If your system don't have ualarm(3)
  78 or setitimer(2) you don't
  79 get ualarm() or alarm().  If you try to import an unimplemented function
  80 in the C<use> statement it will fail at compile time.
  81
  82 The following functions can be imported from this module.  No
  83 functions are exported by default.
  84
  85 =over 4
  86
  87 =item gettimeofday ()
  88
  89 In array context it returns a 2 element array with the seconds and
  90 microseconds since the epoch.  In scalar context it returns floating
  91 seconds like Time::HiRes::time() (see below).
  92
  93 =item usleep ( $useconds )
  94
  95 Issues a usleep for the number of microseconds specified. See also
  96 Time::HiRes::sleep() below.
  97
  98 =item ualarm ( $useconds [, $interval_useconds ] )
  99
 100 Issues a ualarm call; interval_useconds is optional and will be 0 if
 101 unspecified, resulting in alarm-like behaviour.
 102
 103 =item tv_interval ( $ref_to_gettimeofday [, $ref_to_later_gettimeofday] )
 104
 105 Returns the floating seconds between the two times, which should have been
 106 returned by gettimeofday(). If the second argument is omitted, then the
 107 current time is used.
 108
 109 =item time ()
 110
 111 Returns a floating seconds since the epoch. This function can be imported,
 112 resulting in a nice drop-in replacement for the C<time> provided with perl,
 113 see the EXAMPLES below.
 114
 115 =item sleep ( $floating_seconds )
 116
 117 Converts $floating_seconds to microseconds and issues a usleep for the
 118 result.  This function can be imported, resulting in a nice drop-in
 119 replacement for the C<sleep> provided with perl, see the EXAMPLES below.
 120
 121 =item alarm ( $floating_seconds [, $interval_floating_seconds ] )
 122
 123 Converts $floating_seconds and $interval_floating_seconds and issues
 124 a ualarm for the results.  The $interval_floating_seconds argument
 125 is optional and will be 0 if unspecified, resulting in alarm-like
 126 behaviour.  This function can be imported, resulting in a nice drop-in
 127 replacement for the C<alarm> provided with perl, see the EXAMPLES below.
 128
 129 =back
 130
 131 =head1 EXAMPLES
 132
 133   use Time::HiRes qw(usleep ualarm gettimeofday tv_interval);
 134
 135   $microseconds = 750_000;
 136   usleep $microseconds;
 137
 138   # signal alarm in 2.5s & every .1s thereafter
 139   ualarm 2_500_000, 100_000;
 140
 141   # get seconds and microseconds since the epoch
 142   ($s, $usec) = gettimeofday;
 143
 144   # measure elapsed time
 145   # (could also do by subtracting 2 gettimeofday return values)
 146   $t0 = [gettimeofday];
 147   # do bunch of stuff here
 148   $t1 = [gettimeofday];
 149   # do more stuff here
 150   $t0_t1 = tv_interval $t0, $t1;
 151
 152   $elapsed = tv_interval ($t0, [gettimeofday]);
 153   $elapsed = tv_interval ($t0); # equivalent code
 154
 155   #
 156   # replacements for time, alarm and sleep that know about
 157   # floating seconds
 158   #
 159   use Time::HiRes;
 160   $now_fractions = Time::HiRes::time;
 161   Time::HiRes::sleep (2.5);
 162   Time::HiRes::alarm (10.6666666);
 163
 164   use Time::HiRes qw ( time alarm sleep );
 165   $now_fractions = time;
 166   sleep (2.5);
 167   alarm (10.6666666);
 168
 169 =head1 C API
 170
 171 In addition to the perl API described above, a C API is available for
 172 extension writers.  The following C functions are available in the
 173 modglobal hash:
 174
 175   name             C prototype
 176   ---------------  ----------------------
 177   Time::NVtime     double (*)()
 178   Time::U2time     void (*)(UV ret[2])
 179
 180 Both functions return equivalent information (like C<gettimeofday>)
 181 but with different representations.  The names C<NVtime> and C<U2time>
 182 were selected mainly because they are operating system independent.
 183 (C<gettimeofday> is Un*x-centric.)
 184
 185 Here is an example of using NVtime from C:
 186
 187   double (*myNVtime)();
 188   SV **svp = hv_fetch(PL_modglobal, "Time::NVtime", 12, 0);
 189   if (!svp)         croak("Time::HiRes is required");
 190   if (!SvIOK(*svp)) croak("Time::NVtime isn't a function pointer");
 191   myNVtime = (double(*)()) SvIV(*svp);
 192   printf("The current time is: %f\n", (*myNVtime)());
 193
 194 =head1 AUTHORS
 195
 196 D. Wegscheid <wegscd@whirlpool.com>
 197 R. Schertler <roderick@argon.org>
 198 J. Hietaniemi <jhi@iki.fi>
 199 G. Aas <gisle@aas.no>
 200
 201 =head1 REVISION
 202
 203 $Id: HiRes.pm,v 1.20 1999/03/16 02:26:13 wegscd Exp $
 204
 205 $Log: HiRes.pm,v $
 206 Revision 1.20  1999/03/16 02:26:13  wegscd
 207 Add documentation for NVTime and U2Time.
 208
 209 Revision 1.19  1998/09/30 02:34:42  wegscd
 210 No changes, bump version.
 211
 212 Revision 1.18  1998/07/07 02:41:35  wegscd
 213 No changes, bump version.
 214
 215 Revision 1.17  1998/07/02 01:45:13  wegscd
 216 Bump version to 1.17
 217
 218 Revision 1.16  1997/11/13 02:06:36  wegscd
 219 version bump to accomodate HiRes.xs fix.
 220
 221 Revision 1.15  1997/11/11 02:17:59  wegscd
 222 POD editing, courtesy of Gisle Aas.
 223
 224 Revision 1.14  1997/11/06 03:14:35  wegscd
 225 Update version # for Makefile.PL and HiRes.xs changes.
 226
 227 Revision 1.13  1997/11/05 05:36:25  wegscd
 228 change version # for Makefile.pl and HiRes.xs changes.
 229
 230 Revision 1.12  1997/10/13 20:55:33  wegscd
 231 Force a new version for Makefile.PL changes.
 232
 233 Revision 1.11  1997/09/05 19:59:33  wegscd
 234 New version to bump version for README and Makefile.PL fixes.
 235 Fix bad RCS log.
 236
 237 Revision 1.10  1997/05/23 01:11:38  wegscd
 238 Conditional compilation; EXPORT_FAIL fixes.
 239
 240 Revision 1.2  1996/12/30 13:28:40  wegscd
 241 Update documentation for what to do when missing ualarm() and friends.
 242
 243 Revision 1.1  1996/10/17 20:53:31  wegscd
 244 Fix =head1 being next to __END__ so pod2man works
 245
 246 Revision 1.0  1996/09/03 18:25:15  wegscd
 247 Initial revision
 248
 249 =head1 COPYRIGHT
 250
 251 Copyright (c) 1996-1997 Douglas E. Wegscheid.
 252 All rights reserved. This program is free software; you can
 253 redistribute it and/or modify it under the same terms as Perl itself.
 254
 255 =cut