[doc] Time::HiRes documentation missing import of CLOCK_REALTIME

[ulchie]

Where
Time::HiRes

Description

The Time::HiRes documentation shows invocations of clock_gettime(CLOCK_REALTIME), but in the example there is no import of CLOCK_REALTIME.

The code in question gives the impression that it is correct when executed on Linux as CLOCK_REALTIME seems to map to 0 anyways, but not on Windows:

Windows

$ perl -MTime::HiRes=clock_gettime,CLOCK_REALTIME -e 'print(CLOCK_REALTIME, "\n");'
1

Linux

$ perl -MTime::HiRes=clock_gettime,CLOCK_REALTIME -e 'print(CLOCK_REALTIME, "\n");'
0

I'm not a perl expert by any means but it looks like some kind of implicit conversion to 0 is happening when the import of CLOCK_REALTIME is missing. I know use strict; will find this but it's a subtle detail.

The lack of import threw me since I have very little familiarity with perl, so I had assumed these constants were just available globally because the documentation did not import them, so it looked like I had used it correctly when I tested on Linux but was giving me all -1 values on Windows.

Not using strict but only executing this kind of code could cause subtle issues for anyone that wants CLOCK_MONOTONIC semantics. We do use strict, but I was writing up a quick test-case to ensure I was using the API properly since I was resolving a timing drift problem that only happens on Windows for us when using Time::HiRes::time() and it threw me for a loop.

Just in case version matters at all here:

# Version on Windows
$ perl --version

This is perl 5, version 32, subversion 1 (v5.32.1) built for i686-cygwin-threads-64int-multi
(with 6 registered patches, see perl -V for more detail)

# Version on Linux
❯ perl --version

This is perl 5, version 34, subversion 0 (v5.34.0) built for x86_64-linux-gnu-thread-multi
(with 57 registered patches, see perl -V for more detail)

[jkeenan]

Where Time::HiRes

Description

The Time::HiRes documentation shows invocations of clock_gettime(CLOCK_REALTIME), but in the example there is no import of CLOCK_REALTIME.

Can you clarify why the following code samples from the documentation in HiRes.pm don't satisfy your concern?

555   use Time::HiRes qw( clock_gettime clock_getres CLOCK_REALTIME );
556   # Read the POSIX high resolution timer.
557   my $high = clock_gettime(CLOCK_REALTIME);
558   # But how accurate we can be, really?
559   my $reso = clock_getres(CLOCK_REALTIME);
560 

To me, that's an example of importing CLOCK_REALTIME.

[ulchie]

The code example in the synopsis at the top of the page is what is missing the import.

See:

use Time::HiRes qw( usleep ualarm gettimeofday tv_interval nanosleep
                    clock_gettime clock_getres clock_nanosleep clock
                    stat lstat utime);

usleep ($microseconds);
nanosleep ($nanoseconds);

ualarm ($microseconds);
ualarm ($microseconds, $interval_microseconds);

$t0 = [gettimeofday];
($seconds, $microseconds) = gettimeofday;

$elapsed = tv_interval ( $t0, [$seconds, $microseconds]);
$elapsed = tv_interval ( $t0, [gettimeofday]);
$elapsed = tv_interval ( $t0 );

use Time::HiRes qw ( time alarm sleep );

$now_fractions = time;
sleep ($floating_seconds);
alarm ($floating_seconds);
alarm ($floating_seconds, $floating_interval);

use Time::HiRes qw( setitimer getitimer );

setitimer ($which, $floating_seconds, $floating_interval );
getitimer ($which);

use Time::HiRes qw( clock_gettime clock_getres clock_nanosleep
                    ITIMER_REAL ITIMER_VIRTUAL ITIMER_PROF
                    ITIMER_REALPROF );

$realtime   = clock_gettime(CLOCK_REALTIME);
$resolution = clock_getres(CLOCK_REALTIME);

clock_nanosleep(CLOCK_REALTIME, 1.5e9);
clock_nanosleep(CLOCK_REALTIME, time()*1e9 + 10e9, TIMER_ABSTIME);

my $ticktock = clock();

use Time::HiRes qw( stat lstat );

my @stat = stat("file");
my @stat = stat(FH);
my @stat = lstat("file");

use Time::HiRes qw( utime );
utime $floating_seconds, $floating_seconds, file...;

[jkeenan]

Okay, but in #22061 I'm suggesting that we put the import of CLOCK_REALTIME closer to the place in the synopsis where it's currently being used.

[ulchie]

Ya, when I said top of the page I was just referring to where the entire code block is. The placement of the added import looks good. Thank you!