Commit | Line | Data |
dcf686c9 |
1 | package Time::HiRes; |
2 | |
3 | use strict; |
4 | use vars qw($VERSION @ISA @EXPORT @EXPORT_OK @EXPORT_FAIL); |
5 | |
6 | require Exporter; |
7 | require DynaLoader; |
8 | |
9 | @ISA = qw(Exporter DynaLoader); |
10 | |
11 | @EXPORT = qw( ); |
12 | @EXPORT_OK = qw (usleep sleep ualarm alarm gettimeofday time tv_interval); |
13 | |
14 | $VERSION = do{my@r=q$Revision: 1.20 $=~/\d+/g;sprintf '%02d.'.'%02d'x$#r,@r}; |
15 | |
16 | bootstrap Time::HiRes $VERSION; |
17 | |
18 | @EXPORT_FAIL = grep { ! defined &$_ } @EXPORT_OK; |
19 | |
20 | # Preloaded methods go here. |
21 | |
22 | sub tv_interval { |
23 | # probably could have been done in C |
24 | my ($a, $b) = @_; |
25 | $b = [gettimeofday()] unless defined($b); |
26 | (${$b}[0] - ${$a}[0]) + ((${$b}[1] - ${$a}[1]) / 1_000_000); |
27 | } |
28 | |
29 | # I'm only supplying this because the version of it in 5.003's Export.pm |
30 | # is buggy (it doesn't shift off the class name). |
31 | |
32 | sub export_fail { |
33 | my $self = shift; |
34 | @_; |
35 | } |
36 | |
37 | # Autoload methods go after =cut, and are processed by the autosplit program. |
38 | |
39 | 1; |
40 | __END__ |
41 | |
42 | =head1 NAME |
43 | |
44 | Time::HiRes - High resolution ualarm, usleep, and gettimeofday |
45 | |
46 | =head1 SYNOPSIS |
47 | |
48 | use Time::HiRes qw( usleep ualarm gettimeofday tv_interval ); |
49 | |
50 | usleep ($microseconds); |
51 | |
52 | ualarm ($microseconds); |
53 | ualarm ($microseconds, $interval_microseconds); |
54 | |
55 | $t0 = [gettimeofday]; |
56 | ($seconds, $microseconds) = gettimeofday; |
57 | |
58 | $elapsed = tv_interval ( $t0, [$seconds, $microseconds]); |
59 | $elapsed = tv_interval ( $t0, [gettimeofday]); |
60 | $elapsed = tv_interval ( $t0 ); |
61 | |
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); |
67 | |
68 | =head1 DESCRIPTION |
69 | |
70 | The C<Time::HiRes> 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. |
74 | |
75 | If your system lacks gettimeofday(2) you don't get gettimeofday() or the |
76 | one-arg form of tv_interval(). If you don't have usleep(3) or select(2) |
77 | you don't get usleep() or sleep(). If your system don't have ualarm(3) |
78 | or setitimer(2) you don't |
79 | get ualarm() or alarm(). If you try to import an unimplemented function |
80 | in the C<use> statement it will fail at compile time. |
81 | |
82 | The following functions can be imported from this module. No |
83 | functions are exported by default. |
84 | |
85 | =over 4 |
86 | |
87 | =item gettimeofday () |
88 | |
89 | In array context it returns a 2 element array with the seconds and |
90 | microseconds since the epoch. In scalar context it returns floating |
91 | seconds like Time::HiRes::time() (see below). |
92 | |
93 | =item usleep ( $useconds ) |
94 | |
95 | Issues a usleep for the number of microseconds specified. See also |
96 | Time::HiRes::sleep() below. |
97 | |
98 | =item ualarm ( $useconds [, $interval_useconds ] ) |
99 | |
100 | Issues a ualarm call; interval_useconds is optional and will be 0 if |
101 | unspecified, resulting in alarm-like behaviour. |
102 | |
103 | =item tv_interval ( $ref_to_gettimeofday [, $ref_to_later_gettimeofday] ) |
104 | |
105 | Returns the floating seconds between the two times, which should have been |
106 | returned by gettimeofday(). If the second argument is omitted, then the |
107 | current time is used. |
108 | |
109 | =item time () |
110 | |
111 | Returns a floating seconds since the epoch. This function can be imported, |
112 | resulting in a nice drop-in replacement for the C<time> provided with perl, |
113 | see the EXAMPLES below. |
114 | |
115 | =item sleep ( $floating_seconds ) |
116 | |
117 | Converts $floating_seconds to microseconds and issues a usleep for the |
118 | result. This function can be imported, resulting in a nice drop-in |
119 | replacement for the C<sleep> provided with perl, see the EXAMPLES below. |
120 | |
121 | =item alarm ( $floating_seconds [, $interval_floating_seconds ] ) |
122 | |
123 | Converts $floating_seconds and $interval_floating_seconds and issues |
124 | a ualarm for the results. The $interval_floating_seconds argument |
125 | is optional and will be 0 if unspecified, resulting in alarm-like |
126 | behaviour. This function can be imported, resulting in a nice drop-in |
127 | replacement for the C<alarm> provided with perl, see the EXAMPLES below. |
128 | |
129 | =back |
130 | |
131 | =head1 EXAMPLES |
132 | |
133 | use Time::HiRes qw(usleep ualarm gettimeofday tv_interval); |
134 | |
135 | $microseconds = 750_000; |
136 | usleep $microseconds; |
137 | |
138 | # signal alarm in 2.5s & every .1s thereafter |
139 | ualarm 2_500_000, 100_000; |
140 | |
141 | # get seconds and microseconds since the epoch |
142 | ($s, $usec) = gettimeofday; |
143 | |
144 | # measure elapsed time |
145 | # (could also do by subtracting 2 gettimeofday return values) |
146 | $t0 = [gettimeofday]; |
147 | # do bunch of stuff here |
148 | $t1 = [gettimeofday]; |
149 | # do more stuff here |
150 | $t0_t1 = tv_interval $t0, $t1; |
151 | |
152 | $elapsed = tv_interval ($t0, [gettimeofday]); |
153 | $elapsed = tv_interval ($t0); # equivalent code |
154 | |
155 | # |
156 | # replacements for time, alarm and sleep that know about |
157 | # floating seconds |
158 | # |
159 | use Time::HiRes; |
160 | $now_fractions = Time::HiRes::time; |
161 | Time::HiRes::sleep (2.5); |
162 | Time::HiRes::alarm (10.6666666); |
163 | |
164 | use Time::HiRes qw ( time alarm sleep ); |
165 | $now_fractions = time; |
166 | sleep (2.5); |
167 | alarm (10.6666666); |
168 | |
169 | =head1 C API |
170 | |
171 | 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: |
174 | |
175 | name C prototype |
176 | --------------- ---------------------- |
177 | Time::NVtime double (*)() |
178 | Time::U2time void (*)(UV ret[2]) |
179 | |
180 | Both functions return equivalent information (like C<gettimeofday>) |
181 | but with different representations. The names C<NVtime> and C<U2time> |
182 | were selected mainly because they are operating system independent. |
183 | (C<gettimeofday> is Un*x-centric.) |
184 | |
185 | Here is an example of using NVtime from C: |
186 | |
187 | double (*myNVtime)(); |
188 | SV **svp = hv_fetch(PL_modglobal, "Time::NVtime", 12, 0); |
189 | if (!svp) croak("Time::HiRes is required"); |
190 | if (!SvIOK(*svp)) croak("Time::NVtime isn't a function pointer"); |
191 | myNVtime = (double(*)()) SvIV(*svp); |
192 | printf("The current time is: %f\n", (*myNVtime)()); |
193 | |
194 | =head1 AUTHORS |
195 | |
196 | D. Wegscheid <wegscd@whirlpool.com> |
197 | R. Schertler <roderick@argon.org> |
198 | J. Hietaniemi <jhi@iki.fi> |
199 | G. Aas <gisle@aas.no> |
200 | |
201 | =head1 REVISION |
202 | |
203 | $Id: HiRes.pm,v 1.20 1999/03/16 02:26:13 wegscd Exp $ |
204 | |
205 | $Log: HiRes.pm,v $ |
206 | Revision 1.20 1999/03/16 02:26:13 wegscd |
207 | Add documentation for NVTime and U2Time. |
208 | |
209 | Revision 1.19 1998/09/30 02:34:42 wegscd |
210 | No changes, bump version. |
211 | |
212 | Revision 1.18 1998/07/07 02:41:35 wegscd |
213 | No changes, bump version. |
214 | |
215 | Revision 1.17 1998/07/02 01:45:13 wegscd |
216 | Bump version to 1.17 |
217 | |
218 | Revision 1.16 1997/11/13 02:06:36 wegscd |
219 | version bump to accomodate HiRes.xs fix. |
220 | |
221 | Revision 1.15 1997/11/11 02:17:59 wegscd |
222 | POD editing, courtesy of Gisle Aas. |
223 | |
224 | Revision 1.14 1997/11/06 03:14:35 wegscd |
225 | Update version # for Makefile.PL and HiRes.xs changes. |
226 | |
227 | Revision 1.13 1997/11/05 05:36:25 wegscd |
228 | change version # for Makefile.pl and HiRes.xs changes. |
229 | |
230 | Revision 1.12 1997/10/13 20:55:33 wegscd |
231 | Force a new version for Makefile.PL changes. |
232 | |
233 | Revision 1.11 1997/09/05 19:59:33 wegscd |
234 | New version to bump version for README and Makefile.PL fixes. |
235 | Fix bad RCS log. |
236 | |
237 | Revision 1.10 1997/05/23 01:11:38 wegscd |
238 | Conditional compilation; EXPORT_FAIL fixes. |
239 | |
240 | Revision 1.2 1996/12/30 13:28:40 wegscd |
241 | Update documentation for what to do when missing ualarm() and friends. |
242 | |
243 | Revision 1.1 1996/10/17 20:53:31 wegscd |
244 | Fix =head1 being next to __END__ so pod2man works |
245 | |
246 | Revision 1.0 1996/09/03 18:25:15 wegscd |
247 | Initial revision |
248 | |
249 | =head1 COPYRIGHT |
250 | |
251 | Copyright (c) 1996-1997 Douglas E. Wegscheid. |
252 | All rights reserved. This program is free software; you can |
253 | redistribute it and/or modify it under the same terms as Perl itself. |
254 | |
255 | =cut |