This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Integrate Time::Hires 1.20 from Douglas E. Wegscheid.
[perl5.git] / ext / Time / HiRes / HiRes.pm
CommitLineData
dcf686c9
JH
1package Time::HiRes;
2
3use strict;
4use vars qw($VERSION @ISA @EXPORT @EXPORT_OK @EXPORT_FAIL);
5
6require Exporter;
7require 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
16bootstrap Time::HiRes $VERSION;
17
18@EXPORT_FAIL = grep { ! defined &$_ } @EXPORT_OK;
19
20# Preloaded methods go here.
21
22sub 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
32sub export_fail {
33 my $self = shift;
34 @_;
35}
36
37# Autoload methods go after =cut, and are processed by the autosplit program.
38
391;
40__END__
41
42=head1 NAME
43
44Time::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
70The C<Time::HiRes> module implements a Perl interface to the usleep, ualarm,
71and gettimeofday system calls. See the EXAMPLES section below and the test
72scripts for usage; see your system documentation for the description of
73the underlying gettimeofday, usleep, and ualarm calls.
74
75If your system lacks gettimeofday(2) you don't get gettimeofday() or the
76one-arg form of tv_interval(). If you don't have usleep(3) or select(2)
77you don't get usleep() or sleep(). If your system don't have ualarm(3)
78or setitimer(2) you don't
79get ualarm() or alarm(). If you try to import an unimplemented function
80in the C<use> statement it will fail at compile time.
81
82The following functions can be imported from this module. No
83functions are exported by default.
84
85=over 4
86
87=item gettimeofday ()
88
89In array context it returns a 2 element array with the seconds and
90microseconds since the epoch. In scalar context it returns floating
91seconds like Time::HiRes::time() (see below).
92
93=item usleep ( $useconds )
94
95Issues a usleep for the number of microseconds specified. See also
96Time::HiRes::sleep() below.
97
98=item ualarm ( $useconds [, $interval_useconds ] )
99
100Issues a ualarm call; interval_useconds is optional and will be 0 if
101unspecified, resulting in alarm-like behaviour.
102
103=item tv_interval ( $ref_to_gettimeofday [, $ref_to_later_gettimeofday] )
104
105Returns the floating seconds between the two times, which should have been
106returned by gettimeofday(). If the second argument is omitted, then the
107current time is used.
108
109=item time ()
110
111Returns a floating seconds since the epoch. This function can be imported,
112resulting in a nice drop-in replacement for the C<time> provided with perl,
113see the EXAMPLES below.
114
115=item sleep ( $floating_seconds )
116
117Converts $floating_seconds to microseconds and issues a usleep for the
118result. This function can be imported, resulting in a nice drop-in
119replacement for the C<sleep> provided with perl, see the EXAMPLES below.
120
121=item alarm ( $floating_seconds [, $interval_floating_seconds ] )
122
123Converts $floating_seconds and $interval_floating_seconds and issues
124a ualarm for the results. The $interval_floating_seconds argument
125is optional and will be 0 if unspecified, resulting in alarm-like
126behaviour. This function can be imported, resulting in a nice drop-in
127replacement 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
171In addition to the perl API described above, a C API is available for
172extension writers. The following C functions are available in the
173modglobal hash:
174
175 name C prototype
176 --------------- ----------------------
177 Time::NVtime double (*)()
178 Time::U2time void (*)(UV ret[2])
179
180Both functions return equivalent information (like C<gettimeofday>)
181but with different representations. The names C<NVtime> and C<U2time>
182were selected mainly because they are operating system independent.
183(C<gettimeofday> is Un*x-centric.)
184
185Here 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
196D. Wegscheid <wegscd@whirlpool.com>
197R. Schertler <roderick@argon.org>
198J. Hietaniemi <jhi@iki.fi>
199G. 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 $
206Revision 1.20 1999/03/16 02:26:13 wegscd
207Add documentation for NVTime and U2Time.
208
209Revision 1.19 1998/09/30 02:34:42 wegscd
210No changes, bump version.
211
212Revision 1.18 1998/07/07 02:41:35 wegscd
213No changes, bump version.
214
215Revision 1.17 1998/07/02 01:45:13 wegscd
216Bump version to 1.17
217
218Revision 1.16 1997/11/13 02:06:36 wegscd
219version bump to accomodate HiRes.xs fix.
220
221Revision 1.15 1997/11/11 02:17:59 wegscd
222POD editing, courtesy of Gisle Aas.
223
224Revision 1.14 1997/11/06 03:14:35 wegscd
225Update version # for Makefile.PL and HiRes.xs changes.
226
227Revision 1.13 1997/11/05 05:36:25 wegscd
228change version # for Makefile.pl and HiRes.xs changes.
229
230Revision 1.12 1997/10/13 20:55:33 wegscd
231Force a new version for Makefile.PL changes.
232
233Revision 1.11 1997/09/05 19:59:33 wegscd
234New version to bump version for README and Makefile.PL fixes.
235Fix bad RCS log.
236
237Revision 1.10 1997/05/23 01:11:38 wegscd
238Conditional compilation; EXPORT_FAIL fixes.
239
240Revision 1.2 1996/12/30 13:28:40 wegscd
241Update documentation for what to do when missing ualarm() and friends.
242
243Revision 1.1 1996/10/17 20:53:31 wegscd
244Fix =head1 being next to __END__ so pod2man works
245
246Revision 1.0 1996/09/03 18:25:15 wegscd
247Initial revision
248
249=head1 COPYRIGHT
250
251Copyright (c) 1996-1997 Douglas E. Wegscheid.
252All rights reserved. This program is free software; you can
253redistribute it and/or modify it under the same terms as Perl itself.
254
255=cut