Explain an apparent bug reported by

[p5sagit/p5-mst-13.2.git] / ext / Time / HiRes / HiRes.pm

diff --git a/ext/Time/HiRes/HiRes.pm b/ext/Time/HiRes/HiRes.pm
index 11848db..e52d7ee 100644 (file)
--- a/ext/Time/HiRes/HiRes.pm
+++ b/ext/Time/HiRes/HiRes.pm
@@ -12,7 +12,7 @@ use XSLoader;
 @EXPORT_OK = qw (usleep sleep ualarm alarm gettimeofday time tv_interval
                 getitimer setitimer ITIMER_REAL ITIMER_VIRTUAL ITIMER_PROF);
 
-$VERSION = '1.21';
+$VERSION = '1.20_00';
 
 sub AUTOLOAD {
     my $constname;
@@ -113,7 +113,9 @@ Time::HiRes::sleep() below.
 Issues a ualarm call; interval_useconds is optional and will be 0 if 
 unspecified, resulting in alarm-like behaviour.
 
-=item tv_interval ( $ref_to_gettimeofday [, $ref_to_later_gettimeofday] )
+=item tv_interval 
+
+S<tv_interval ( $ref_to_gettimeofday [, $ref_to_later_gettimeofday] )>
 
 Returns the floating seconds between the two times, which should have been 
 returned by gettimeofday(). If the second argument is omitted, then the
@@ -125,6 +127,19 @@ Returns a floating seconds since the epoch. This function can be imported,
 resulting in a nice drop-in replacement for the C<time> provided with perl,
 see the EXAMPLES below.
 
+B<NOTE>: Since Sunday, September 9th, 2001 at 01:46:40 AM GMT the
+default floating point format of Perl and the seconds since epoch
+have conspired to produce an apparent bug: if you print the value
+of Time::HiRes::time() you seem to be getting only five decimals,
+not six as promised (microseconds).  Not to worry, the microseconds
+are there (assuming your platform supports such granularity).
+What is going on is that the default floating point format of Perl
+only outputs 15 digits.  In this case that means ten digits before the
+decimal separator and five after.  To see the microseconds you can use
+either printf/sprintf with C<%.6f>, or the gettimeofday() function in
+list context, which will give you the seconds and microseconds as two
+separate values.
+
 =item sleep ( $floating_seconds )
 
 Converts $floating_seconds to microseconds and issues a usleep for the 
@@ -139,7 +154,9 @@ is optional and will be 0 if unspecified, resulting in alarm-like
 behaviour.  This function can be imported, resulting in a nice drop-in
 replacement for the C<alarm> provided with perl, see the EXAMPLES below.
 
-=item setitimer ( $which, $floating_seconds [, $interval_floating_seconds ] )
+=item setitimer 
+
+S<setitimer ( $which, $floating_seconds [, $interval_floating_seconds ] )>
 
 Start up an interval timer: after a certain time, a signal is arrives,
 and more may keep arriving at certain intervals.  To disable a timer,
@@ -258,6 +275,12 @@ Here is an example of using NVtime from C:
   myNVtime = (double(*)()) SvIV(*svp);
   printf("The current time is: %f\n", (*myNVtime)());
 
+=head1 CAVEATS
+
+Notice that the core time() maybe rounding rather than truncating.
+What this means that the core time() may be giving time one second
+later than gettimeofday(), also known as Time::HiRes::time().
+
 =head1 AUTHORS
 
 D. Wegscheid <wegscd@whirlpool.com>