mingw/html/ext/Time/HiRes/HiRes.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>Time::HiRes - High resolution alarm, sleep, gettimeofday, interval timers</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;Time::HiRes - High resolution alarm, sleep, gettimeofday, interval timers</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <li><a href="#examples">EXAMPLES</a></li>
  26         <li><a href="#c_api">C API</a></li>
  27         <li><a href="#diagnostics">DIAGNOSTICS</a></li>
  28         <ul>
  29
  30                 <li><a href="#negative_time_not_invented_yet">negative time not invented yet</a></li>
  31                 <li><a href="#internal_error__useconds___0__unsigned_____signed_____">internal error: useconds &lt; 0 (unsigned ... signed ...)</a></li>
  32         </ul>
  33
  34         <li><a href="#caveats">CAVEATS</a></li>
  35         <li><a href="#see_also">SEE ALSO</a></li>
  36         <li><a href="#authors">AUTHORS</a></li>
  37         <li><a href="#copyright_and_license">COPYRIGHT AND LICENSE</a></li>
  38 </ul>
  39 <!-- INDEX END -->
  40
  41 <hr />
  42 <p>
  43 </p>
  44 <h1><a name="name">NAME</a></h1>
  45 <p>Time::HiRes - High resolution alarm, sleep, gettimeofday, interval timers</p>
  46 <p>
  47 </p>
  48 <hr />
  49 <h1><a name="synopsis">SYNOPSIS</a></h1>
  50 <pre>
  51   use Time::HiRes qw( usleep ualarm gettimeofday tv_interval nanosleep
  52                       clock_gettime clock_getres clock_nanosleep clock );</pre>
  53 <pre>
  54   usleep ($microseconds);
  55   nanosleep ($nanoseconds);</pre>
  56 <pre>
  57   ualarm ($microseconds);
  58   ualarm ($microseconds, $interval_microseconds);</pre>
  59 <pre>
  60   $t0 = [gettimeofday];
  61   ($seconds, $microseconds) = gettimeofday;</pre>
  62 <pre>
  63   $elapsed = tv_interval ( $t0, [$seconds, $microseconds]);
  64   $elapsed = tv_interval ( $t0, [gettimeofday]);
  65   $elapsed = tv_interval ( $t0 );</pre>
  66 <pre>
  67   use Time::HiRes qw ( time alarm sleep );</pre>
  68 <pre>
  69   $now_fractions = time;
  70   sleep ($floating_seconds);
  71   alarm ($floating_seconds);
  72   alarm ($floating_seconds, $floating_interval);</pre>
  73 <pre>
  74   use Time::HiRes qw( setitimer getitimer
  75                       ITIMER_REAL ITIMER_VIRTUAL ITIMER_PROF ITIMER_REALPROF );</pre>
  76 <pre>
  77   setitimer ($which, $floating_seconds, $floating_interval );
  78   getitimer ($which);</pre>
  79 <pre>
  80   $realtime   = clock_gettime(CLOCK_REALTIME);
  81   $resolution = clock_getres(CLOCK_REALTIME);</pre>
  82 <pre>
  83   clock_nanosleep(CLOCK_REALTIME, 1.5);
  84   clock_nanosleep(CLOCK_REALTIME, time() + 10, TIMER_ABSTIME);</pre>
  85 <pre>
  86   my $ticktock = clock();</pre>
  87 <p>
  88 </p>
  89 <hr />
  90 <h1><a name="description">DESCRIPTION</a></h1>
  91 <p>The <code>Time::HiRes</code> module implements a Perl interface to the
  92 <a href="#item_usleep"><code>usleep</code></a>, <a href="#item_nanosleep"><code>nanosleep</code></a>, <a href="#item_ualarm"><code>ualarm</code></a>, <a href="#item_gettimeofday"><code>gettimeofday</code></a>, and
  93 <a href="#item_setitimer"><code>setitimer</code></a>/<a href="#item_getitimer"><code>getitimer</code></a> system calls, in other words, high
  94 resolution time and timers. See the <a href="#examples">EXAMPLES</a> section below and the
  95 test scripts for usage; see your system documentation for the
  96 description of the underlying <a href="#item_nanosleep"><code>nanosleep</code></a> or <a href="#item_usleep"><code>usleep</code></a>, <a href="#item_ualarm"><code>ualarm</code></a>,
  97 <a href="#item_gettimeofday"><code>gettimeofday</code></a>, and <a href="#item_setitimer"><code>setitimer</code></a>/<a href="#item_getitimer"><code>getitimer</code></a> calls.</p>
  98 <p>If your system lacks <a href="#item_gettimeofday"><code>gettimeofday()</code></a> or an emulation of it you don't
  99 get <a href="#item_gettimeofday"><code>gettimeofday()</code></a> or the one-argument form of <a href="#item_tv_interval"><code>tv_interval()</code></a>.
 100 If your system lacks all of <a href="#item_nanosleep"><code>nanosleep()</code></a>, <a href="#item_usleep"><code>usleep()</code></a>,
 101 <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_select"><code>select()</code></a>, and <code>poll</code>, you don't get <a href="#item_usleep"><code>Time::HiRes::usleep()</code></a>,
 102 <a href="#item_nanosleep"><code>Time::HiRes::nanosleep()</code></a>, or <a href="#item_sleep"><code>Time::HiRes::sleep()</code></a>.
 103 If your system lacks both <a href="#item_ualarm"><code>ualarm()</code></a> and <a href="#item_setitimer"><code>setitimer()</code></a> you don't get
 104 <a href="#item_ualarm"><code>Time::HiRes::ualarm()</code></a> or <a href="#item_alarm"><code>Time::HiRes::alarm()</code></a>.</p>
 105 <p>If you try to import an unimplemented function in the <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_use"><code>use</code></a> statement
 106 it will fail at compile time.</p>
 107 <p>If your subsecond sleeping is implemented with <a href="#item_nanosleep"><code>nanosleep()</code></a> instead
 108 of <a href="#item_usleep"><code>usleep()</code></a>, you can mix subsecond sleeping with signals since
 109 <a href="#item_nanosleep"><code>nanosleep()</code></a> does not use signals.  This, however, is not portable,
 110 and you should first check for the truth value of
 111 <code>&amp;Time::HiRes::d_nanosleep</code> to see whether you have nanosleep, and
 112 then carefully read your <a href="#item_nanosleep"><code>nanosleep()</code></a> C API documentation for any
 113 peculiarities.</p>
 114 <p>If you are using <a href="#item_nanosleep"><code>nanosleep</code></a> for something else than mixing sleeping
 115 with signals, give some thought to whether Perl is the tool you should
 116 be using for work requiring nanosecond accuracies.</p>
 117 <p>The following functions can be imported from this module.
 118 No functions are exported by default.</p>
 119 <dl>
 120 <dt><strong><a name="item_gettimeofday">gettimeofday ()</a></strong>
 121
 122 <dd>
 123 <p>In array context returns a two-element array with the seconds and
 124 microseconds since the epoch.  In scalar context returns floating
 125 seconds like <a href="#item_time"><code>Time::HiRes::time()</code></a> (see below).</p>
 126 </dd>
 127 </li>
 128 <dt><strong><a name="item_usleep">usleep ( $useconds )</a></strong>
 129
 130 <dd>
 131 <p>Sleeps for the number of microseconds (millionths of a second)
 132 specified.  Returns the number of microseconds actually slept.  Can
 133 sleep for more than one second, unlike the <a href="#item_usleep"><code>usleep</code></a> system call. Can
 134 also sleep for zero seconds, which often works like a <em>thread yield</em>.
 135 See also <a href="#item_usleep"><code>Time::HiRes::usleep()</code></a>, <a href="#item_sleep"><code>Time::HiRes::sleep()</code></a>, and
 136 <a href="#item_clock_nanosleep"><code>Time::HiRes::clock_nanosleep()</code></a>.</p>
 137 </dd>
 138 <dd>
 139 <p>Do not expect <a href="#item_usleep"><code>usleep()</code></a> to be exact down to one microsecond.</p>
 140 </dd>
 141 </li>
 142 <dt><strong><a name="item_nanosleep">nanosleep ( $nanoseconds )</a></strong>
 143
 144 <dd>
 145 <p>Sleeps for the number of nanoseconds (1e9ths of a second) specified.
 146 Returns the number of nanoseconds actually slept (accurate only to
 147 microseconds, the nearest thousand of them).  Can sleep for more than
 148 one second.  Can also sleep for zero seconds, which often works like a
 149 <em>thread yield</em>.  See also <a href="#item_sleep"><code>Time::HiRes::sleep()</code></a>,
 150 <a href="#item_usleep"><code>Time::HiRes::usleep()</code></a>, and <a href="#item_clock_nanosleep"><code>Time::HiRes::clock_nanosleep()</code></a>.</p>
 151 </dd>
 152 <dd>
 153 <p>Do not expect <a href="#item_nanosleep"><code>nanosleep()</code></a> to be exact down to one nanosecond.
 154 Getting even accuracy of one thousand nanoseconds is good.</p>
 155 </dd>
 156 </li>
 157 <dt><strong><a name="item_ualarm">ualarm ( $useconds [, $interval_useconds ] )</a></strong>
 158
 159 <dd>
 160 <p>Issues a <a href="#item_ualarm"><code>ualarm</code></a> call; the <code>$interval_useconds</code> is optional and
 161 will be zero if unspecified, resulting in <a href="#item_alarm"><code>alarm</code></a>-like behaviour.</p>
 162 </dd>
 163 <dd>
 164 <p>Note that the interaction between alarms and sleeps is unspecified.</p>
 165 </dd>
 166 </li>
 167 <dt><strong><a name="item_tv_interval">tv_interval</a></strong>
 168
 169 <dd>
 170 <p>tv_interval ( $ref_to_gettimeofday [, $ref_to_later_gettimeofday] )</p>
 171 </dd>
 172 <dd>
 173 <p>Returns the floating seconds between the two times, which should have
 174 been returned by <a href="#item_gettimeofday"><code>gettimeofday()</code></a>. If the second argument is omitted,
 175 then the current time is used.</p>
 176 </dd>
 177 </li>
 178 <dt><strong><a name="item_time">time ()</a></strong>
 179
 180 <dd>
 181 <p>Returns a floating seconds since the epoch. This function can be
 182 imported, resulting in a nice drop-in replacement for the <a href="#item_time"><code>time</code></a>
 183 provided with core Perl; see the <a href="#examples">EXAMPLES</a> below.</p>
 184 </dd>
 185 <dd>
 186 <p><strong>NOTE 1</strong>: This higher resolution timer can return values either less
 187 or more than the core <a href="#item_time"><code>time()</code></a>, depending on whether your platform
 188 rounds the higher resolution timer values up, down, or to the nearest second
 189 to get the core <a href="#item_time"><code>time()</code></a>, but naturally the difference should be never
 190 more than half a second.  See also <a href="#item_clock_getres">clock_getres</a>, if available
 191 in your system.</p>
 192 </dd>
 193 <dd>
 194 <p><strong>NOTE 2</strong>: Since Sunday, September 9th, 2001 at 01:46:40 AM GMT, when
 195 the <a href="#item_time"><code>time()</code></a> seconds since epoch rolled over to 1_000_000_000, the
 196 default floating point format of Perl and the seconds since epoch have
 197 conspired to produce an apparent bug: if you print the value of
 198 <a href="#item_time"><code>Time::HiRes::time()</code></a> you seem to be getting only five decimals, not
 199 six as promised (microseconds).  Not to worry, the microseconds are
 200 there (assuming your platform supports such granularity in the first
 201 place).  What is going on is that the default floating point format of
 202 Perl only outputs 15 digits.  In this case that means ten digits
 203 before the decimal separator and five after.  To see the microseconds
 204 you can use either <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_printf"><code>printf</code></a>/<code>sprintf</code> with <code>&quot;%.6f&quot;</code>, or the
 205 <a href="#item_gettimeofday"><code>gettimeofday()</code></a> function in list context, which will give you the
 206 seconds and microseconds as two separate values.</p>
 207 </dd>
 208 </li>
 209 <dt><strong><a name="item_sleep">sleep ( $floating_seconds )</a></strong>
 210
 211 <dd>
 212 <p>Sleeps for the specified amount of seconds.  Returns the number of
 213 seconds actually slept (a floating point value).  This function can
 214 be imported, resulting in a nice drop-in replacement for the <a href="#item_sleep"><code>sleep</code></a>
 215 provided with perl, see the <a href="#examples">EXAMPLES</a> below.</p>
 216 </dd>
 217 <dd>
 218 <p>Note that the interaction between alarms and sleeps is unspecified.</p>
 219 </dd>
 220 </li>
 221 <dt><strong><a name="item_alarm">alarm ( $floating_seconds [, $interval_floating_seconds ] )</a></strong>
 222
 223 <dd>
 224 <p>The <code>SIGALRM</code> signal is sent after the specified number of seconds.
 225 Implemented using <a href="#item_ualarm"><code>ualarm()</code></a>.  The <code>$interval_floating_seconds</code> argument
 226 is optional and will be zero if unspecified, resulting in <a href="#item_alarm"><code>alarm()</code></a>-like
 227 behaviour.  This function can be imported, resulting in a nice drop-in
 228 replacement for the <a href="#item_alarm"><code>alarm</code></a> provided with perl, see the <a href="#examples">EXAMPLES</a> below.</p>
 229 </dd>
 230 <dd>
 231 <p><strong>NOTE 1</strong>: With some combinations of operating systems and Perl
 232 releases <code>SIGALRM</code> restarts <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_select"><code>select()</code></a>, instead of interrupting it.
 233 This means that an <a href="#item_alarm"><code>alarm()</code></a> followed by a <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_select"><code>select()</code></a> may together
 234 take the sum of the times specified for the the <a href="#item_alarm"><code>alarm()</code></a> and the
 235 <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_select"><code>select()</code></a>, not just the time of the <a href="#item_alarm"><code>alarm()</code></a>.</p>
 236 </dd>
 237 <dd>
 238 <p>Note that the interaction between alarms and sleeps is unspecified.</p>
 239 </dd>
 240 </li>
 241 <dt><strong><a name="item_setitimer">setitimer ( $which, $floating_seconds [, $interval_floating_seconds ] )</a></strong>
 242
 243 <dd>
 244 <p>Start up an interval timer: after a certain time, a signal arrives,
 245 and more signals may keep arriving at certain intervals.  To disable
 246 an ``itimer'', use <code>$floating_seconds</code> of zero.  If the
 247 <code>$interval_floating_seconds</code> is set to zero (or unspecified), the
 248 timer is disabled <strong>after</strong> the next delivered signal.</p>
 249 </dd>
 250 <dd>
 251 <p>Use of interval timers may interfere with <a href="#item_alarm"><code>alarm()</code></a>, <a href="#item_sleep"><code>sleep()</code></a>,
 252 and <a href="#item_usleep"><code>usleep()</code></a>.  In standard-speak the ``interaction is unspecified'',
 253 which means that <em>anything</em> may happen: it may work, it may not.</p>
 254 </dd>
 255 <dd>
 256 <p>In scalar context, the remaining time in the timer is returned.</p>
 257 </dd>
 258 <dd>
 259 <p>In list context, both the remaining time and the interval are returned.</p>
 260 </dd>
 261 <dd>
 262 <p>There are usually three or four interval timers available: the
 263 <code>$which</code> can be <code>ITIMER_REAL</code>, <code>ITIMER_VIRTUAL</code>, <code>ITIMER_PROF</code>, or
 264 <code>ITIMER_REALPROF</code>.  Note that which ones are available depends: true
 265 UNIX platforms usually have the first three, but (for example) Win32
 266 and Cygwin have only <code>ITIMER_REAL</code>, and only Solaris seems to have
 267 <code>ITIMER_REALPROF</code> (which is used to profile multithreaded programs).</p>
 268 </dd>
 269 <dd>
 270 <p><code>ITIMER_REAL</code> results in <a href="#item_alarm"><code>alarm()</code></a>-like behaviour.  Time is counted in
 271 <em>real time</em>; that is, wallclock time.  <code>SIGALRM</code> is delivered when
 272 the timer expires.</p>
 273 </dd>
 274 <dd>
 275 <p><code>ITIMER_VIRTUAL</code> counts time in (process) <em>virtual time</em>; that is,
 276 only when the process is running.  In multiprocessor/user/CPU systems
 277 this may be more or less than real or wallclock time.  (This time is
 278 also known as the <em>user time</em>.)  <code>SIGVTALRM</code> is delivered when the
 279 timer expires.</p>
 280 </dd>
 281 <dd>
 282 <p><code>ITIMER_PROF</code> counts time when either the process virtual time or when
 283 the operating system is running on behalf of the process (such as I/O).
 284 (This time is also known as the <em>system time</em>.)  (The sum of user
 285 time and system time is known as the <em>CPU time</em>.)  <code>SIGPROF</code> is
 286 delivered when the timer expires.  <code>SIGPROF</code> can interrupt system calls.</p>
 287 </dd>
 288 <dd>
 289 <p>The semantics of interval timers for multithreaded programs are
 290 system-specific, and some systems may support additional interval
 291 timers.  See your <a href="#item_setitimer"><code>setitimer()</code></a> documentation.</p>
 292 </dd>
 293 </li>
 294 <dt><strong><a name="item_getitimer">getitimer ( $which )</a></strong>
 295
 296 <dd>
 297 <p>Return the remaining time in the interval timer specified by <code>$which</code>.</p>
 298 </dd>
 299 <dd>
 300 <p>In scalar context, the remaining time is returned.</p>
 301 </dd>
 302 <dd>
 303 <p>In list context, both the remaining time and the interval are returned.
 304 The interval is always what you put in using <a href="#item_setitimer"><code>setitimer()</code></a>.</p>
 305 </dd>
 306 </li>
 307 <dt><strong><a name="item_clock_gettime">clock_gettime ( $which )</a></strong>
 308
 309 <dd>
 310 <p>Return as seconds the current value of the POSIX high resolution timer
 311 specified by <code>$which</code>.  All implementations that support POSIX high
 312 resolution timers are supposed to support at least the <code>$which</code> value
 313 of <code>CLOCK_REALTIME</code>, which is supposed to return results close to the
 314 results of <a href="#item_gettimeofday"><code>gettimeofday</code></a>, or the number of seconds since 00:00:00:00
 315 January 1, 1970 Greenwich Mean Time (GMT).  Do not assume that
 316 CLOCK_REALTIME is zero, it might be one, or something else.
 317 Another potentially useful (but not available everywhere) value is
 318 <code>CLOCK_MONOTONIC</code>, which guarantees a monotonically increasing time
 319 value (unlike time(), which can be adjusted).  See your system
 320 documentation for other possibly supported values.</p>
 321 </dd>
 322 </li>
 323 <dt><strong><a name="item_clock_getres">clock_getres ( $which )</a></strong>
 324
 325 <dd>
 326 <p>Return as seconds the resolution of the POSIX high resolution timer
 327 specified by <code>$which</code>.  All implementations that support POSIX high
 328 resolution timers are supposed to support at least the <code>$which</code> value
 329 of <code>CLOCK_REALTIME</code>, see <a href="#item_clock_gettime">clock_gettime</a>.</p>
 330 </dd>
 331 </li>
 332 <dt><strong><a name="item_clock_nanosleep">clock_nanosleep ( $which, $seconds, $flags = 0)</a></strong>
 333
 334 <dd>
 335 <p>Sleeps for the number of seconds (1e9ths of a second) specified.
 336 Returns the number of seconds actually slept.  The $which is the
 337 ``clock id'', as with <a href="#item_clock_gettime"><code>clock_gettime()</code></a> and clock_getres().  The flags
 338 default to zero but <code>TIMER_ABSTIME</code> can specified (must be exported
 339 explicitly) which means that <code>$nanoseconds</code> is not a time interval
 340 (as is the default) but instead an absolute time.  Can sleep for more
 341 than one second.  Can also sleep for zero seconds, which often works
 342 like a <em>thread yield</em>.  See also <a href="#item_sleep"><code>Time::HiRes::sleep()</code></a>,
 343 <a href="#item_usleep"><code>Time::HiRes::usleep()</code></a>, and <a href="#item_nanosleep"><code>Time::HiRes::nanosleep()</code></a>.</p>
 344 </dd>
 345 <dd>
 346 <p>Do not expect <a href="#item_clock_nanosleep"><code>clock_nanosleep()</code></a> to be exact down to one nanosecond.
 347 Getting even accuracy of one thousand nanoseconds is good.</p>
 348 </dd>
 349 </li>
 350 <dt><strong><a name="item_clock"><code>clock()</code></a></strong>
 351
 352 <dd>
 353 <p>Return as seconds the <em>process time</em> (user + system time) spent by
 354 the process since the first call to <a href="#item_clock"><code>clock()</code></a> (the definition is <strong>not</strong>
 355 ``since the start of the process'', though if you are lucky these times
 356 may be quite close to each other, depending on the system).  What this
 357 means is that you probably need to store the result of your first call
 358 to clock(), and subtract that value from the following results of clock().</p>
 359 </dd>
 360 <dd>
 361 <p>The time returned also includes the process times of the terminated
 362 child processes for which <code>wait()</code> has been executed.  This value is
 363 somewhat like the second value returned by the <code>times()</code> of core Perl,
 364 but not necessarily identical.  Note that due to backward
 365 compatibility limitations the returned value may wrap around at about
 366 2147 seconds or at about 36 minutes.</p>
 367 </dd>
 368 </li>
 369 </dl>
 370 <p>
 371 </p>
 372 <hr />
 373 <h1><a name="examples">EXAMPLES</a></h1>
 374 <pre>
 375   use Time::HiRes qw(usleep ualarm gettimeofday tv_interval);</pre>
 376 <pre>
 377   $microseconds = 750_000;
 378   usleep($microseconds);</pre>
 379 <pre>
 380   # signal alarm in 2.5s &amp; every .1s thereafter
 381   ualarm(2_500_000, 100_000);</pre>
 382 <pre>
 383   # get seconds and microseconds since the epoch
 384   ($s, $usec) = gettimeofday();</pre>
 385 <pre>
 386   # measure elapsed time
 387   # (could also do by subtracting 2 gettimeofday return values)
 388   $t0 = [gettimeofday];
 389   # do bunch of stuff here
 390   $t1 = [gettimeofday];
 391   # do more stuff here
 392   $t0_t1 = tv_interval $t0, $t1;</pre>
 393 <pre>
 394   $elapsed = tv_interval ($t0, [gettimeofday]);
 395   $elapsed = tv_interval ($t0); # equivalent code</pre>
 396 <pre>
 397   #
 398   # replacements for time, alarm and sleep that know about
 399   # floating seconds
 400   #
 401   use Time::HiRes;
 402   $now_fractions = Time::HiRes::time;
 403   Time::HiRes::sleep (2.5);
 404   Time::HiRes::alarm (10.6666666);</pre>
 405 <pre>
 406   use Time::HiRes qw ( time alarm sleep );
 407   $now_fractions = time;
 408   sleep (2.5);
 409   alarm (10.6666666);</pre>
 410 <pre>
 411   # Arm an interval timer to go off first at 10 seconds and
 412   # after that every 2.5 seconds, in process virtual time</pre>
 413 <pre>
 414   use Time::HiRes qw ( setitimer ITIMER_VIRTUAL time );</pre>
 415 <pre>
 416   $SIG{VTALRM} = sub { print time, &quot;\n&quot; };
 417   setitimer(ITIMER_VIRTUAL, 10, 2.5);</pre>
 418 <pre>
 419   use Time::HiRes qw( clock_gettime clock_getres CLOCK_REALTIME );
 420   # Read the POSIX high resolution timer.
 421   my $high = clock_getres(CLOCK_REALTIME);
 422   # But how accurate we can be, really?
 423   my $reso = clock_getres(CLOCK_REALTIME);</pre>
 424 <pre>
 425   use Time::HiRes qw( clock_nanosleep TIMER_ABSTIME );
 426   clock_nanosleep(CLOCK_REALTIME, 1e6);
 427   clock_nanosleep(CLOCK_REALTIME, 2e9, TIMER_ABSTIME);</pre>
 428 <pre>
 429   use Time::HiRes qw( clock );
 430   my $clock0 = clock();
 431   ... # Do something.
 432   my $clock1 = clock();
 433   my $clockd = $clock1 - $clock0;</pre>
 434 <p>
 435 </p>
 436 <hr />
 437 <h1><a name="c_api">C API</a></h1>
 438 <p>In addition to the perl API described above, a C API is available for
 439 extension writers.  The following C functions are available in the
 440 modglobal hash:</p>
 441 <pre>
 442   name             C prototype
 443   ---------------  ----------------------
 444   Time::NVtime     double (*)()
 445   Time::U2time     void (*)(pTHX_ UV ret[2])</pre>
 446 <p>Both functions return equivalent information (like <a href="#item_gettimeofday"><code>gettimeofday</code></a>)
 447 but with different representations.  The names <code>NVtime</code> and <code>U2time</code>
 448 were selected mainly because they are operating system independent.
 449 (<a href="#item_gettimeofday"><code>gettimeofday</code></a> is Unix-centric, though some platforms like Win32 and
 450 VMS have emulations for it.)</p>
 451 <p>Here is an example of using <code>NVtime</code> from C:</p>
 452 <pre>
 453   double (*myNVtime)(); /* Returns -1 on failure. */
 454   SV **svp = hv_fetch(PL_modglobal, &quot;Time::NVtime&quot;, 12, 0);
 455   if (!svp)         croak(&quot;Time::HiRes is required&quot;);
 456   if (!SvIOK(*svp)) croak(&quot;Time::NVtime isn't a function pointer&quot;);
 457   myNVtime = INT2PTR(double(*)(), SvIV(*svp));
 458   printf(&quot;The current time is: %f\n&quot;, (*myNVtime)());</pre>
 459 <p>
 460 </p>
 461 <hr />
 462 <h1><a name="diagnostics">DIAGNOSTICS</a></h1>
 463 <p>
 464 </p>
 465 <h2><a name="negative_time_not_invented_yet">negative time not invented yet</a></h2>
 466 <p>You tried to use a negative time argument.</p>
 467 <p>
 468 </p>
 469 <h2><a name="internal_error__useconds___0__unsigned_____signed_____">internal error: useconds &lt; 0 (unsigned ... signed ...)</a></h2>
 470 <p>Something went horribly wrong-- the number of microseconds that cannot
 471 become negative just became negative.  Maybe your compiler is broken?</p>
 472 <p>
 473 </p>
 474 <hr />
 475 <h1><a name="caveats">CAVEATS</a></h1>
 476 <p>Notice that the core <a href="#item_time"><code>time()</code></a> maybe rounding rather than truncating.
 477 What this means is that the core <a href="#item_time"><code>time()</code></a> may be reporting the time
 478 as one second later than <a href="#item_gettimeofday"><code>gettimeofday()</code></a> and <a href="#item_time"><code>Time::HiRes::time()</code></a>.</p>
 479 <p>Adjusting the system clock (either manually or by services like ntp)
 480 may cause problems, especially for long running programs that assume
 481 a monotonously increasing time (note that all platforms do not adjust
 482 time as gracefully as UNIX ntp does).  For example in Win32 (and derived
 483 platforms like Cygwin and MinGW) the Time::HiRes::time() may temporarily
 484 drift off from the system clock (and the original <a href="#item_time"><code>time())</code></a>  by up to 0.5
 485 seconds. Time::HiRes will notice this eventually and recalibrate.
 486 Note that since Time::HiRes 1.77 the <a href="#item_clock_gettime"><code>clock_gettime(CLOCK_MONOTONIC)</code></a>
 487 might help in this (in case your system supports CLOCK_MONOTONIC).</p>
 488 <p>
 489 </p>
 490 <hr />
 491 <h1><a name="see_also">SEE ALSO</a></h1>
 492 <p>Perl modules <a href="file://C|\msysgit\mingw\html/BSD/Resource.html">the BSD::Resource manpage</a>, <a href="file://C|\msysgit\mingw\html/Time/TAI64.html">the Time::TAI64 manpage</a>.</p>
 493 <p>Your system documentation for <a href="#item_clock_gettime"><code>clock_gettime</code></a>, <code>clock_settime</code>,
 494 <a href="#item_gettimeofday"><code>gettimeofday</code></a>, <a href="#item_getitimer"><code>getitimer</code></a>, <a href="#item_setitimer"><code>setitimer</code></a>, <a href="#item_ualarm"><code>ualarm</code></a>.</p>
 495 <p>
 496 </p>
 497 <hr />
 498 <h1><a name="authors">AUTHORS</a></h1>
 499 <p>D. Wegscheid &lt;<a href="mailto:wegscd@whirlpool.com">wegscd@whirlpool.com</a>&gt;
 500 R. Schertler &lt;<a href="mailto:roderick@argon.org">roderick@argon.org</a>&gt;
 501 J. Hietaniemi &lt;<a href="mailto:jhi@iki.fi">jhi@iki.fi</a>&gt;
 502 G. Aas &lt;<a href="mailto:gisle@aas.no">gisle@aas.no</a>&gt;</p>
 503 <p>
 504 </p>
 505 <hr />
 506 <h1><a name="copyright_and_license">COPYRIGHT AND LICENSE</a></h1>
 507 <p>Copyright (c) 1996-2002 Douglas E. Wegscheid.  All rights reserved.</p>
 508 <p>Copyright (c) 2002, 2003, 2004, 2005 Jarkko Hietaniemi.  All rights reserved.</p>
 509 <p>This program is free software; you can redistribute it and/or modify
 510 it under the same terms as Perl itself.</p>
 511 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 512 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 513 <big><strong><span class="block">&nbsp;Time::HiRes - High resolution alarm, sleep, gettimeofday, interval timers</span></strong></big>
 514 </td></tr>
 515 </table>
 516
 517 </body>
 518
 519 </html>