1IPC::Run::Timer(3)    User Contributed Perl Documentation   IPC::Run::Timer(3)
2
3
4

NAME

6       IPC::Run::Timer -- Timer channels for IPC::Run.
7

SYNOPSIS

9          use IPC::Run qw( run  timer timeout );
10          ## or IPC::Run::Timer ( timer timeout );
11          ## or IPC::Run::Timer ( :all );
12
13          ## A non-fatal timer:
14          $t = timer( 5 ); # or...
15          $t = IO::Run::Timer->new( 5 );
16          run $t, ...;
17
18          ## 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

DESCRIPTION

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
27       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
30          ## 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
38          $in = "some stimulus";
39          $out = '';
40          $t->time( 5 )
41          pump $h until $out =~ /expected response/;
42
43       You do need to check timers:
44
45          ## 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
53          $in = "some stimulus";
54          $out = '';
55          $t->time( 5 )
56          pump $h until $out =~ /expected response/ || $t->is_expired;
57
58       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
62       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
67   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
72       Examples:
73
74          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
83       Absolute date/time strings are *not* accepted: year, month and day-of-
84       month parsing is not available (patches welcome :-).
85
86   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
91       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
96           -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
102       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
106           -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
114       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
118           -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
128       Adding a fudge of '1' in this example means that the timer is
129       guaranteed not to expire before tick 2.
130
131       The fudge is not added to an interval of '0'.
132
133       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

SUBCLASSING

139       INCOMPATIBLE CHANGE: Due to the awkwardness introduced by ripping
140       pseudohashes out of Perl, this class no longer uses the fields pragma.
141

FUNCTIONS & METHODS

143       timer
144           A constructor function (not method) of IPC::Run::Timer instances:
145
146              $t = timer( 5 );
147              $t = timer( 5, name => 'stall timer', debug => 1 );
148
149              $t = timer;
150              $t->interval( 5 );
151
152              run ..., $t;
153              run ..., $t = timer( 5 );
154
155           This convenience function is a shortened spelling of
156
157              IPC::Run::Timer->new( ... );
158
159           .  It returns a timer in the reset state with a given interval.
160
161           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
166       timeout
167           A constructor function (not method) of IPC::Run::Timer instances:
168
169              $t = timeout( 5 );
170              $t = timeout( 5, exception => "kablooey" );
171              $t = timeout( 5, name => "stall", exception => "kablooey" );
172
173              $t = timeout;
174              $t->interval( 5 );
175
176              run ..., $t;
177              run ..., $t = timeout( 5 );
178
179           A This convenience function is a shortened spelling of
180
181              IPC::Run::Timer->new( exception => "IPC::Run: timeout ...", ... );
182
183           .  It returns a timer in the reset state that will throw an
184           exception when it expires.
185
186           Takes the same parameters as "timer", any exception passed in
187           overrides the default exception.
188
189       new
190              IPC::Run::Timer->new()  ;
191              IPC::Run::Timer->new( 5 )  ;
192              IPC::Run::Timer->new( 5, exception => 'kablooey' )  ;
193
194           Constructor.  See "timer" for details.
195
196       check
197              check $t;
198              check $t, $now;
199              $t->check;
200
201           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
205           IPC::Run::pump() calls this routine for any timers in the harness.
206
207           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
211           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
216           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
219       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
224       end_time
225              $et = $t->end_time;
226              $et = end_time $t;
227
228              $t->end_time( time + 10 );
229
230           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
234           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
239           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
243       exception
244              $x = $t->exception;
245              $t->exception( $x );
246              $t->exception( undef );
247
248           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
252       interval
253              $i = interval $t;
254              $i = $t->interval;
255              $t->interval( $i );
256
257           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
260       expire
261              expire $t;
262              $t->expire;
263
264           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
268       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
275       reset
276              reset $t;
277              $t->reset;
278
279           Resets the timer to the non-running, non-expired state and clears
280           the end_time().
281
282       start
283              start $t;
284              $t->start;
285              start $t, $interval;
286              start $t, $interval, $now;
287
288           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
292           You may pass an optional interval or current time value.
293
294           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
298           Not passing a defined current time value causes the current time to
299           be used.
300
301           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
306       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
311       state
312              $s = state $t;
313              $t->state( $s );
314
315           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
319           Note:  Setting the state to 'undef' to expire a timer will not
320           throw an exception.
321

TODO

323       use Time::HiRes; if it's present.
324
325       Add detection and parsing of [[[HH:]MM:]SS formatted times and
326       intervals.
327

AUTHOR

329       Barrie Slaymaker <barries@slaysys.com>
330
331
332
333perl v5.34.0                      2022-01-21                IPC::Run::Timer(3)
Impressum