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
70 floating point seconds, optionally preceded by puncuation-separated
71 days, hours, and minutes.\
72 Examples:
74 1 1 second
76 1.1 1.1 seconds
77 60 60 seconds
78 1:0 1 minute
79 1:1 1 minute, 1 second
80 1:90 2 minutes, 30 seconds
81 1:2:3:4.5 1 day, 2 hours, 3 minutes, 4.5 seconds
82 Absolute date/time strings are *not* accepted: year, month and day-of-
84 month parsing is not available (patches welcome :-).
85 Interval fudging
87 When calculating an end time from a start time and an interval,
89 IPC::Run::Timer instances add a little fudge factor. This is to ensure
90 that no time will expire before the interval is up.
91 First a little background. Time is sampled in discrete increments.
93 We'll call the exact moment that the reported time increments from one
94 interval to the next a tick, and the interval between ticks as the time
95 period. Here's a diagram of three ticks and the periods between them:
96 -0-0-0-0-0-0-0-0-0-0-1-1-1-1-1-1-1-1-1-1-2-...
98 ^ ^ ^
99 ⎪<--- period 0 ---->⎪<--- period 1 ---->⎪
100 ⎪ ⎪ ⎪
101 tick 0 tick 1 tick 2
102 To see why the fudge factor is necessary, consider what would happen
104 when a timer with an interval of 1 second is started right at the end
105 of period 0:
106 -0-0-0-0-0-0-0-0-0-0-1-1-1-1-1-1-1-1-1-1-2-...
108 ^ ^ ^ ^
109 ⎪ ⎪ ⎪ ⎪
110 ⎪ ⎪ ⎪ ⎪
111 tick 0 ⎪tick 1 tick 2
112 ⎪
113 start $t
114 Assuming that check() is called many times per period, then the timer
116 is likely to expire just after tick 1, since the time reported will
117 have lept from the value '0' to the value '1':
118 -0-0-0-0-0-0-0-0-0-0-1-1-1-1-1-1-1-1-1-1-2-...
120 ^ ^ ^ ^ ^
121 ⎪ ⎪ ⎪ ⎪ ⎪
122 ⎪ ⎪ ⎪ ⎪ ⎪
123 tick 0 ⎪tick 1⎪ tick 2
124 ⎪ ⎪
125 start $t ⎪
126 ⎪
127 check $t
128 Adding a fudge of '1' in this example means that the timer is guaran‐
130 teed not to expire before tick 2.
131 The fudge is not added to an interval of '0'.
133 This means that intervals guarantee a minimum interval. Given that the
135 process running perl may be suspended for some period of time, or that
136 it gets busy doing something time-consuming, there are no other guaran‐
137 tees on how long it will take a timer to expire.
138
140 INCOMPATIBLE CHANGE: Due to the awkwardness introduced by ripping pseu‐
141 dohashes out of Perl, this class no longer uses the fields pragma.
142
144 timer
145 A constructor function (not method) of IPC::Run::Timer instances:
146 $t = timer( 5 ) ;
148 $t = timer( 5, name => 'stall timer', debug => 1 ) ;
149 $t = timer ;
151 $t->interval( 5 ) ;
152 run ..., $t ;
154 run ..., $t = timer( 5 ) ;
155 This convenience function is a shortened spelling of
157 IPC::Run::Timer->new( ... ) ;
159 . It returns a timer in the reset state with a given interval.
161 If an exception is provided, it will be thrown when the timer
163 notices that it has expired (in check()). The name is for debug‐
164 ging usage, if you plan on having multiple timers around. If no
165 name is provided, a name like "timer #1" will be provided.
166 timeout
168 A constructor function (not method) of IPC::Run::Timer instances:
169 $t = timeout( 5 ) ;
171 $t = timeout( 5, exception => "kablooey" ) ;
172 $t = timeout( 5, name => "stall", exception => "kablooey" ) ;
173 $t = timeout ;
175 $t->interval( 5 ) ;
176 run ..., $t ;
178 run ..., $t = timeout( 5 ) ;
179 A This convenience function is a shortened spelling of
181 IPC::Run::Timer->new( exception => "IPC::Run: timeout ...", ... ) ;
183 . It returns a timer in the reset state that will throw an excep‐
185 tion when it expires.
186 Takes the same parameters as "timer", any exception passed in over‐
188 rides the default exception.
189 new
191 IPC::Run::Timer->new() ;
192 IPC::Run::Timer->new( 5 ) ;
193 IPC::Run::Timer->new( 5, exception => 'kablooey' ) ;
194 Constructor. See "timer" for details.
196 check
198 check $t ;
199 check $t, $now ;
200 $t->check ;
201 Checks to see if a timer has expired since the last check. Has no
203 effect on non-running timers. This will throw an exception if one
204 is defined.
205 IPC::Run::pump() calls this routine for any timers in the harness.
207 You may pass in a version of now, which is useful in case you have
209 it lying around or you want to check several timers with a consis‐
210 tent concept of the current time.
211 Returns the time left before end_time or 0 if end_time is no longer
213 in the future or the timer is not running (unless, of course,
214 check() expire()s the timer and this results in an exception being
215 thrown).
216 Returns undef if the timer is not running on entry, 0 if check()
218 expires it, and the time left if it's left running.
219 debug
221 Sets/gets the current setting of the debugging flag for this timer.
222 This has no effect if debugging is not enabled for the current har‐
223 ness.
224 end_time
226 $et = $t->end_time ;
227 $et = end_time $t ;
228 $t->end_time( time + 10 ) ;
230 Returns the time when this timer will or did expire. Even if this
232 time is in the past, the timer may not be expired, since check()
233 may not have been called yet.
234 Note that this end_time is not start_time($t) + interval($t), since
236 some small extra amount of time is added to make sure that the
237 timer does not expire before interval() elapses. If this were not
238 so, then
239 Changing end_time() while a timer is running will set the expira‐
241 tion time. Changing it while it is expired has no affect, since
242 reset()ing a timer always clears the end_time().
243 exception
245 $x = $t->exception ;
246 $t->exception( $x ) ;
247 $t->exception( undef ) ;
248 Sets/gets the exception to throw, if any. 'undef' means that no
250 exception will be thrown. Exception does not need to be a scalar:
251 you may ask that references be thrown.
252 interval
254 $i = interval $t ;
255 $i = $t->interval ;
256 $t->interval( $i ) ;
257 Sets the interval. Sets the end time based on the start_time() and
259 the interval (and a little fudge) if the timer is running.
260 expire
262 expire $t ;
263 $t->expire ;
264 Sets the state to expired (undef). Will throw an exception if one
266 is defined and the timer was not already expired. You can expire a
267 reset timer without starting it.
268 is_running
270 is_reset
271 is_expired
272 name
273 Sets/gets this timer's name. The name is only used for debugging
274 purposes so you can tell which freakin' timer is doing what.
275 reset
277 reset $t ;
278 $t->reset ;
279 Resets the timer to the non-running, non-expired state and clears
281 the end_time().
282 start
284 start $t ;
285 $t->start ;
286 start $t, $interval ;
287 start $t, $interval, $now ;
288 Starts or restarts a timer. This always sets the start_time. It
290 sets the end_time based on the interval if the timer is running or
291 if no end time has been set.
292 You may pass an optional interval or current time value.
294 Not passing a defined interval causes the previous interval setting
296 to be re-used unless the timer is reset and an end_time has been
297 set (an exception is thrown if no interval has been set).
298 Not passing a defined current time value causes the current time to
300 be used.
301 Passing a current time value is useful if you happen to have a time
303 value lying around or if you want to make sure that several timers
304 are started with the same concept of start time. You might even
305 need to lie to an IPC::Run::Timer, occasionally.
306 start_time
308 Sets/gets the start time, in seconds since the epoch. Setting this
309 manually is a bad idea, it's better to call "start"() at the cor‐
310 rect time.
311 state
313 $s = state $t ;
314 $t->state( $s ) ;
315 Get/Set the current state. Only use this if you really need to
317 transfer the state to/from some variable. Use "expire", "start",
318 "reset", "is_expired", "is_running", "is_reset".
319 Note: Setting the state to 'undef' to expire a timer will not
321 throw an exception.
322
324 use Time::HiRes ; if it's present.
325 Add detection and parsing of [[[HH:]MM:]SS formatted times and inter‐
327 vals.
328
330 Barrie Slaymaker <barries@slaysys.com>
331perl v5.8.8 2006-05-10 IPC::Run::Timer(3)