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 respect 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 any kind of perl number,
69 e.g. as integer or floating point seconds, optionally preceded by
70 punctuation-separated 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 'inf' the infinity perl special number (the timer never finishes)
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,
88 IPC::Run::Timer instances add a little fudge factor. This is to ensure
89 that no time will expire before the interval is up.
90 First a little background. Time is sampled in discrete increments.
92 We'll call the exact moment that the reported time increments from one
93 interval to the next a tick, and the interval between ticks as the time
94 period. Here's a diagram of three ticks and the periods between them:
95 -0-0-0-0-0-0-0-0-0-0-1-1-1-1-1-1-1-1-1-1-2-...
97 ^ ^ ^
98 |<--- period 0 ---->|<--- period 1 ---->|
99 | | |
100 tick 0 tick 1 tick 2
101 To see why the fudge factor is necessary, consider what would happen
103 when a timer with an interval of 1 second is started right at the end
104 of period 0:
105 -0-0-0-0-0-0-0-0-0-0-1-1-1-1-1-1-1-1-1-1-2-...
107 ^ ^ ^ ^
108 | | | |
109 | | | |
110 tick 0 |tick 1 tick 2
111 |
112 start $t
113 Assuming that check() is called many times per period, then the timer
115 is likely to expire just after tick 1, since the time reported will
116 have lept from the value '0' to the value '1':
117 -0-0-0-0-0-0-0-0-0-0-1-1-1-1-1-1-1-1-1-1-2-...
119 ^ ^ ^ ^ ^
120 | | | | |
121 | | | | |
122 tick 0 |tick 1| tick 2
123 | |
124 start $t |
125 |
126 check $t
127 Adding a fudge of '1' in this example means that the timer is
129 guaranteed not to expire before tick 2.
130 The fudge is not added to an interval of '0'.
132 This means that intervals guarantee a minimum interval. Given that the
134 process running perl may be suspended for some period of time, or that
135 it gets busy doing something time-consuming, there are no other
136 guarantees on how long it will take a timer to expire.
137
139 INCOMPATIBLE CHANGE: Due to the awkwardness introduced by ripping
140 pseudohashes out of Perl, this class no longer uses the fields pragma.
141
143 timer
144 A constructor function (not method) of IPC::Run::Timer instances:
145 $t = timer( 5 );
147 $t = timer( 5, name => 'stall timer', debug => 1 );
148 $t = timer;
150 $t->interval( 5 );
151 run ..., $t;
153 run ..., $t = timer( 5 );
154 This convenience function is a shortened spelling of
156 IPC::Run::Timer->new( ... );
158 . It returns a timer in the reset state with a given interval.
160 If an exception is provided, it will be thrown when the timer
162 notices that it has expired (in check()). The name is for
163 debugging usage, if you plan on having multiple timers around. If
164 no name is provided, a name like "timer #1" will be provided.
165 timeout
167 A constructor function (not method) of IPC::Run::Timer instances:
168 $t = timeout( 5 );
170 $t = timeout( 5, exception => "kablooey" );
171 $t = timeout( 5, name => "stall", exception => "kablooey" );
172 $t = timeout;
174 $t->interval( 5 );
175 run ..., $t;
177 run ..., $t = timeout( 5 );
178 A This convenience function is a shortened spelling of
180 IPC::Run::Timer->new( exception => "IPC::Run: timeout ...", ... );
182 . It returns a timer in the reset state that will throw an
184 exception when it expires.
185 Takes the same parameters as "timer", any exception passed in
187 overrides the default exception.
188 new
190 IPC::Run::Timer->new() ;
191 IPC::Run::Timer->new( 5 ) ;
192 IPC::Run::Timer->new( 5, exception => 'kablooey' ) ;
193 Constructor. See "timer" for details.
195 check
197 check $t;
198 check $t, $now;
199 $t->check;
200 Checks to see if a timer has expired since the last check. Has no
202 effect on non-running timers. This will throw an exception if one
203 is defined.
204 IPC::Run::pump() calls this routine for any timers in the harness.
206 You may pass in a version of now, which is useful in case you have
208 it lying around or you want to check several timers with a
209 consistent concept of the current time.
210 Returns the time left before end_time or 0 if end_time is no longer
212 in the future or the timer is not running (unless, of course,
213 check() expire()s the timer and this results in an exception being
214 thrown).
215 Returns undef if the timer is not running on entry, 0 if check()
217 expires it, and the time left if it's left running.
218 debug
220 Sets/gets the current setting of the debugging flag for this timer.
221 This has no effect if debugging is not enabled for the current
222 harness.
223 end_time
225 $et = $t->end_time;
226 $et = end_time $t;
227 $t->end_time( time + 10 );
229 Returns the time when this timer will or did expire. Even if this
231 time is in the past, the timer may not be expired, since check()
232 may not have been called yet.
233 Note that this end_time is not start_time($t) + interval($t), since
235 some small extra amount of time is added to make sure that the
236 timer does not expire before interval() elapses. If this were not
237 so, then
238 Changing end_time() while a timer is running will set the
240 expiration time. Changing it while it is expired has no affect,
241 since reset()ing a timer always clears the end_time().
242 exception
244 $x = $t->exception;
245 $t->exception( $x );
246 $t->exception( undef );
247 Sets/gets the exception to throw, if any. 'undef' means that no
249 exception will be thrown. Exception does not need to be a scalar:
250 you may ask that references be thrown.
251 interval
253 $i = interval $t;
254 $i = $t->interval;
255 $t->interval( $i );
256 Sets the interval. Sets the end time based on the start_time() and
258 the interval (and a little fudge) if the timer is running.
259 expire
261 expire $t;
262 $t->expire;
263 Sets the state to expired (undef). Will throw an exception if one
265 is defined and the timer was not already expired. You can expire a
266 reset timer without starting it.
267 is_running
269 is_reset
270 is_expired
271 name
272 Sets/gets this timer's name. The name is only used for debugging
273 purposes so you can tell which freakin' timer is doing what.
274 reset
276 reset $t;
277 $t->reset;
278 Resets the timer to the non-running, non-expired state and clears
280 the end_time().
281 start
283 start $t;
284 $t->start;
285 start $t, $interval;
286 start $t, $interval, $now;
287 Starts or restarts a timer. This always sets the start_time. It
289 sets the end_time based on the interval if the timer is running or
290 if no end time has been set.
291 You may pass an optional interval or current time value.
293 Not passing a defined interval causes the previous interval setting
295 to be re-used unless the timer is reset and an end_time has been
296 set (an exception is thrown if no interval has been set).
297 Not passing a defined current time value causes the current time to
299 be used.
300 Passing a current time value is useful if you happen to have a time
302 value lying around or if you want to make sure that several timers
303 are started with the same concept of start time. You might even
304 need to lie to an IPC::Run::Timer, occasionally.
305 start_time
307 Sets/gets the start time, in seconds since the epoch. Setting this
308 manually is a bad idea, it's better to call "start"() at the
309 correct time.
310 state
312 $s = state $t;
313 $t->state( $s );
314 Get/Set the current state. Only use this if you really need to
316 transfer the state to/from some variable. Use "expire", "start",
317 "reset", "is_expired", "is_running", "is_reset".
318 Note: Setting the state to 'undef' to expire a timer will not
320 throw an exception.
321
323 use Time::HiRes; if it's present.
324 Add detection and parsing of [[[HH:]MM:]SS formatted times and
326 intervals.
327
329 Barrie Slaymaker <barries@slaysys.com>
330perl v5.36.0 2023-01-20 IPC::Run::Timer(3)