home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _fbf634fd8efa26bbeb48454960f4d8d8 < prev    next >
Text File  |  2000-03-23  |  10KB  |  247 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>Time::HiRes - High resolution ualarm, usleep, and gettimeofday</TITLE>
  5. <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> Time::HiRes - High resolution ualarm, usleep, and gettimeofday</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  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="#authors">AUTHORS</A></LI>
  28.     <LI><A HREF="#revision">REVISION</A></LI>
  29.     <LI><A HREF="#copyright">COPYRIGHT</A></LI>
  30. </UL>
  31. <!-- INDEX END -->
  32.  
  33. <HR>
  34. <P>
  35. <H1><A NAME="name">NAME</A></H1>
  36. <P>Time::HiRes - High resolution ualarm, usleep, and gettimeofday</P>
  37. <P>
  38. <HR>
  39. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  40. <UL>
  41. <LI>Linux</LI>
  42. <LI>Solaris</LI>
  43. <LI>Windows</LI>
  44. </UL>
  45. <HR>
  46. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  47. <PRE>
  48.   use Time::HiRes qw( usleep ualarm gettimeofday tv_interval );</PRE>
  49. <PRE>
  50.   usleep ($microseconds);</PRE>
  51. <PRE>
  52.   ualarm ($microseconds);
  53.   ualarm ($microseconds, $interval_microseconds);</PRE>
  54. <PRE>
  55.   $t0 = [gettimeofday];
  56.   ($seconds, $microseconds) = gettimeofday;</PRE>
  57. <PRE>
  58.   $elapsed = tv_interval ( $t0, [$seconds, $microseconds]);
  59.   $elapsed = tv_interval ( $t0, [gettimeofday]);
  60.   $elapsed = tv_interval ( $t0 );</PRE>
  61. <PRE>
  62.   use Time::HiRes qw ( time alarm sleep );
  63.   $now_fractions = time;
  64.   sleep ($floating_seconds);
  65.   alarm ($floating_seconds);
  66.   alarm ($floating_seconds, $floating_interval);</PRE>
  67. <P>
  68. <HR>
  69. <H1><A NAME="description">DESCRIPTION</A></H1>
  70. <P>The <CODE>Time::HiRes</CODE> module implements a Perl interface to the usleep, ualarm,
  71. and gettimeofday system calls. See the EXAMPLES section below and the test
  72. scripts for usage; see your system documentation for the description of
  73. the underlying gettimeofday, usleep, and ualarm calls.</P>
  74. <P>If your system lacks <A HREF="#item_gettimeofday"><CODE>gettimeofday(2)</CODE></A> you don't get <A HREF="#item_gettimeofday"><CODE>gettimeofday()</CODE></A> or the
  75. one-arg form of tv_interval().  If you don't have <A HREF="#item_usleep"><CODE>usleep(3)</CODE></A> or <A HREF="../../../lib/Pod/perlfunc.html#item_select"><CODE>select(2)</CODE></A>
  76. you don't get <A HREF="#item_usleep"><CODE>usleep()</CODE></A> or sleep().  If your system don't have <A HREF="#item_ualarm"><CODE>ualarm(3)</CODE></A>
  77. or <CODE>setitimer(2)</CODE> you don't
  78. get <A HREF="#item_ualarm"><CODE>ualarm()</CODE></A> or alarm().  If you try to import an unimplemented function
  79. in the <A HREF="../../../lib/Pod/perlfunc.html#item_use"><CODE>use</CODE></A> statement it will fail at compile time.</P>
  80. <P>The following functions can be imported from this module.  No
  81. functions are exported by default.</P>
  82. <DL>
  83. <DT><STRONG><A NAME="item_gettimeofday">gettimeofday ()</A></STRONG><BR>
  84. <DD>
  85. In array context it returns a 2 element array with the seconds and
  86. microseconds since the epoch.  In scalar context it returns floating
  87. seconds like Time::HiRes::time() (see below).
  88. <P></P>
  89. <DT><STRONG><A NAME="item_usleep">usleep ( $useconds )</A></STRONG><BR>
  90. <DD>
  91. Issues a usleep for the number of microseconds specified. See also 
  92. Time::HiRes::sleep() below.
  93. <P></P>
  94. <DT><STRONG><A NAME="item_ualarm">ualarm ( $useconds [, $interval_useconds ] )</A></STRONG><BR>
  95. <DD>
  96. Issues a ualarm call; interval_useconds is optional and will be 0 if 
  97. unspecified, resulting in alarm-like behaviour.
  98. <P></P>
  99. <DT><STRONG><A NAME="item_tv_interval">tv_interval ( $ref_to_gettimeofday [, $ref_to_later_gettimeofday] )</A></STRONG><BR>
  100. <DD>
  101. Returns the floating seconds between the two times, which should have been 
  102. returned by gettimeofday(). If the second argument is omitted, then the
  103. current time is used.
  104. <P></P>
  105. <DT><STRONG><A NAME="item_time">time ()</A></STRONG><BR>
  106. <DD>
  107. Returns a floating seconds since the epoch. This function can be imported,
  108. resulting in a nice drop-in replacement for the <A HREF="#item_time"><CODE>time</CODE></A> provided with perl,
  109. see the EXAMPLES below.
  110. <P></P>
  111. <DT><STRONG><A NAME="item_sleep">sleep ( $floating_seconds )</A></STRONG><BR>
  112. <DD>
  113. Converts $floating_seconds to microseconds and issues a usleep for the 
  114. result.  This function can be imported, resulting in a nice drop-in 
  115. replacement for the <A HREF="#item_sleep"><CODE>sleep</CODE></A> provided with perl, see the EXAMPLES below.
  116. <P></P>
  117. <DT><STRONG><A NAME="item_alarm">alarm ( $floating_seconds [, $interval_floating_seconds ] )</A></STRONG><BR>
  118. <DD>
  119. Converts $floating_seconds and $interval_floating_seconds and issues a
  120. ualarm for the results.  The $interval_floating_seconds argument is optional and will 
  121. be 0 if unspecified, resulting in alarm-like behaviour.  This function can 
  122. be imported, resulting in a nice drop-in 
  123. replacement for the <A HREF="#item_alarm"><CODE>alarm</CODE></A> provided with perl, see the EXAMPLES below.
  124. <P></P></DL>
  125. <P>
  126. <HR>
  127. <H1><A NAME="examples">EXAMPLES</A></H1>
  128. <PRE>
  129.   use Time::HiRes qw(usleep ualarm gettimeofday tv_interval);</PRE>
  130. <PRE>
  131.   $microseconds = 750_000;
  132.   usleep $microseconds;</PRE>
  133. <PRE>
  134.   # signal alarm in 2.5s & every .1s thereafter
  135.   ualarm 2_500_000, 100_000;</PRE>
  136. <PRE>
  137.   # get seconds and microseconds since the epoch
  138.   ($s, $usec) = gettimeofday;</PRE>
  139. <PRE>
  140.   # measure elapsed time 
  141.   # (could also do by subtracting 2 gettimeofday return values)
  142.   $t0 = [gettimeofday];
  143.   # do bunch of stuff here
  144.   $t1 = [gettimeofday];
  145.   # do more stuff here
  146.   $t0_t1 = tv_interval $t0, $t1;
  147. </PRE>
  148. <PRE>
  149.  
  150.   $elapsed = tv_interval ($t0, [gettimeofday]);
  151.   $elapsed = tv_interval ($t0); # equivalent code</PRE>
  152. <PRE>
  153.   #
  154.   # replacements for time, alarm and sleep that know about
  155.   # floating seconds
  156.   #
  157.   use Time::HiRes;
  158.   $now_fractions = Time::HiRes::time;
  159.   Time::HiRes::sleep (2.5);
  160.   Time::HiRes::alarm (10.6666666);
  161. </PRE>
  162. <PRE>
  163.  
  164.   use Time::HiRes qw ( time alarm sleep );
  165.   $now_fractions = time;
  166.   sleep (2.5);
  167.   alarm (10.6666666);</PRE>
  168. <P>
  169. <HR>
  170. <H1><A NAME="c api">C API</A></H1>
  171. <P>In addition to the perl API described above, a C API is available for
  172. extension writers.  The following C functions are available in the
  173. modglobal hash:</P>
  174. <PRE>
  175.   name             C prototype
  176.   ---------------  ----------------------
  177.   Time::NVtime     double (*)()
  178.   Time::U2time     void (*)(UV ret[2])</PRE>
  179. <P>Both functions return equivalent information (like <A HREF="#item_gettimeofday"><CODE>gettimeofday</CODE></A>)
  180. but with different representations.  The names <CODE>NVtime</CODE> and <CODE>U2time</CODE>
  181. were selected mainly because they are operating system independent.
  182. (<A HREF="#item_gettimeofday"><CODE>gettimeofday</CODE></A> is Un*x-centric.)</P>
  183. <P>Here is an example of using NVtime from C:</P>
  184. <PRE>
  185.   double (*myNVtime)();
  186.   SV **svp = hv_fetch(PL_modglobal, "Time::NVtime", 12, 0);
  187.   if (!svp)         croak("Time::HiRes is required");
  188.   if (!SvIOK(*svp)) croak("Time::NVtime isn't a function pointer");
  189.   myNVtime = (double(*)()) SvIV(*svp);
  190.   printf("The current time is: %f\n", (*myNVtime)());</PRE>
  191. <P>
  192. <HR>
  193. <H1><A NAME="authors">AUTHORS</A></H1>
  194. <P>D. Wegscheid <<A HREF="mailto:wegscd@whirlpool.com">wegscd@whirlpool.com</A>>
  195. R. Schertler <<A HREF="mailto:roderick@argon.org">roderick@argon.org</A>>
  196. J. Hietaniemi <<A HREF="mailto:jhi@iki.fi">jhi@iki.fi</A>>
  197. G. Aas <<A HREF="mailto:gisle@aas.no">gisle@aas.no</A>></P>
  198. <P>
  199. <HR>
  200. <H1><A NAME="revision">REVISION</A></H1>
  201. <P>$Id: HiRes.pm,v 1.20 1999/03/16 02:26:13 wegscd Exp $</P>
  202. <P>$Log: HiRes.pm,v $
  203. Revision 1.20  1999/03/16 02:26:13  wegscd
  204. Add documentation for NVTime and U2Time.</P>
  205. <P>Revision 1.19  1998/09/30 02:34:42  wegscd
  206. No changes, bump version.</P>
  207. <P>Revision 1.18  1998/07/07 02:41:35  wegscd
  208. No changes, bump version.</P>
  209. <P>Revision 1.17  1998/07/02 01:45:13  wegscd
  210. Bump version to 1.17</P>
  211. <P>Revision 1.16  1997/11/13 02:06:36  wegscd
  212. version bump to accomodate HiRes.xs fix.</P>
  213. <P>Revision 1.15  1997/11/11 02:17:59  wegscd
  214. POD editing, courtesy of Gisle Aas.</P>
  215. <P>Revision 1.14  1997/11/06 03:14:35  wegscd
  216. Update version # for Makefile.PL and HiRes.xs changes.</P>
  217. <P>Revision 1.13  1997/11/05 05:36:25  wegscd
  218. change version # for Makefile.pl and HiRes.xs changes.</P>
  219. <P>Revision 1.12  1997/10/13 20:55:33  wegscd
  220. Force a new version for Makefile.PL changes.</P>
  221. <P>Revision 1.11  1997/09/05 19:59:33  wegscd
  222. New version to bump version for README and Makefile.PL fixes.
  223. Fix bad RCS log.</P>
  224. <P>Revision 1.10  1997/05/23 01:11:38  wegscd
  225. Conditional compilation; EXPORT_FAIL fixes.</P>
  226. <P>Revision 1.2  1996/12/30 13:28:40  wegscd
  227. Update documentation for what to do when missing <A HREF="#item_ualarm"><CODE>ualarm()</CODE></A> and friends.</P>
  228. <P>Revision 1.1  1996/10/17 20:53:31  wegscd
  229. Fix =head1 being next to __END__ so pod2man works</P>
  230. <P>Revision 1.0  1996/09/03 18:25:15  wegscd
  231. Initial revision</P>
  232. <P>
  233. <HR>
  234. <H1><A NAME="copyright">COPYRIGHT</A></H1>
  235. <P>Copyright (c) 1996-1997 Douglas E. Wegscheid.
  236. All rights reserved. This program is free software; you can
  237. redistribute it and/or modify it under the same terms as Perl itself.</P>
  238. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  239. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  240. <STRONG><P CLASS=block> Time::HiRes - High resolution ualarm, usleep, and gettimeofday</P></STRONG>
  241. </TD></TR>
  242. </TABLE>
  243.  
  244. </BODY>
  245.  
  246. </HTML>
  247.