1IPC::Run::Timer(3) User Contributed Perl Documentation IPC::Run::Timer(3)
2
6 IPC::Run::Timer -- Timer channels for IPC::Run.
7
9 use IPC::Run qw( run timer timeout );
10 ## or IPC::Run::Timer ( timer timeout );
11 ## or IPC::Run::Timer ( :all );
12 ## A non-fatal timer:
14 $t = timer( 5 ); # or...
15 $t = IO::Run::Timer->new( 5 );
16 run $t, ...;
17 ## A timeout (which is a timer that dies on expiry):
19 $t = timeout( 5 ); # or...
20 $t = IO::Run::Timer->new( 5, exception => "harness timed out" );
21
23 This class and module allows timers and timeouts to be created for use
24 by IPC::Run. A timer simply expires when it's time is up. A timeout
25 is a timer that throws an exception when it expires.
26 Timeouts are usually a bit simpler to use than timers: they throw an
28 exception on expiration so you don't need to check them:
29 ## Give @cmd 10 seconds to get started, then 5 seconds to respond
31 my $t = timeout( 10 );
32 $h = start(
33 \@cmd, \$in, \$out,
34 $t,
35 );
36 pump $h until $out =~ /prompt/;
37 $in = "some stimulus";
39 $out = '';
40 $t->time( 5 )
41 pump $h until $out =~ /expected response/;
42 You do need to check timers:
44 ## Give @cmd 10 seconds to get started, then 5 seconds to respond
46 my $t = timer( 10 );
47 $h = start(
48 \@cmd, \$in, \$out,
49 $t,
50 );
51 pump $h until $t->is_expired || $out =~ /prompt/;
52 $in = "some stimulus";
54 $out = '';
55 $t->time( 5 )
56 pump $h until $out =~ /expected response/ || $t->is_expired;
57 Timers and timeouts that are reset get started by start() and pump().
59 Timers change state only in pump(). Since run() and finish() both call
60 pump(), they act like pump() with repect to timers.
61 Timers and timeouts have three states: reset, running, and expired.
63 Setting the timeout value resets the timer, as does calling the reset()
64 method. The start() method starts (or restarts) a timer with the most
65 recently set time value, no matter what state it's in.
66 Time values
68 All time values are in seconds. Times may be specified as integer or
69 floating point seconds, optionally preceded by puncuation-separated
70 days, hours, and minutes.\
71 Examples:
73 1 1 second
75 1.1 1.1 seconds
76 60 60 seconds
77 1:0 1 minute
78 1:1 1 minute, 1 second
79 1:90 2 minutes, 30 seconds
80 1:2:3:4.5 1 day, 2 hours, 3 minutes, 4.5 seconds
81 Absolute date/time strings are *not* accepted: year, month and day-of-
83 month parsing is not available (patches welcome :-).
84 Interval fudging
86 When calculating an end time from a start time and an interval,
87 IPC::Run::Timer instances add a little fudge factor. This is to ensure
88 that no time will expire before the interval is up.
89 First a little background. Time is sampled in discrete increments.
91 We'll call the exact moment that the reported time increments from one
92 interval to the next a tick, and the interval between ticks as the time
93 period. Here's a diagram of three ticks and the periods between them:
94 -0-0-0-0-0-0-0-0-0-0-1-1-1-1-1-1-1-1-1-1-2-...
96 ^ ^ ^
97 |<--- period 0 ---->|<--- period 1 ---->|
98 | | |
99 tick 0 tick 1 tick 2
100 To see why the fudge factor is necessary, consider what would happen
102 when a timer with an interval of 1 second is started right at the end
103 of period 0:
104 -0-0-0-0-0-0-0-0-0-0-1-1-1-1-1-1-1-1-1-1-2-...
106 ^ ^ ^ ^
107 | | | |
108 | | | |
109 tick 0 |tick 1 tick 2
110 |
111 start $t
112 Assuming that check() is called many times per period, then the timer
114 is likely to expire just after tick 1, since the time reported will
115 have lept from the value '0' to the value '1':
116 -0-0-0-0-0-0-0-0-0-0-1-1-1-1-1-1-1-1-1-1-2-...
118 ^ ^ ^ ^ ^
119 | | | | |
120 | | | | |
121 tick 0 |tick 1| tick 2
122 | |
123 start $t |
124 |
125 check $t
126 Adding a fudge of '1' in this example means that the timer is
128 guaranteed not to expire before tick 2.
129 The fudge is not added to an interval of '0'.
131 This means that intervals guarantee a minimum interval. Given that the
133 process running perl may be suspended for some period of time, or that
134 it gets busy doing something time-consuming, there are no other
135 guarantees on how long it will take a timer to expire.
136
138 INCOMPATIBLE CHANGE: Due to the awkwardness introduced by ripping
139 pseudohashes out of Perl, this class no longer uses the fields pragma.
140
142 timer
143 A constructor function (not method) of IPC::Run::Timer instances:
144 $t = timer( 5 );
146 $t = timer( 5, name => 'stall timer', debug => 1 );
147 $t = timer;
149 $t->interval( 5 );
150 run ..., $t;
152 run ..., $t = timer( 5 );
153 This convenience function is a shortened spelling of
155 IPC::Run::Timer->new( ... );
157 . It returns a timer in the reset state with a given interval.
159 If an exception is provided, it will be thrown when the timer
161 notices that it has expired (in check()). The name is for
162 debugging usage, if you plan on having multiple timers around. If
163 no name is provided, a name like "timer #1" will be provided.
164 timeout
166 A constructor function (not method) of IPC::Run::Timer instances:
167 $t = timeout( 5 );
169 $t = timeout( 5, exception => "kablooey" );
170 $t = timeout( 5, name => "stall", exception => "kablooey" );
171 $t = timeout;
173 $t->interval( 5 );
174 run ..., $t;
176 run ..., $t = timeout( 5 );
177 A This convenience function is a shortened spelling of
179 IPC::Run::Timer->new( exception => "IPC::Run: timeout ...", ... );
181 . It returns a timer in the reset state that will throw an
183 exception when it expires.
184 Takes the same parameters as "timer", any exception passed in
186 overrides the default exception.
187 new
189 IPC::Run::Timer->new() ;
190 IPC::Run::Timer->new( 5 ) ;
191 IPC::Run::Timer->new( 5, exception => 'kablooey' ) ;
192 Constructor. See "timer" for details.
194 check
196 check $t;
197 check $t, $now;
198 $t->check;
199 Checks to see if a timer has expired since the last check. Has no
201 effect on non-running timers. This will throw an exception if one
202 is defined.
203 IPC::Run::pump() calls this routine for any timers in the harness.
205 You may pass in a version of now, which is useful in case you have
207 it lying around or you want to check several timers with a
208 consistent concept of the current time.
209 Returns the time left before end_time or 0 if end_time is no longer
211 in the future or the timer is not running (unless, of course,
212 check() expire()s the timer and this results in an exception being
213 thrown).
214 Returns undef if the timer is not running on entry, 0 if check()
216 expires it, and the time left if it's left running.
217 debug
219 Sets/gets the current setting of the debugging flag for this timer.
220 This has no effect if debugging is not enabled for the current
221 harness.
222 end_time
224 $et = $t->end_time;
225 $et = end_time $t;
226 $t->end_time( time + 10 );
228 Returns the time when this timer will or did expire. Even if this
230 time is in the past, the timer may not be expired, since check()
231 may not have been called yet.
232 Note that this end_time is not start_time($t) + interval($t), since
234 some small extra amount of time is added to make sure that the
235 timer does not expire before interval() elapses. If this were not
236 so, then
237 Changing end_time() while a timer is running will set the
239 expiration time. Changing it while it is expired has no affect,
240 since reset()ing a timer always clears the end_time().
241 exception
243 $x = $t->exception;
244 $t->exception( $x );
245 $t->exception( undef );
246 Sets/gets the exception to throw, if any. 'undef' means that no
248 exception will be thrown. Exception does not need to be a scalar:
249 you may ask that references be thrown.
250 interval
252 $i = interval $t;
253 $i = $t->interval;
254 $t->interval( $i );
255 Sets the interval. Sets the end time based on the start_time() and
257 the interval (and a little fudge) if the timer is running.
258 expire
260 expire $t;
261 $t->expire;
262 Sets the state to expired (undef). Will throw an exception if one
264 is defined and the timer was not already expired. You can expire a
265 reset timer without starting it.
266 is_running
268 is_reset
269 is_expired
270 name
271 Sets/gets this timer's name. The name is only used for debugging
272 purposes so you can tell which freakin' timer is doing what.
273 reset
275 reset $t;
276 $t->reset;
277 Resets the timer to the non-running, non-expired state and clears
279 the end_time().
280 start
282 start $t;
283 $t->start;
284 start $t, $interval;
285 start $t, $interval, $now;
286 Starts or restarts a timer. This always sets the start_time. It
288 sets the end_time based on the interval if the timer is running or
289 if no end time has been set.
290 You may pass an optional interval or current time value.
292 Not passing a defined interval causes the previous interval setting
294 to be re-used unless the timer is reset and an end_time has been
295 set (an exception is thrown if no interval has been set).
296 Not passing a defined current time value causes the current time to
298 be used.
299 Passing a current time value is useful if you happen to have a time
301 value lying around or if you want to make sure that several timers
302 are started with the same concept of start time. You might even
303 need to lie to an IPC::Run::Timer, occasionally.
304 start_time
306 Sets/gets the start time, in seconds since the epoch. Setting this
307 manually is a bad idea, it's better to call "start"() at the
308 correct time.
309 state
311 $s = state $t;
312 $t->state( $s );
313 Get/Set the current state. Only use this if you really need to
315 transfer the state to/from some variable. Use "expire", "start",
316 "reset", "is_expired", "is_running", "is_reset".
317 Note: Setting the state to 'undef' to expire a timer will not
319 throw an exception.
320
322 use Time::HiRes; if it's present.
323 Add detection and parsing of [[[HH:]MM:]SS formatted times and
325 intervals.
326
328 Barrie Slaymaker <barries@slaysys.com>
329perl v5.12.2 2010-04-01 IPC::Run::Timer(3)