Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "Time::HiRes 3" | |
132 | .TH Time::HiRes 3 "2001-09-21" "perl v5.8.8" "Perl Programmers Reference Guide" | |
133 | .SH "NAME" | |
134 | Time::HiRes \- High resolution alarm, sleep, gettimeofday, interval timers | |
135 | .SH "SYNOPSIS" | |
136 | .IX Header "SYNOPSIS" | |
137 | .Vb 2 | |
138 | \& use Time::HiRes qw( usleep ualarm gettimeofday tv_interval nanosleep | |
139 | \& clock_gettime clock_getres clock_nanosleep clock ); | |
140 | .Ve | |
141 | .PP | |
142 | .Vb 2 | |
143 | \& usleep ($microseconds); | |
144 | \& nanosleep ($nanoseconds); | |
145 | .Ve | |
146 | .PP | |
147 | .Vb 2 | |
148 | \& ualarm ($microseconds); | |
149 | \& ualarm ($microseconds, $interval_microseconds); | |
150 | .Ve | |
151 | .PP | |
152 | .Vb 2 | |
153 | \& $t0 = [gettimeofday]; | |
154 | \& ($seconds, $microseconds) = gettimeofday; | |
155 | .Ve | |
156 | .PP | |
157 | .Vb 3 | |
158 | \& $elapsed = tv_interval ( $t0, [$seconds, $microseconds]); | |
159 | \& $elapsed = tv_interval ( $t0, [gettimeofday]); | |
160 | \& $elapsed = tv_interval ( $t0 ); | |
161 | .Ve | |
162 | .PP | |
163 | .Vb 1 | |
164 | \& use Time::HiRes qw ( time alarm sleep ); | |
165 | .Ve | |
166 | .PP | |
167 | .Vb 4 | |
168 | \& $now_fractions = time; | |
169 | \& sleep ($floating_seconds); | |
170 | \& alarm ($floating_seconds); | |
171 | \& alarm ($floating_seconds, $floating_interval); | |
172 | .Ve | |
173 | .PP | |
174 | .Vb 2 | |
175 | \& use Time::HiRes qw( setitimer getitimer | |
176 | \& ITIMER_REAL ITIMER_VIRTUAL ITIMER_PROF ITIMER_REALPROF ); | |
177 | .Ve | |
178 | .PP | |
179 | .Vb 2 | |
180 | \& setitimer ($which, $floating_seconds, $floating_interval ); | |
181 | \& getitimer ($which); | |
182 | .Ve | |
183 | .PP | |
184 | .Vb 2 | |
185 | \& $realtime = clock_gettime(CLOCK_REALTIME); | |
186 | \& $resolution = clock_getres(CLOCK_REALTIME); | |
187 | .Ve | |
188 | .PP | |
189 | .Vb 2 | |
190 | \& clock_nanosleep(CLOCK_REALTIME, 1.5); | |
191 | \& clock_nanosleep(CLOCK_REALTIME, time() + 10, TIMER_ABSTIME); | |
192 | .Ve | |
193 | .PP | |
194 | .Vb 1 | |
195 | \& my $ticktock = clock(); | |
196 | .Ve | |
197 | .SH "DESCRIPTION" | |
198 | .IX Header "DESCRIPTION" | |
199 | The \f(CW\*(C`Time::HiRes\*(C'\fR module implements a Perl interface to the | |
200 | \&\f(CW\*(C`usleep\*(C'\fR, \f(CW\*(C`nanosleep\*(C'\fR, \f(CW\*(C`ualarm\*(C'\fR, \f(CW\*(C`gettimeofday\*(C'\fR, and | |
201 | \&\f(CW\*(C`setitimer\*(C'\fR/\f(CW\*(C`getitimer\*(C'\fR system calls, in other words, high | |
202 | resolution time and timers. See the \*(L"\s-1EXAMPLES\s0\*(R" section below and the | |
203 | test scripts for usage; see your system documentation for the | |
204 | description of the underlying \f(CW\*(C`nanosleep\*(C'\fR or \f(CW\*(C`usleep\*(C'\fR, \f(CW\*(C`ualarm\*(C'\fR, | |
205 | \&\f(CW\*(C`gettimeofday\*(C'\fR, and \f(CW\*(C`setitimer\*(C'\fR/\f(CW\*(C`getitimer\*(C'\fR calls. | |
206 | .PP | |
207 | If your system lacks \f(CW\*(C`gettimeofday()\*(C'\fR or an emulation of it you don't | |
208 | get \f(CW\*(C`gettimeofday()\*(C'\fR or the one-argument form of \f(CW\*(C`tv_interval()\*(C'\fR. | |
209 | If your system lacks all of \f(CW\*(C`nanosleep()\*(C'\fR, \f(CW\*(C`usleep()\*(C'\fR, | |
210 | \&\f(CW\*(C`select()\*(C'\fR, and \f(CW\*(C`poll\*(C'\fR, you don't get \f(CW\*(C`Time::HiRes::usleep()\*(C'\fR, | |
211 | \&\f(CW\*(C`Time::HiRes::nanosleep()\*(C'\fR, or \f(CW\*(C`Time::HiRes::sleep()\*(C'\fR. | |
212 | If your system lacks both \f(CW\*(C`ualarm()\*(C'\fR and \f(CW\*(C`setitimer()\*(C'\fR you don't get | |
213 | \&\f(CW\*(C`Time::HiRes::ualarm()\*(C'\fR or \f(CW\*(C`Time::HiRes::alarm()\*(C'\fR. | |
214 | .PP | |
215 | If you try to import an unimplemented function in the \f(CW\*(C`use\*(C'\fR statement | |
216 | it will fail at compile time. | |
217 | .PP | |
218 | If your subsecond sleeping is implemented with \f(CW\*(C`nanosleep()\*(C'\fR instead | |
219 | of \f(CW\*(C`usleep()\*(C'\fR, you can mix subsecond sleeping with signals since | |
220 | \&\f(CW\*(C`nanosleep()\*(C'\fR does not use signals. This, however, is not portable, | |
221 | and you should first check for the truth value of | |
222 | \&\f(CW&Time::HiRes::d_nanosleep\fR to see whether you have nanosleep, and | |
223 | then carefully read your \f(CW\*(C`nanosleep()\*(C'\fR C \s-1API\s0 documentation for any | |
224 | peculiarities. | |
225 | .PP | |
226 | If you are using \f(CW\*(C`nanosleep\*(C'\fR for something else than mixing sleeping | |
227 | with signals, give some thought to whether Perl is the tool you should | |
228 | be using for work requiring nanosecond accuracies. | |
229 | .PP | |
230 | The following functions can be imported from this module. | |
231 | No functions are exported by default. | |
232 | .IP "gettimeofday ()" 4 | |
233 | .IX Item "gettimeofday ()" | |
234 | In array context returns a two-element array with the seconds and | |
235 | microseconds since the epoch. In scalar context returns floating | |
236 | seconds like \f(CW\*(C`Time::HiRes::time()\*(C'\fR (see below). | |
237 | .ie n .IP "usleep ( $useconds )" 4 | |
238 | .el .IP "usleep ( \f(CW$useconds\fR )" 4 | |
239 | .IX Item "usleep ( $useconds )" | |
240 | Sleeps for the number of microseconds (millionths of a second) | |
241 | specified. Returns the number of microseconds actually slept. Can | |
242 | sleep for more than one second, unlike the \f(CW\*(C`usleep\*(C'\fR system call. Can | |
243 | also sleep for zero seconds, which often works like a \fIthread yield\fR. | |
244 | See also \f(CW\*(C`Time::HiRes::usleep()\*(C'\fR, \f(CW\*(C`Time::HiRes::sleep()\*(C'\fR, and | |
245 | \&\f(CW\*(C`Time::HiRes::clock_nanosleep()\*(C'\fR. | |
246 | .Sp | |
247 | Do not expect \fIusleep()\fR to be exact down to one microsecond. | |
248 | .ie n .IP "nanosleep ( $nanoseconds )" 4 | |
249 | .el .IP "nanosleep ( \f(CW$nanoseconds\fR )" 4 | |
250 | .IX Item "nanosleep ( $nanoseconds )" | |
251 | Sleeps for the number of nanoseconds (1e9ths of a second) specified. | |
252 | Returns the number of nanoseconds actually slept (accurate only to | |
253 | microseconds, the nearest thousand of them). Can sleep for more than | |
254 | one second. Can also sleep for zero seconds, which often works like a | |
255 | \&\fIthread yield\fR. See also \f(CW\*(C`Time::HiRes::sleep()\*(C'\fR, | |
256 | \&\f(CW\*(C`Time::HiRes::usleep()\*(C'\fR, and \f(CW\*(C`Time::HiRes::clock_nanosleep()\*(C'\fR. | |
257 | .Sp | |
258 | Do not expect \fInanosleep()\fR to be exact down to one nanosecond. | |
259 | Getting even accuracy of one thousand nanoseconds is good. | |
260 | .ie n .IP "ualarm ( $useconds\fR [, \f(CW$interval_useconds ] )" 4 | |
261 | .el .IP "ualarm ( \f(CW$useconds\fR [, \f(CW$interval_useconds\fR ] )" 4 | |
262 | .IX Item "ualarm ( $useconds [, $interval_useconds ] )" | |
263 | Issues a \f(CW\*(C`ualarm\*(C'\fR call; the \f(CW$interval_useconds\fR is optional and | |
264 | will be zero if unspecified, resulting in \f(CW\*(C`alarm\*(C'\fR\-like behaviour. | |
265 | .Sp | |
266 | Note that the interaction between alarms and sleeps is unspecified. | |
267 | .IP "tv_interval" 4 | |
268 | .IX Item "tv_interval" | |
269 | tv_interval ( \f(CW$ref_to_gettimeofday\fR [, \f(CW$ref_to_later_gettimeofday\fR] ) | |
270 | .Sp | |
271 | Returns the floating seconds between the two times, which should have | |
272 | been returned by \f(CW\*(C`gettimeofday()\*(C'\fR. If the second argument is omitted, | |
273 | then the current time is used. | |
274 | .IP "time ()" 4 | |
275 | .IX Item "time ()" | |
276 | Returns a floating seconds since the epoch. This function can be | |
277 | imported, resulting in a nice drop-in replacement for the \f(CW\*(C`time\*(C'\fR | |
278 | provided with core Perl; see the \*(L"\s-1EXAMPLES\s0\*(R" below. | |
279 | .Sp | |
280 | \&\fB\s-1NOTE\s0 1\fR: This higher resolution timer can return values either less | |
281 | or more than the core \f(CW\*(C`time()\*(C'\fR, depending on whether your platform | |
282 | rounds the higher resolution timer values up, down, or to the nearest second | |
283 | to get the core \f(CW\*(C`time()\*(C'\fR, but naturally the difference should be never | |
284 | more than half a second. See also \*(L"clock_getres\*(R", if available | |
285 | in your system. | |
286 | .Sp | |
287 | \&\fB\s-1NOTE\s0 2\fR: Since Sunday, September 9th, 2001 at 01:46:40 \s-1AM\s0 \s-1GMT\s0, when | |
288 | the \f(CW\*(C`time()\*(C'\fR seconds since epoch rolled over to 1_000_000_000, the | |
289 | default floating point format of Perl and the seconds since epoch have | |
290 | conspired to produce an apparent bug: if you print the value of | |
291 | \&\f(CW\*(C`Time::HiRes::time()\*(C'\fR you seem to be getting only five decimals, not | |
292 | six as promised (microseconds). Not to worry, the microseconds are | |
293 | there (assuming your platform supports such granularity in the first | |
294 | place). What is going on is that the default floating point format of | |
295 | Perl only outputs 15 digits. In this case that means ten digits | |
296 | before the decimal separator and five after. To see the microseconds | |
297 | you can use either \f(CW\*(C`printf\*(C'\fR/\f(CW\*(C`sprintf\*(C'\fR with \f(CW"%.6f"\fR, or the | |
298 | \&\f(CW\*(C`gettimeofday()\*(C'\fR function in list context, which will give you the | |
299 | seconds and microseconds as two separate values. | |
300 | .ie n .IP "sleep ( $floating_seconds )" 4 | |
301 | .el .IP "sleep ( \f(CW$floating_seconds\fR )" 4 | |
302 | .IX Item "sleep ( $floating_seconds )" | |
303 | Sleeps for the specified amount of seconds. Returns the number of | |
304 | seconds actually slept (a floating point value). This function can | |
305 | be imported, resulting in a nice drop-in replacement for the \f(CW\*(C`sleep\*(C'\fR | |
306 | provided with perl, see the \*(L"\s-1EXAMPLES\s0\*(R" below. | |
307 | .Sp | |
308 | Note that the interaction between alarms and sleeps is unspecified. | |
309 | .ie n .IP "alarm ( $floating_seconds\fR [, \f(CW$interval_floating_seconds ] )" 4 | |
310 | .el .IP "alarm ( \f(CW$floating_seconds\fR [, \f(CW$interval_floating_seconds\fR ] )" 4 | |
311 | .IX Item "alarm ( $floating_seconds [, $interval_floating_seconds ] )" | |
312 | The \f(CW\*(C`SIGALRM\*(C'\fR signal is sent after the specified number of seconds. | |
313 | Implemented using \f(CW\*(C`ualarm()\*(C'\fR. The \f(CW$interval_floating_seconds\fR argument | |
314 | is optional and will be zero if unspecified, resulting in \f(CW\*(C`alarm()\*(C'\fR\-like | |
315 | behaviour. This function can be imported, resulting in a nice drop-in | |
316 | replacement for the \f(CW\*(C`alarm\*(C'\fR provided with perl, see the \*(L"\s-1EXAMPLES\s0\*(R" below. | |
317 | .Sp | |
318 | \&\fB\s-1NOTE\s0 1\fR: With some combinations of operating systems and Perl | |
319 | releases \f(CW\*(C`SIGALRM\*(C'\fR restarts \f(CW\*(C`select()\*(C'\fR, instead of interrupting it. | |
320 | This means that an \f(CW\*(C`alarm()\*(C'\fR followed by a \f(CW\*(C`select()\*(C'\fR may together | |
321 | take the sum of the times specified for the the \f(CW\*(C`alarm()\*(C'\fR and the | |
322 | \&\f(CW\*(C`select()\*(C'\fR, not just the time of the \f(CW\*(C`alarm()\*(C'\fR. | |
323 | .Sp | |
324 | Note that the interaction between alarms and sleeps is unspecified. | |
325 | .ie n .IP "setitimer ( $which\fR, \f(CW$floating_seconds\fR [, \f(CW$interval_floating_seconds ] )" 4 | |
326 | .el .IP "setitimer ( \f(CW$which\fR, \f(CW$floating_seconds\fR [, \f(CW$interval_floating_seconds\fR ] )" 4 | |
327 | .IX Item "setitimer ( $which, $floating_seconds [, $interval_floating_seconds ] )" | |
328 | Start up an interval timer: after a certain time, a signal arrives, | |
329 | and more signals may keep arriving at certain intervals. To disable | |
330 | an \*(L"itimer\*(R", use \f(CW$floating_seconds\fR of zero. If the | |
331 | \&\f(CW$interval_floating_seconds\fR is set to zero (or unspecified), the | |
332 | timer is disabled \fBafter\fR the next delivered signal. | |
333 | .Sp | |
334 | Use of interval timers may interfere with \f(CW\*(C`alarm()\*(C'\fR, \f(CW\*(C`sleep()\*(C'\fR, | |
335 | and \f(CW\*(C`usleep()\*(C'\fR. In standard-speak the \*(L"interaction is unspecified\*(R", | |
336 | which means that \fIanything\fR may happen: it may work, it may not. | |
337 | .Sp | |
338 | In scalar context, the remaining time in the timer is returned. | |
339 | .Sp | |
340 | In list context, both the remaining time and the interval are returned. | |
341 | .Sp | |
342 | There are usually three or four interval timers available: the | |
343 | \&\f(CW$which\fR can be \f(CW\*(C`ITIMER_REAL\*(C'\fR, \f(CW\*(C`ITIMER_VIRTUAL\*(C'\fR, \f(CW\*(C`ITIMER_PROF\*(C'\fR, or | |
344 | \&\f(CW\*(C`ITIMER_REALPROF\*(C'\fR. Note that which ones are available depends: true | |
345 | \&\s-1UNIX\s0 platforms usually have the first three, but (for example) Win32 | |
346 | and Cygwin have only \f(CW\*(C`ITIMER_REAL\*(C'\fR, and only Solaris seems to have | |
347 | \&\f(CW\*(C`ITIMER_REALPROF\*(C'\fR (which is used to profile multithreaded programs). | |
348 | .Sp | |
349 | \&\f(CW\*(C`ITIMER_REAL\*(C'\fR results in \f(CW\*(C`alarm()\*(C'\fR\-like behaviour. Time is counted in | |
350 | \&\fIreal time\fR; that is, wallclock time. \f(CW\*(C`SIGALRM\*(C'\fR is delivered when | |
351 | the timer expires. | |
352 | .Sp | |
353 | \&\f(CW\*(C`ITIMER_VIRTUAL\*(C'\fR counts time in (process) \fIvirtual time\fR; that is, | |
354 | only when the process is running. In multiprocessor/user/CPU systems | |
355 | this may be more or less than real or wallclock time. (This time is | |
356 | also known as the \fIuser time\fR.) \f(CW\*(C`SIGVTALRM\*(C'\fR is delivered when the | |
357 | timer expires. | |
358 | .Sp | |
359 | \&\f(CW\*(C`ITIMER_PROF\*(C'\fR counts time when either the process virtual time or when | |
360 | the operating system is running on behalf of the process (such as I/O). | |
361 | (This time is also known as the \fIsystem time\fR.) (The sum of user | |
362 | time and system time is known as the \fI\s-1CPU\s0 time\fR.) \f(CW\*(C`SIGPROF\*(C'\fR is | |
363 | delivered when the timer expires. \f(CW\*(C`SIGPROF\*(C'\fR can interrupt system calls. | |
364 | .Sp | |
365 | The semantics of interval timers for multithreaded programs are | |
366 | system\-specific, and some systems may support additional interval | |
367 | timers. See your \f(CW\*(C`setitimer()\*(C'\fR documentation. | |
368 | .ie n .IP "getitimer ( $which )" 4 | |
369 | .el .IP "getitimer ( \f(CW$which\fR )" 4 | |
370 | .IX Item "getitimer ( $which )" | |
371 | Return the remaining time in the interval timer specified by \f(CW$which\fR. | |
372 | .Sp | |
373 | In scalar context, the remaining time is returned. | |
374 | .Sp | |
375 | In list context, both the remaining time and the interval are returned. | |
376 | The interval is always what you put in using \f(CW\*(C`setitimer()\*(C'\fR. | |
377 | .ie n .IP "clock_gettime ( $which )" 4 | |
378 | .el .IP "clock_gettime ( \f(CW$which\fR )" 4 | |
379 | .IX Item "clock_gettime ( $which )" | |
380 | Return as seconds the current value of the \s-1POSIX\s0 high resolution timer | |
381 | specified by \f(CW$which\fR. All implementations that support \s-1POSIX\s0 high | |
382 | resolution timers are supposed to support at least the \f(CW$which\fR value | |
383 | of \f(CW\*(C`CLOCK_REALTIME\*(C'\fR, which is supposed to return results close to the | |
384 | results of \f(CW\*(C`gettimeofday\*(C'\fR, or the number of seconds since 00:00:00:00 | |
385 | January 1, 1970 Greenwich Mean Time (\s-1GMT\s0). Do not assume that | |
386 | \&\s-1CLOCK_REALTIME\s0 is zero, it might be one, or something else. | |
387 | Another potentially useful (but not available everywhere) value is | |
388 | \&\f(CW\*(C`CLOCK_MONOTONIC\*(C'\fR, which guarantees a monotonically increasing time | |
389 | value (unlike \fItime()\fR, which can be adjusted). See your system | |
390 | documentation for other possibly supported values. | |
391 | .ie n .IP "clock_getres ( $which )" 4 | |
392 | .el .IP "clock_getres ( \f(CW$which\fR )" 4 | |
393 | .IX Item "clock_getres ( $which )" | |
394 | Return as seconds the resolution of the \s-1POSIX\s0 high resolution timer | |
395 | specified by \f(CW$which\fR. All implementations that support \s-1POSIX\s0 high | |
396 | resolution timers are supposed to support at least the \f(CW$which\fR value | |
397 | of \f(CW\*(C`CLOCK_REALTIME\*(C'\fR, see \*(L"clock_gettime\*(R". | |
398 | .ie n .IP "clock_nanosleep ( $which\fR, \f(CW$seconds\fR, \f(CW$flags = 0)" 4 | |
399 | .el .IP "clock_nanosleep ( \f(CW$which\fR, \f(CW$seconds\fR, \f(CW$flags\fR = 0)" 4 | |
400 | .IX Item "clock_nanosleep ( $which, $seconds, $flags = 0)" | |
401 | Sleeps for the number of seconds (1e9ths of a second) specified. | |
402 | Returns the number of seconds actually slept. The \f(CW$which\fR is the | |
403 | \&\*(L"clock id\*(R", as with \fIclock_gettime()\fR and \fIclock_getres()\fR. The flags | |
404 | default to zero but \f(CW\*(C`TIMER_ABSTIME\*(C'\fR can specified (must be exported | |
405 | explicitly) which means that \f(CW$nanoseconds\fR is not a time interval | |
406 | (as is the default) but instead an absolute time. Can sleep for more | |
407 | than one second. Can also sleep for zero seconds, which often works | |
408 | like a \fIthread yield\fR. See also \f(CW\*(C`Time::HiRes::sleep()\*(C'\fR, | |
409 | \&\f(CW\*(C`Time::HiRes::usleep()\*(C'\fR, and \f(CW\*(C`Time::HiRes::nanosleep()\*(C'\fR. | |
410 | .Sp | |
411 | Do not expect \fIclock_nanosleep()\fR to be exact down to one nanosecond. | |
412 | Getting even accuracy of one thousand nanoseconds is good. | |
413 | .IP "\fIclock()\fR" 4 | |
414 | .IX Item "clock()" | |
415 | Return as seconds the \fIprocess time\fR (user + system time) spent by | |
416 | the process since the first call to \fIclock()\fR (the definition is \fBnot\fR | |
417 | \&\*(L"since the start of the process\*(R", 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 \fIclock()\fR, and subtract that value from the following results of \fIclock()\fR. | |
421 | .Sp | |
422 | The time returned also includes the process times of the terminated | |
423 | child processes for which \fIwait()\fR has been executed. This value is | |
424 | somewhat like the second value returned by the \fItimes()\fR 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 | .SH "EXAMPLES" | |
429 | .IX Header "EXAMPLES" | |
430 | .Vb 1 | |
431 | \& use Time::HiRes qw(usleep ualarm gettimeofday tv_interval); | |
432 | .Ve | |
433 | .PP | |
434 | .Vb 2 | |
435 | \& $microseconds = 750_000; | |
436 | \& usleep($microseconds); | |
437 | .Ve | |
438 | .PP | |
439 | .Vb 2 | |
440 | \& # signal alarm in 2.5s & every .1s thereafter | |
441 | \& ualarm(2_500_000, 100_000); | |
442 | .Ve | |
443 | .PP | |
444 | .Vb 2 | |
445 | \& # get seconds and microseconds since the epoch | |
446 | \& ($s, $usec) = gettimeofday(); | |
447 | .Ve | |
448 | .PP | |
449 | .Vb 7 | |
450 | \& # measure elapsed time | |
451 | \& # (could also do by subtracting 2 gettimeofday return values) | |
452 | \& $t0 = [gettimeofday]; | |
453 | \& # do bunch of stuff here | |
454 | \& $t1 = [gettimeofday]; | |
455 | \& # do more stuff here | |
456 | \& $t0_t1 = tv_interval $t0, $t1; | |
457 | .Ve | |
458 | .PP | |
459 | .Vb 2 | |
460 | \& $elapsed = tv_interval ($t0, [gettimeofday]); | |
461 | \& $elapsed = tv_interval ($t0); # equivalent code | |
462 | .Ve | |
463 | .PP | |
464 | .Vb 8 | |
465 | \& # | |
466 | \& # replacements for time, alarm and sleep that know about | |
467 | \& # floating seconds | |
468 | \& # | |
469 | \& use Time::HiRes; | |
470 | \& $now_fractions = Time::HiRes::time; | |
471 | \& Time::HiRes::sleep (2.5); | |
472 | \& Time::HiRes::alarm (10.6666666); | |
473 | .Ve | |
474 | .PP | |
475 | .Vb 4 | |
476 | \& use Time::HiRes qw ( time alarm sleep ); | |
477 | \& $now_fractions = time; | |
478 | \& sleep (2.5); | |
479 | \& alarm (10.6666666); | |
480 | .Ve | |
481 | .PP | |
482 | .Vb 2 | |
483 | \& # Arm an interval timer to go off first at 10 seconds and | |
484 | \& # after that every 2.5 seconds, in process virtual time | |
485 | .Ve | |
486 | .PP | |
487 | .Vb 1 | |
488 | \& use Time::HiRes qw ( setitimer ITIMER_VIRTUAL time ); | |
489 | .Ve | |
490 | .PP | |
491 | .Vb 2 | |
492 | \& $SIG{VTALRM} = sub { print time, "\en" }; | |
493 | \& setitimer(ITIMER_VIRTUAL, 10, 2.5); | |
494 | .Ve | |
495 | .PP | |
496 | .Vb 5 | |
497 | \& use Time::HiRes qw( clock_gettime clock_getres CLOCK_REALTIME ); | |
498 | \& # Read the POSIX high resolution timer. | |
499 | \& my $high = clock_getres(CLOCK_REALTIME); | |
500 | \& # But how accurate we can be, really? | |
501 | \& my $reso = clock_getres(CLOCK_REALTIME); | |
502 | .Ve | |
503 | .PP | |
504 | .Vb 3 | |
505 | \& use Time::HiRes qw( clock_nanosleep TIMER_ABSTIME ); | |
506 | \& clock_nanosleep(CLOCK_REALTIME, 1e6); | |
507 | \& clock_nanosleep(CLOCK_REALTIME, 2e9, TIMER_ABSTIME); | |
508 | .Ve | |
509 | .PP | |
510 | .Vb 5 | |
511 | \& use Time::HiRes qw( clock ); | |
512 | \& my $clock0 = clock(); | |
513 | \& ... # Do something. | |
514 | \& my $clock1 = clock(); | |
515 | \& my $clockd = $clock1 - $clock0; | |
516 | .Ve | |
517 | .SH "C API" | |
518 | .IX Header "C API" | |
519 | In addition to the perl \s-1API\s0 described above, a C \s-1API\s0 is available for | |
520 | extension writers. The following C functions are available in the | |
521 | modglobal hash: | |
522 | .PP | |
523 | .Vb 4 | |
524 | \& name C prototype | |
525 | \& --------------- ---------------------- | |
526 | \& Time::NVtime double (*)() | |
527 | \& Time::U2time void (*)(pTHX_ UV ret[2]) | |
528 | .Ve | |
529 | .PP | |
530 | Both functions return equivalent information (like \f(CW\*(C`gettimeofday\*(C'\fR) | |
531 | but with different representations. The names \f(CW\*(C`NVtime\*(C'\fR and \f(CW\*(C`U2time\*(C'\fR | |
532 | were selected mainly because they are operating system independent. | |
533 | (\f(CW\*(C`gettimeofday\*(C'\fR is Unix\-centric, though some platforms like Win32 and | |
534 | \&\s-1VMS\s0 have emulations for it.) | |
535 | .PP | |
536 | Here is an example of using \f(CW\*(C`NVtime\*(C'\fR from C: | |
537 | .PP | |
538 | .Vb 6 | |
539 | \& double (*myNVtime)(); /* Returns -1 on failure. */ | |
540 | \& SV **svp = hv_fetch(PL_modglobal, "Time::NVtime", 12, 0); | |
541 | \& if (!svp) croak("Time::HiRes is required"); | |
542 | \& if (!SvIOK(*svp)) croak("Time::NVtime isn't a function pointer"); | |
543 | \& myNVtime = INT2PTR(double(*)(), SvIV(*svp)); | |
544 | \& printf("The current time is: %f\en", (*myNVtime)()); | |
545 | .Ve | |
546 | .SH "DIAGNOSTICS" | |
547 | .IX Header "DIAGNOSTICS" | |
548 | .Sh "negative time not invented yet" | |
549 | .IX Subsection "negative time not invented yet" | |
550 | You tried to use a negative time argument. | |
551 | .Sh "internal error: useconds < 0 (unsigned ... signed ...)" | |
552 | .IX Subsection "internal error: useconds < 0 (unsigned ... signed ...)" | |
553 | Something went horribly wrong\*(-- the number of microseconds that cannot | |
554 | become negative just became negative. Maybe your compiler is broken? | |
555 | .SH "CAVEATS" | |
556 | .IX Header "CAVEATS" | |
557 | Notice that the core \f(CW\*(C`time()\*(C'\fR maybe rounding rather than truncating. | |
558 | What this means is that the core \f(CW\*(C`time()\*(C'\fR may be reporting the time | |
559 | as one second later than \f(CW\*(C`gettimeofday()\*(C'\fR and \f(CW\*(C`Time::HiRes::time()\*(C'\fR. | |
560 | .PP | |
561 | Adjusting the system clock (either manually or by services like ntp) | |
562 | may cause problems, especially for long running programs that assume | |
563 | a monotonously increasing time (note that all platforms do not adjust | |
564 | time as gracefully as \s-1UNIX\s0 ntp does). For example in Win32 (and derived | |
565 | platforms like Cygwin and MinGW) the \fITime::HiRes::time()\fR may temporarily | |
566 | drift off from the system clock (and the original \fItime()\fR) by up to 0.5 | |
567 | seconds. Time::HiRes will notice this eventually and recalibrate. | |
568 | Note that since Time::HiRes 1.77 the clock_gettime(\s-1CLOCK_MONOTONIC\s0) | |
569 | might help in this (in case your system supports \s-1CLOCK_MONOTONIC\s0). | |
570 | .SH "SEE ALSO" | |
571 | .IX Header "SEE ALSO" | |
572 | Perl modules BSD::Resource, Time::TAI64. | |
573 | .PP | |
574 | Your system documentation for \f(CW\*(C`clock_gettime\*(C'\fR, \f(CW\*(C`clock_settime\*(C'\fR, | |
575 | \&\f(CW\*(C`gettimeofday\*(C'\fR, \f(CW\*(C`getitimer\*(C'\fR, \f(CW\*(C`setitimer\*(C'\fR, \f(CW\*(C`ualarm\*(C'\fR. | |
576 | .SH "AUTHORS" | |
577 | .IX Header "AUTHORS" | |
578 | D. Wegscheid <wegscd@whirlpool.com> | |
579 | R. Schertler <roderick@argon.org> | |
580 | J. Hietaniemi <jhi@iki.fi> | |
581 | G. Aas <gisle@aas.no> | |
582 | .SH "COPYRIGHT AND LICENSE" | |
583 | .IX Header "COPYRIGHT AND LICENSE" | |
584 | Copyright (c) 1996\-2002 Douglas E. Wegscheid. All rights reserved. | |
585 | .PP | |
586 | Copyright (c) 2002, 2003, 2004, 2005 Jarkko Hietaniemi. All rights reserved. | |
587 | .PP | |
588 | This program is free software; you can redistribute it and/or modify | |
589 | it under the same terms as Perl itself. |