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