Profile of /usr/local/lib/perl5/5.10.1/darwin-2level/Time/HiRes.pm

← Index
NYTProf Performance Profile «block view•line view•sub view»
For 01.HTTP.t
Run on Tue May 4 15:25:55 2010
Reported on Tue May 4 15:26:08 2010

File | /usr/local/lib/perl5/5.10.1/darwin-2level/Time/HiRes.pm
Statements Executed | 32
Statement Execution Time | 481µs

Subroutines — ordered by exclusive time
Calls | P | F | Exclusive Time | Inclusive Time | Subroutine
--- | --- | --- | --- | --- | ---
1 | 1 | 2 | 66µs | 66µs | Time::HiRes::::bootstrapTime::HiRes::bootstrap (xsub)
1 | 1 | 1 | 23µs | 248µs | Time::HiRes::::importTime::HiRes::import
1 | 1 | 1 | 21µs | 33µs | Time::HiRes::::AUTOLOADTime::HiRes::AUTOLOAD
1 | 1 | 1 | 13µs | 16µs | Time::HiRes::::BEGIN@3Time::HiRes::BEGIN@3
1 | 1 | 2 | 8µs | 8µs | Time::HiRes::::constantTime::HiRes::constant (xsub)
1 | 1 | 1 | 7µs | 94µs | Time::HiRes::::BEGIN@4Time::HiRes::BEGIN@4
1 | 1 | 1 | 7µs | 18µs | Time::HiRes::::BEGIN@42Time::HiRes::BEGIN@42
1 | 1 | 2 | 4µs | 4µs | Time::HiRes::::CORE:substTime::HiRes::CORE:subst (opcode)
1 | 1 | 1 | 1µs | 1µs | Time::HiRes::::__ANON__[:43]Time::HiRes::__ANON__[:43]
0 | 0 | 0 | 0s | 0s | Time::HiRes::::tv_intervalTime::HiRes::tv_interval

Call graph for these subroutines as a Graphviz dot language file.

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