"Fossies" - the Fresh Open Source Software Archive

Member "install-tl-20200916/tlpkg/tlperl/lib/Time/HiRes.pm" (7 Mar 2020, 24733 Bytes) of package /windows/misc/install-tl.zip:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Perl source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file.

    1 package Time::HiRes;
    2 
    3 { use 5.006; }
    4 use strict;
    5 
    6 require Exporter;
    7 use XSLoader ();
    8 
    9 our @ISA = qw(Exporter);
   10 
   11 our @EXPORT = qw( );
   12 # More or less this same list is in Makefile.PL.  Should unify.
   13 our @EXPORT_OK = qw (usleep sleep ualarm alarm gettimeofday time tv_interval
   14          getitimer setitimer nanosleep clock_gettime clock_getres
   15          clock clock_nanosleep
   16          CLOCKS_PER_SEC
   17          CLOCK_BOOTTIME
   18          CLOCK_HIGHRES
   19          CLOCK_MONOTONIC
   20          CLOCK_MONOTONIC_COARSE
   21          CLOCK_MONOTONIC_FAST
   22          CLOCK_MONOTONIC_PRECISE
   23          CLOCK_MONOTONIC_RAW
   24          CLOCK_PROCESS_CPUTIME_ID
   25          CLOCK_PROF
   26          CLOCK_REALTIME
   27          CLOCK_REALTIME_COARSE
   28          CLOCK_REALTIME_FAST
   29          CLOCK_REALTIME_PRECISE
   30          CLOCK_REALTIME_RAW
   31          CLOCK_SECOND
   32          CLOCK_SOFTTIME
   33          CLOCK_THREAD_CPUTIME_ID
   34          CLOCK_TIMEOFDAY
   35          CLOCK_UPTIME
   36          CLOCK_UPTIME_COARSE
   37          CLOCK_UPTIME_FAST
   38          CLOCK_UPTIME_PRECISE
   39          CLOCK_UPTIME_RAW
   40          CLOCK_VIRTUAL
   41          ITIMER_PROF
   42          ITIMER_REAL
   43          ITIMER_REALPROF
   44          ITIMER_VIRTUAL
   45          TIMER_ABSTIME
   46          d_usleep d_ualarm d_gettimeofday d_getitimer d_setitimer
   47          d_nanosleep d_clock_gettime d_clock_getres
   48          d_clock d_clock_nanosleep d_hires_stat
   49          d_futimens d_utimensat d_hires_utime
   50          stat lstat utime
   51         );
   52 
   53 our $VERSION = '1.9760';
   54 our $XS_VERSION = $VERSION;
   55 $VERSION = eval $VERSION;
   56 
   57 our $AUTOLOAD;
   58 sub AUTOLOAD {
   59     my $constname;
   60     ($constname = $AUTOLOAD) =~ s/.*:://;
   61     # print "AUTOLOAD: constname = $constname ($AUTOLOAD)\n";
   62     die "&Time::HiRes::constant not defined" if $constname eq 'constant';
   63     my ($error, $val) = constant($constname);
   64     # print "AUTOLOAD: error = $error, val = $val\n";
   65     if ($error) {
   66         my (undef,$file,$line) = caller;
   67         die "$error at $file line $line.\n";
   68     }
   69     {
   70     no strict 'refs';
   71     *$AUTOLOAD = sub { $val };
   72     }
   73     goto &$AUTOLOAD;
   74 }
   75 
   76 sub import {
   77     my $this = shift;
   78     for my $i (@_) {
   79     if (($i eq 'clock_getres'    && !&d_clock_getres)    ||
   80         ($i eq 'clock_gettime'   && !&d_clock_gettime)   ||
   81         ($i eq 'clock_nanosleep' && !&d_clock_nanosleep) ||
   82         ($i eq 'clock'           && !&d_clock)           ||
   83         ($i eq 'nanosleep'       && !&d_nanosleep)       ||
   84         ($i eq 'usleep'          && !&d_usleep)          ||
   85         ($i eq 'utime'           && !&d_hires_utime)     ||
   86         ($i eq 'ualarm'          && !&d_ualarm)) {
   87         require Carp;
   88         Carp::croak("Time::HiRes::$i(): unimplemented in this platform");
   89     }
   90     }
   91     Time::HiRes->export_to_level(1, $this, @_);
   92 }
   93 
   94 XSLoader::load( 'Time::HiRes', $XS_VERSION );
   95 
   96 # Preloaded methods go here.
   97 
   98 sub tv_interval {
   99     # probably could have been done in C
  100     my ($a, $b) = @_;
  101     $b = [gettimeofday()] unless defined($b);
  102     (${$b}[0] - ${$a}[0]) + ((${$b}[1] - ${$a}[1]) / 1_000_000);
  103 }
  104 
  105 # Autoload methods go after =cut, and are processed by the autosplit program.
  106 
  107 1;
  108 __END__
  109 
  110 =head1 NAME
  111 
  112 Time::HiRes - High resolution alarm, sleep, gettimeofday, interval timers
  113 
  114 =head1 SYNOPSIS
  115 
  116   use Time::HiRes qw( usleep ualarm gettimeofday tv_interval nanosleep
  117               clock_gettime clock_getres clock_nanosleep clock
  118                       stat lstat utime);
  119 
  120   usleep ($microseconds);
  121   nanosleep ($nanoseconds);
  122 
  123   ualarm ($microseconds);
  124   ualarm ($microseconds, $interval_microseconds);
  125 
  126   $t0 = [gettimeofday];
  127   ($seconds, $microseconds) = gettimeofday;
  128 
  129   $elapsed = tv_interval ( $t0, [$seconds, $microseconds]);
  130   $elapsed = tv_interval ( $t0, [gettimeofday]);
  131   $elapsed = tv_interval ( $t0 );
  132 
  133   use Time::HiRes qw ( time alarm sleep );
  134 
  135   $now_fractions = time;
  136   sleep ($floating_seconds);
  137   alarm ($floating_seconds);
  138   alarm ($floating_seconds, $floating_interval);
  139 
  140   use Time::HiRes qw( setitimer getitimer );
  141 
  142   setitimer ($which, $floating_seconds, $floating_interval );
  143   getitimer ($which);
  144 
  145   use Time::HiRes qw( clock_gettime clock_getres clock_nanosleep
  146               ITIMER_REAL ITIMER_VIRTUAL ITIMER_PROF
  147                       ITIMER_REALPROF );
  148 
  149   $realtime   = clock_gettime(CLOCK_REALTIME);
  150   $resolution = clock_getres(CLOCK_REALTIME);
  151 
  152   clock_nanosleep(CLOCK_REALTIME, 1.5e9);
  153   clock_nanosleep(CLOCK_REALTIME, time()*1e9 + 10e9, TIMER_ABSTIME);
  154 
  155   my $ticktock = clock();
  156 
  157   use Time::HiRes qw( stat lstat );
  158 
  159   my @stat = stat("file");
  160   my @stat = stat(FH);
  161   my @stat = lstat("file");
  162 
  163   use Time::HiRes qw( utime );
  164   utime $floating_seconds, $floating_seconds, file...;
  165 
  166 =head1 DESCRIPTION
  167 
  168 The C<Time::HiRes> module implements a Perl interface to the
  169 C<usleep>, C<nanosleep>, C<ualarm>, C<gettimeofday>, and
  170 C<setitimer>/C<getitimer> system calls, in other words, high
  171 resolution time and timers. See the L</EXAMPLES> section below and the
  172 test scripts for usage; see your system documentation for the
  173 description of the underlying C<nanosleep> or C<usleep>, C<ualarm>,
  174 C<gettimeofday>, and C<setitimer>/C<getitimer> calls.
  175 
  176 If your system lacks C<gettimeofday()> or an emulation of it you don't
  177 get C<gettimeofday()> or the one-argument form of C<tv_interval()>.
  178 If your system lacks all of C<nanosleep()>, C<usleep()>,
  179 C<select()>, and C<poll>, you don't get C<Time::HiRes::usleep()>,
  180 C<Time::HiRes::nanosleep()>, or C<Time::HiRes::sleep()>.
  181 If your system lacks both C<ualarm()> and C<setitimer()> you don't get
  182 C<Time::HiRes::ualarm()> or C<Time::HiRes::alarm()>.
  183 
  184 If you try to import an unimplemented function in the C<use> statement
  185 it will fail at compile time.
  186 
  187 If your subsecond sleeping is implemented with C<nanosleep()> instead
  188 of C<usleep()>, you can mix subsecond sleeping with signals since
  189 C<nanosleep()> does not use signals.  This, however, is not portable,
  190 and you should first check for the truth value of
  191 C<&Time::HiRes::d_nanosleep> to see whether you have nanosleep, and
  192 then carefully read your C<nanosleep()> C API documentation for any
  193 peculiarities.
  194 
  195 If you are using C<nanosleep> for something else than mixing sleeping
  196 with signals, give some thought to whether Perl is the tool you should
  197 be using for work requiring nanosecond accuracies.
  198 
  199 Remember that unless you are working on a I<hard realtime> system,
  200 any clocks and timers will be imprecise, especially so if you are working
  201 in a pre-emptive multiuser system.  Understand the difference between
  202 I<wallclock time> and process time (in UNIX-like systems the sum of
  203 I<user> and I<system> times).  Any attempt to sleep for X seconds will
  204 most probably end up sleeping B<more> than that, but don't be surprised
  205 if you end up sleeping slightly B<less>.
  206 
  207 The following functions can be imported from this module.
  208 No functions are exported by default.
  209 
  210 =over 4
  211 
  212 =item gettimeofday ()
  213 
  214 In array context returns a two-element array with the seconds and
  215 microseconds since the epoch.  In scalar context returns floating
  216 seconds like C<Time::HiRes::time()> (see below).
  217 
  218 =item usleep ( $useconds )
  219 
  220 Sleeps for the number of microseconds (millionths of a second)
  221 specified.  Returns the number of microseconds actually slept.
  222 Can sleep for more than one second, unlike the C<usleep> system call.
  223 Can also sleep for zero seconds, which often works like a I<thread yield>.
  224 See also C<Time::HiRes::usleep()>, C<Time::HiRes::sleep()>, and
  225 C<Time::HiRes::clock_nanosleep()>.
  226 
  227 Do not expect usleep() to be exact down to one microsecond.
  228 
  229 =item nanosleep ( $nanoseconds )
  230 
  231 Sleeps for the number of nanoseconds (1e9ths of a second) specified.
  232 Returns the number of nanoseconds actually slept (accurate only to
  233 microseconds, the nearest thousand of them).  Can sleep for more than
  234 one second.  Can also sleep for zero seconds, which often works like
  235 a I<thread yield>.  See also C<Time::HiRes::sleep()>,
  236 C<Time::HiRes::usleep()>, and C<Time::HiRes::clock_nanosleep()>.
  237 
  238 Do not expect nanosleep() to be exact down to one nanosecond.
  239 Getting even accuracy of one thousand nanoseconds is good.
  240 
  241 =item ualarm ( $useconds [, $interval_useconds ] )
  242 
  243 Issues a C<ualarm> call; the C<$interval_useconds> is optional and
  244 will be zero if unspecified, resulting in C<alarm>-like behaviour.
  245 
  246 Returns the remaining time in the alarm in microseconds, or C<undef>
  247 if an error occurred.
  248 
  249 ualarm(0) will cancel an outstanding ualarm().
  250 
  251 Note that the interaction between alarms and sleeps is unspecified.
  252 
  253 =item tv_interval 
  254 
  255 tv_interval ( $ref_to_gettimeofday [, $ref_to_later_gettimeofday] )
  256 
  257 Returns the floating seconds between the two times, which should have
  258 been returned by C<gettimeofday()>. If the second argument is omitted,
  259 then the current time is used.
  260 
  261 =item time ()
  262 
  263 Returns a floating seconds since the epoch. This function can be
  264 imported, resulting in a nice drop-in replacement for the C<time>
  265 provided with core Perl; see the L</EXAMPLES> below.
  266 
  267 B<NOTE 1>: This higher resolution timer can return values either less
  268 or more than the core C<time()>, depending on whether your platform
  269 rounds the higher resolution timer values up, down, or to the nearest second
  270 to get the core C<time()>, but naturally the difference should be never
  271 more than half a second.  See also L</clock_getres>, if available
  272 in your system.
  273 
  274 B<NOTE 2>: Since Sunday, September 9th, 2001 at 01:46:40 AM GMT, when
  275 the C<time()> seconds since epoch rolled over to 1_000_000_000, the
  276 default floating point format of Perl and the seconds since epoch have
  277 conspired to produce an apparent bug: if you print the value of
  278 C<Time::HiRes::time()> you seem to be getting only five decimals, not
  279 six as promised (microseconds).  Not to worry, the microseconds are
  280 there (assuming your platform supports such granularity in the first
  281 place).  What is going on is that the default floating point format of
  282 Perl only outputs 15 digits.  In this case that means ten digits
  283 before the decimal separator and five after.  To see the microseconds
  284 you can use either C<printf>/C<sprintf> with C<"%.6f">, or the
  285 C<gettimeofday()> function in list context, which will give you the
  286 seconds and microseconds as two separate values.
  287 
  288 =item sleep ( $floating_seconds )
  289 
  290 Sleeps for the specified amount of seconds.  Returns the number of
  291 seconds actually slept (a floating point value).  This function can
  292 be imported, resulting in a nice drop-in replacement for the C<sleep>
  293 provided with perl, see the L</EXAMPLES> below.
  294 
  295 Note that the interaction between alarms and sleeps is unspecified.
  296 
  297 =item alarm ( $floating_seconds [, $interval_floating_seconds ] )
  298 
  299 The C<SIGALRM> signal is sent after the specified number of seconds.
  300 Implemented using C<setitimer()> if available, C<ualarm()> if not.
  301 The C<$interval_floating_seconds> argument is optional and will be
  302 zero if unspecified, resulting in C<alarm()>-like behaviour.  This
  303 function can be imported, resulting in a nice drop-in replacement for
  304 the C<alarm> provided with perl, see the L</EXAMPLES> below.
  305 
  306 Returns the remaining time in the alarm in seconds, or C<undef>
  307 if an error occurred.
  308 
  309 B<NOTE 1>: With some combinations of operating systems and Perl
  310 releases C<SIGALRM> restarts C<select()>, instead of interrupting it.
  311 This means that an C<alarm()> followed by a C<select()> may together
  312 take the sum of the times specified for the C<alarm()> and the
  313 C<select()>, not just the time of the C<alarm()>.
  314 
  315 Note that the interaction between alarms and sleeps is unspecified.
  316 
  317 =item setitimer ( $which, $floating_seconds [, $interval_floating_seconds ] )
  318 
  319 Start up an interval timer: after a certain time, a signal ($which) arrives,
  320 and more signals may keep arriving at certain intervals.  To disable
  321 an "itimer", use C<$floating_seconds> of zero.  If the
  322 C<$interval_floating_seconds> is set to zero (or unspecified), the
  323 timer is disabled B<after> the next delivered signal.
  324 
  325 Use of interval timers may interfere with C<alarm()>, C<sleep()>,
  326 and C<usleep()>.  In standard-speak the "interaction is unspecified",
  327 which means that I<anything> may happen: it may work, it may not.
  328 
  329 In scalar context, the remaining time in the timer is returned.
  330 
  331 In list context, both the remaining time and the interval are returned.
  332 
  333 There are usually three or four interval timers (signals) available: the
  334 C<$which> can be C<ITIMER_REAL>, C<ITIMER_VIRTUAL>, C<ITIMER_PROF>, or
  335 C<ITIMER_REALPROF>.  Note that which ones are available depends: true
  336 UNIX platforms usually have the first three, but only Solaris seems to
  337 have C<ITIMER_REALPROF> (which is used to profile multithreaded programs).
  338 Win32 unfortunately does not have interval timers.
  339 
  340 C<ITIMER_REAL> results in C<alarm()>-like behaviour.  Time is counted in
  341 I<real time>; that is, wallclock time.  C<SIGALRM> is delivered when
  342 the timer expires.
  343 
  344 C<ITIMER_VIRTUAL> counts time in (process) I<virtual time>; that is,
  345 only when the process is running.  In multiprocessor/user/CPU systems
  346 this may be more or less than real or wallclock time.  (This time is
  347 also known as the I<user time>.)  C<SIGVTALRM> is delivered when the
  348 timer expires.
  349 
  350 C<ITIMER_PROF> counts time when either the process virtual time or when
  351 the operating system is running on behalf of the process (such as I/O).
  352 (This time is also known as the I<system time>.)  (The sum of user
  353 time and system time is known as the I<CPU time>.)  C<SIGPROF> is
  354 delivered when the timer expires.  C<SIGPROF> can interrupt system calls.
  355 
  356 The semantics of interval timers for multithreaded programs are
  357 system-specific, and some systems may support additional interval
  358 timers.  For example, it is unspecified which thread gets the signals.
  359 See your C<setitimer()> documentation.
  360 
  361 =item getitimer ( $which )
  362 
  363 Return the remaining time in the interval timer specified by C<$which>.
  364 
  365 In scalar context, the remaining time is returned.
  366 
  367 In list context, both the remaining time and the interval are returned.
  368 The interval is always what you put in using C<setitimer()>.
  369 
  370 =item clock_gettime ( $which )
  371 
  372 Return as seconds the current value of the POSIX high resolution timer
  373 specified by C<$which>.  All implementations that support POSIX high
  374 resolution timers are supposed to support at least the C<$which> value
  375 of C<CLOCK_REALTIME>, which is supposed to return results close to the
  376 results of C<gettimeofday>, or the number of seconds since 00:00:00:00
  377 January 1, 1970 Greenwich Mean Time (GMT).  Do not assume that
  378 CLOCK_REALTIME is zero, it might be one, or something else.
  379 Another potentially useful (but not available everywhere) value is
  380 C<CLOCK_MONOTONIC>, which guarantees a monotonically increasing time
  381 value (unlike time() or gettimeofday(), which can be adjusted).
  382 See your system documentation for other possibly supported values.
  383 
  384 =item clock_getres ( $which )
  385 
  386 Return as seconds the resolution of the POSIX high resolution timer
  387 specified by C<$which>.  All implementations that support POSIX high
  388 resolution timers are supposed to support at least the C<$which> value
  389 of C<CLOCK_REALTIME>, see L</clock_gettime>.
  390 
  391 B<NOTE>: the resolution returned may be highly optimistic.  Even if
  392 the resolution is high (a small number), all it means is that you'll
  393 be able to specify the arguments to clock_gettime() and clock_nanosleep()
  394 with that resolution.  The system might not actually be able to measure
  395 events at that resolution, and the various overheads and the overall system
  396 load are certain to affect any timings.
  397 
  398 =item clock_nanosleep ( $which, $nanoseconds, $flags = 0)
  399 
  400 Sleeps for the number of nanoseconds (1e9ths of a second) specified.
  401 Returns the number of nanoseconds actually slept.  The $which is the
  402 "clock id", as with clock_gettime() and clock_getres().  The flags
  403 default to zero but C<TIMER_ABSTIME> can specified (must be exported
  404 explicitly) which means that C<$nanoseconds> is not a time interval
  405 (as is the default) but instead an absolute time.  Can sleep for more
  406 than one second.  Can also sleep for zero seconds, which often works
  407 like a I<thread yield>.  See also C<Time::HiRes::sleep()>,
  408 C<Time::HiRes::usleep()>, and C<Time::HiRes::nanosleep()>.
  409 
  410 Do not expect clock_nanosleep() to be exact down to one nanosecond.
  411 Getting even accuracy of one thousand nanoseconds is good.
  412 
  413 =item clock()
  414 
  415 Return as seconds the I<process time> (user + system time) spent by
  416 the process since the first call to clock() (the definition is B<not>
  417 "since the start of the process", though if you are lucky these times
  418 may be quite close to each other, depending on the system).  What this
  419 means is that you probably need to store the result of your first call
  420 to clock(), and subtract that value from the following results of clock().
  421 
  422 The time returned also includes the process times of the terminated
  423 child processes for which wait() has been executed.  This value is
  424 somewhat like the second value returned by the times() of core Perl,
  425 but not necessarily identical.  Note that due to backward
  426 compatibility limitations the returned value may wrap around at about
  427 2147 seconds or at about 36 minutes.
  428 
  429 =item stat
  430 
  431 =item stat FH
  432 
  433 =item stat EXPR
  434 
  435 =item lstat
  436 
  437 =item lstat FH
  438 
  439 =item lstat EXPR
  440 
  441 As L<perlfunc/stat> or L<perlfunc/lstat>
  442 but with the access/modify/change file timestamps
  443 in subsecond resolution, if the operating system and the filesystem
  444 both support such timestamps.  To override the standard stat():
  445 
  446     use Time::HiRes qw(stat);
  447 
  448 Test for the value of &Time::HiRes::d_hires_stat to find out whether
  449 the operating system supports subsecond file timestamps: a value
  450 larger than zero means yes. There are unfortunately no easy
  451 ways to find out whether the filesystem supports such timestamps.
  452 UNIX filesystems often do; NTFS does; FAT doesn't (FAT timestamp
  453 granularity is B<two> seconds).
  454 
  455 A zero return value of &Time::HiRes::d_hires_stat means that
  456 Time::HiRes::stat is a no-op passthrough for CORE::stat()
  457 (and likewise for lstat),
  458 and therefore the timestamps will stay integers.  The same
  459 thing will happen if the filesystem does not do subsecond timestamps,
  460 even if the &Time::HiRes::d_hires_stat is non-zero.
  461 
  462 In any case do not expect nanosecond resolution, or even a microsecond
  463 resolution.  Also note that the modify/access timestamps might have
  464 different resolutions, and that they need not be synchronized, e.g.
  465 if the operations are
  466 
  467     write
  468     stat # t1
  469     read
  470     stat # t2
  471 
  472 the access time stamp from t2 need not be greater-than the modify
  473 time stamp from t1: it may be equal or I<less>.
  474 
  475 =item utime LIST
  476 
  477 As L<perlfunc/utime>
  478 but with the ability to set the access/modify file timestamps
  479 in subsecond resolution, if the operating system and the filesystem,
  480 and the mount options of the filesystem, all support such timestamps.
  481 
  482 To override the standard utime():
  483 
  484     use Time::HiRes qw(utime);
  485 
  486 Test for the value of &Time::HiRes::d_hires_utime to find out whether
  487 the operating system supports setting subsecond file timestamps.
  488 
  489 As with CORE::utime(), passing undef as both the atime and mtime will
  490 call the syscall with a NULL argument.
  491 
  492 The actual achievable subsecond resolution depends on the combination
  493 of the operating system and the filesystem.
  494 
  495 Modifying the timestamps may not be possible at all: for example, the
  496 C<noatime> filesystem mount option may prohibit you from changing the
  497 access time timestamp.
  498 
  499 Returns the number of files successfully changed.
  500 
  501 =back
  502 
  503 =head1 EXAMPLES
  504 
  505   use Time::HiRes qw(usleep ualarm gettimeofday tv_interval);
  506 
  507   $microseconds = 750_000;
  508   usleep($microseconds);
  509 
  510   # signal alarm in 2.5s & every .1s thereafter
  511   ualarm(2_500_000, 100_000);
  512   # cancel that ualarm
  513   ualarm(0);
  514 
  515   # get seconds and microseconds since the epoch
  516   ($s, $usec) = gettimeofday();
  517 
  518   # measure elapsed time 
  519   # (could also do by subtracting 2 gettimeofday return values)
  520   $t0 = [gettimeofday];
  521   # do bunch of stuff here
  522   $t1 = [gettimeofday];
  523   # do more stuff here
  524   $t0_t1 = tv_interval $t0, $t1;
  525 
  526   $elapsed = tv_interval ($t0, [gettimeofday]);
  527   $elapsed = tv_interval ($t0); # equivalent code
  528 
  529   #
  530   # replacements for time, alarm and sleep that know about
  531   # floating seconds
  532   #
  533   use Time::HiRes;
  534   $now_fractions = Time::HiRes::time;
  535   Time::HiRes::sleep (2.5);
  536   Time::HiRes::alarm (10.6666666);
  537 
  538   use Time::HiRes qw ( time alarm sleep );
  539   $now_fractions = time;
  540   sleep (2.5);
  541   alarm (10.6666666);
  542 
  543   # Arm an interval timer to go off first at 10 seconds and
  544   # after that every 2.5 seconds, in process virtual time
  545 
  546   use Time::HiRes qw ( setitimer ITIMER_VIRTUAL time );
  547 
  548   $SIG{VTALRM} = sub { print time, "\n" };
  549   setitimer(ITIMER_VIRTUAL, 10, 2.5);
  550 
  551   use Time::HiRes qw( clock_gettime clock_getres CLOCK_REALTIME );
  552   # Read the POSIX high resolution timer.
  553   my $high = clock_gettime(CLOCK_REALTIME);
  554   # But how accurate we can be, really?
  555   my $reso = clock_getres(CLOCK_REALTIME);
  556 
  557   use Time::HiRes qw( clock_nanosleep TIMER_ABSTIME );
  558   clock_nanosleep(CLOCK_REALTIME, 1e6);
  559   clock_nanosleep(CLOCK_REALTIME, 2e9, TIMER_ABSTIME);
  560 
  561   use Time::HiRes qw( clock );
  562   my $clock0 = clock();
  563   ... # Do something.
  564   my $clock1 = clock();
  565   my $clockd = $clock1 - $clock0;
  566 
  567   use Time::HiRes qw( stat );
  568   my ($atime, $mtime, $ctime) = (stat("istics"))[8, 9, 10];
  569 
  570 =head1 C API
  571 
  572 In addition to the perl API described above, a C API is available for
  573 extension writers.  The following C functions are available in the
  574 modglobal hash:
  575 
  576   name             C prototype
  577   ---------------  ----------------------
  578   Time::NVtime     NV (*)()
  579   Time::U2time     void (*)(pTHX_ UV ret[2])
  580 
  581 Both functions return equivalent information (like C<gettimeofday>)
  582 but with different representations.  The names C<NVtime> and C<U2time>
  583 were selected mainly because they are operating system independent.
  584 (C<gettimeofday> is Unix-centric, though some platforms like Win32 and
  585 VMS have emulations for it.)
  586 
  587 Here is an example of using C<NVtime> from C:
  588 
  589   NV (*myNVtime)(); /* Returns -1 on failure. */
  590   SV **svp = hv_fetchs(PL_modglobal, "Time::NVtime", 0);
  591   if (!svp)         croak("Time::HiRes is required");
  592   if (!SvIOK(*svp)) croak("Time::NVtime isn't a function pointer");
  593   myNVtime = INT2PTR(NV(*)(), SvIV(*svp));
  594   printf("The current time is: %" NVff "\n", (*myNVtime)());
  595 
  596 =head1 DIAGNOSTICS
  597 
  598 =head2 useconds or interval more than ...
  599 
  600 In ualarm() you tried to use number of microseconds or interval (also
  601 in microseconds) more than 1_000_000 and setitimer() is not available
  602 in your system to emulate that case.
  603 
  604 =head2 negative time not invented yet
  605 
  606 You tried to use a negative time argument.
  607 
  608 =head2 internal error: useconds < 0 (unsigned ... signed ...)
  609 
  610 Something went horribly wrong-- the number of microseconds that cannot
  611 become negative just became negative.  Maybe your compiler is broken?
  612 
  613 =head2 useconds or uinterval equal to or more than 1000000
  614 
  615 In some platforms it is not possible to get an alarm with subsecond
  616 resolution and later than one second.
  617 
  618 =head2 unimplemented in this platform
  619 
  620 Some calls simply aren't available, real or emulated, on every platform.
  621 
  622 =head1 CAVEATS
  623 
  624 Notice that the core C<time()> maybe rounding rather than truncating.
  625 What this means is that the core C<time()> may be reporting the time
  626 as one second later than C<gettimeofday()> and C<Time::HiRes::time()>.
  627 
  628 Adjusting the system clock (either manually or by services like ntp)
  629 may cause problems, especially for long running programs that assume
  630 a monotonously increasing time (note that all platforms do not adjust
  631 time as gracefully as UNIX ntp does).  For example in Win32 (and derived
  632 platforms like Cygwin and MinGW) the Time::HiRes::time() may temporarily
  633 drift off from the system clock (and the original time())  by up to 0.5
  634 seconds. Time::HiRes will notice this eventually and recalibrate.
  635 Note that since Time::HiRes 1.77 the clock_gettime(CLOCK_MONOTONIC)
  636 might help in this (in case your system supports CLOCK_MONOTONIC).
  637 
  638 Some systems have APIs but not implementations: for example QNX and Haiku
  639 have the interval timer APIs but not the functionality.
  640 
  641 In pre-Sierra macOS (pre-10.12, OS X) clock_getres(), clock_gettime()
  642 and clock_nanosleep() are emulated using the Mach timers; as a side
  643 effect of being emulated the CLOCK_REALTIME and CLOCK_MONOTONIC are
  644 the same timer.
  645 
  646 gnukfreebsd seems to have non-functional futimens() and utimensat()
  647 (at least as of 10.1): therefore the hires utime() does not work.
  648 
  649 =head1 SEE ALSO
  650 
  651 Perl modules L<BSD::Resource>, L<Time::TAI64>.
  652 
  653 Your system documentation for C<clock>, C<clock_gettime>,
  654 C<clock_getres>, C<clock_nanosleep>, C<clock_settime>, C<getitimer>,
  655 C<gettimeofday>, C<setitimer>, C<sleep>, C<stat>, C<ualarm>.
  656 
  657 =head1 AUTHORS
  658 
  659 D. Wegscheid <wegscd@whirlpool.com>
  660 R. Schertler <roderick@argon.org>
  661 J. Hietaniemi <jhi@iki.fi>
  662 G. Aas <gisle@aas.no>
  663 
  664 =head1 COPYRIGHT AND LICENSE
  665 
  666 Copyright (c) 1996-2002 Douglas E. Wegscheid.  All rights reserved.
  667 
  668 Copyright (c) 2002, 2003, 2004, 2005, 2006, 2007, 2008 Jarkko Hietaniemi.
  669 All rights reserved.
  670 
  671 Copyright (C) 2011, 2012, 2013 Andrew Main (Zefram) <zefram@fysh.org>
  672 
  673 This program is free software; you can redistribute it and/or modify
  674 it under the same terms as Perl itself.
  675 
  676 =cut