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