.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "IPC::Run::Timer 3"
.TH IPC::Run::Timer 3 "2014-12-11" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
IPC::Run::Timer \-\- Timer channels for IPC::Run.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&   use IPC::Run qw( run  timer timeout );
\&   ## or IPC::Run::Timer ( timer timeout );
\&   ## or IPC::Run::Timer ( :all );
\&
\&   ## A non\-fatal timer:
\&   $t = timer( 5 ); # or...
\&   $t = IO::Run::Timer\->new( 5 );
\&   run $t, ...;
\&
\&   ## A timeout (which is a timer that dies on expiry):
\&   $t = timeout( 5 ); # or...
\&   $t = IO::Run::Timer\->new( 5, exception => "harness timed out" );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class and module allows timers and timeouts to be created for use
by IPC::Run.  A timer simply expires when it's time is up.  A timeout
is a timer that throws an exception when it expires.
.PP
Timeouts are usually a bit simpler to use  than timers: they throw an
exception on expiration so you don't need to check them:
.PP
.Vb 7
\&   ## Give @cmd 10 seconds to get started, then 5 seconds to respond
\&   my $t = timeout( 10 );
\&   $h = start(
\&      \e@cmd, \e$in, \e$out,
\&      $t,
\&   );
\&   pump $h until $out =~ /prompt/;
\&
\&   $in = "some stimulus";
\&   $out = \*(Aq\*(Aq;
\&   $t\->time( 5 )
\&   pump $h until $out =~ /expected response/;
.Ve
.PP
You do need to check timers:
.PP
.Vb 7
\&   ## Give @cmd 10 seconds to get started, then 5 seconds to respond
\&   my $t = timer( 10 );
\&   $h = start(
\&      \e@cmd, \e$in, \e$out,
\&      $t,
\&   );
\&   pump $h until $t\->is_expired || $out =~ /prompt/;
\&
\&   $in = "some stimulus";
\&   $out = \*(Aq\*(Aq;
\&   $t\->time( 5 )
\&   pump $h until $out =~ /expected response/ || $t\->is_expired;
.Ve
.PP
Timers and timeouts that are reset get started by \fIstart()\fR and
\&\fIpump()\fR.  Timers change state only in \fIpump()\fR.  Since \fIrun()\fR and
\&\fIfinish()\fR both call \fIpump()\fR, they act like \fIpump()\fR with respect to
timers.
.PP
Timers and timeouts have three states: reset, running, and expired.
Setting the timeout value resets the timer, as does calling
the \fIreset()\fR method.  The \fIstart()\fR method starts (or restarts) a
timer with the most recently set time value, no matter what state
it's in.
.SS "Time values"
.IX Subsection "Time values"
All time values are in seconds.  Times may be specified as integer or
floating point seconds, optionally preceded by puncuation-separated
days, hours, and minutes.\e
.PP
Examples:
.PP
.Vb 7
\&   1           1 second
\&   1.1         1.1 seconds
\&   60          60 seconds
\&   1:0         1 minute
\&   1:1         1 minute, 1 second
\&   1:90        2 minutes, 30 seconds
\&   1:2:3:4.5   1 day, 2 hours, 3 minutes, 4.5 seconds
.Ve
.PP
Absolute date/time strings are *not* accepted: year, month and
day-of-month parsing is not available (patches welcome :\-).
.SS "Interval fudging"
.IX Subsection "Interval fudging"
When calculating an end time from a start time and an interval, IPC::Run::Timer
instances add a little fudge factor.  This is to ensure that no time will
expire before the interval is up.
.PP
First a little background.  Time is sampled in discrete increments.  We'll
call the
exact moment that the reported time increments from one interval to the
next a tick, and the interval between ticks as the time period.  Here's
a diagram of three ticks and the periods between them:
.PP
.Vb 5
\&    \-0\-0\-0\-0\-0\-0\-0\-0\-0\-0\-1\-1\-1\-1\-1\-1\-1\-1\-1\-1\-2\-...
\&    ^                   ^                   ^
\&    |<\-\-\- period 0 \-\-\-\->|<\-\-\- period 1 \-\-\-\->|
\&    |                   |                   |
\&  tick 0              tick 1              tick 2
.Ve
.PP
To see why the fudge factor is necessary, consider what would happen
when a timer with an interval of 1 second is started right at the end of
period 0:
.PP
.Vb 7
\&    \-0\-0\-0\-0\-0\-0\-0\-0\-0\-0\-1\-1\-1\-1\-1\-1\-1\-1\-1\-1\-2\-...
\&    ^                ^  ^                   ^
\&    |                |  |                   |
\&    |                |  |                   |
\&  tick 0             |tick 1              tick 2
\&                     |
\&                 start $t
.Ve
.PP
Assuming that \fIcheck()\fR is called many times per period, then the timer
is likely to expire just after tick 1, since the time reported will have
lept from the value '0' to the value '1':
.PP
.Vb 9
\&    \-0\-0\-0\-0\-0\-0\-0\-0\-0\-0\-1\-1\-1\-1\-1\-1\-1\-1\-1\-1\-2\-...
\&    ^                ^  ^   ^               ^
\&    |                |  |   |               |
\&    |                |  |   |               |
\&  tick 0             |tick 1|             tick 2
\&                     |      |
\&                 start $t   |
\&                            |
\&                        check $t
.Ve
.PP
Adding a fudge of '1' in this example means that the timer is guaranteed
not to expire before tick 2.
.PP
The fudge is not added to an interval of '0'.
.PP
This means that intervals guarantee a minimum interval.  Given that
the process running perl may be suspended for some period of time, or that
it gets busy doing something time-consuming, there are no other guarantees on
how long it will take a timer to expire.
.SH "SUBCLASSING"
.IX Header "SUBCLASSING"
\&\s-1INCOMPATIBLE CHANGE:\s0 Due to the awkwardness introduced by ripping
pseudohashes out of Perl, this class \fIno longer\fR uses the fields
pragma.
.SH "FUNCTIONS & METHODS"
.IX Header "FUNCTIONS & METHODS"
.IP "timer" 4
.IX Item "timer"
A constructor function (not method) of IPC::Run::Timer instances:
.Sp
.Vb 2
\&   $t = timer( 5 );
\&   $t = timer( 5, name => \*(Aqstall timer\*(Aq, debug => 1 );
\&
\&   $t = timer;
\&   $t\->interval( 5 );
\&
\&   run ..., $t;
\&   run ..., $t = timer( 5 );
.Ve
.Sp
This convenience function is a shortened spelling of
.Sp
.Vb 1
\&   IPC::Run::Timer\->new( ... );
.Ve
.Sp
\&.  It returns a timer in the reset state with a given interval.
.Sp
If an exception is provided, it will be thrown when the timer notices that
it has expired (in \fIcheck()\fR).  The name is for debugging usage, if you plan on
having multiple timers around.  If no name is provided, a name like \*(L"timer #1\*(R"
will be provided.
.IP "timeout" 4
.IX Item "timeout"
A constructor function (not method) of IPC::Run::Timer instances:
.Sp
.Vb 3
\&   $t = timeout( 5 );
\&   $t = timeout( 5, exception => "kablooey" );
\&   $t = timeout( 5, name => "stall", exception => "kablooey" );
\&
\&   $t = timeout;
\&   $t\->interval( 5 );
\&
\&   run ..., $t;
\&   run ..., $t = timeout( 5 );
.Ve
.Sp
A This convenience function is a shortened spelling of
.Sp
.Vb 1
\&   IPC::Run::Timer\->new( exception => "IPC::Run: timeout ...", ... );
.Ve
.Sp
\&.  It returns a timer in the reset state that will throw an
exception when it expires.
.Sp
Takes the same parameters as \*(L"timer\*(R", any exception passed in overrides
the default exception.
.IP "new" 4
.IX Item "new"
.Vb 3
\&   IPC::Run::Timer\->new()  ;
\&   IPC::Run::Timer\->new( 5 )  ;
\&   IPC::Run::Timer\->new( 5, exception => \*(Aqkablooey\*(Aq )  ;
.Ve
.Sp
Constructor.  See \*(L"timer\*(R" for details.
.IP "check" 4
.IX Item "check"
.Vb 3
\&   check $t;
\&   check $t, $now;
\&   $t\->check;
.Ve
.Sp
Checks to see if a timer has expired since the last check.  Has no effect
on non-running timers.  This will throw an exception if one is defined.
.Sp
\&\fIIPC::Run::pump()\fR calls this routine for any timers in the harness.
.Sp
You may pass in a version of now, which is useful in case you have
it lying around or you want to check several timers with a consistent
concept of the current time.
.Sp
Returns the time left before end_time or 0 if end_time is no longer
in the future or the timer is not running
(unless, of course, \fIcheck()\fR \fIexpire()\fRs the timer and this
results in an exception being thrown).
.Sp
Returns undef if the timer is not running on entry, 0 if \fIcheck()\fR expires it,
and the time left if it's left running.
.IP "debug" 4
.IX Item "debug"
Sets/gets the current setting of the debugging flag for this timer.  This
has no effect if debugging is not enabled for the current harness.
.IP "end_time" 4
.IX Item "end_time"
.Vb 2
\&   $et = $t\->end_time;
\&   $et = end_time $t;
\&
\&   $t\->end_time( time + 10 );
.Ve
.Sp
Returns the time when this timer will or did expire.  Even if this time is
in the past, the timer may not be expired, since \fIcheck()\fR may not have been
called yet.
.Sp
Note that this end_time is not start_time($t) + interval($t), since some
small extra amount of time is added to make sure that the timer does not
expire before \fIinterval()\fR elapses.  If this were not so, then
.Sp
Changing \fIend_time()\fR while a timer is running will set the expiration time.
Changing it while it is expired has no affect, since \fIreset()\fRing a timer always
clears the \fIend_time()\fR.
.IP "exception" 4
.IX Item "exception"
.Vb 3
\&   $x = $t\->exception;
\&   $t\->exception( $x );
\&   $t\->exception( undef );
.Ve
.Sp
Sets/gets the exception to throw, if any.  'undef' means that no
exception will be thrown.  Exception does not need to be a scalar: you 
may ask that references be thrown.
.IP "interval" 4
.IX Item "interval"
.Vb 3
\&   $i = interval $t;
\&   $i = $t\->interval;
\&   $t\->interval( $i );
.Ve
.Sp
Sets the interval.  Sets the end time based on the \fIstart_time()\fR and the
interval (and a little fudge) if the timer is running.
.IP "expire" 4
.IX Item "expire"
.Vb 2
\&   expire $t;
\&   $t\->expire;
.Ve
.Sp
Sets the state to expired (undef).
Will throw an exception if one
is defined and the timer was not already expired.  You can expire a
reset timer without starting it.
.IP "is_running" 4
.IX Item "is_running"
.PD 0
.IP "is_reset" 4
.IX Item "is_reset"
.IP "is_expired" 4
.IX Item "is_expired"
.IP "name" 4
.IX Item "name"
.PD
Sets/gets this timer's name.  The name is only used for debugging
purposes so you can tell which freakin' timer is doing what.
.IP "reset" 4
.IX Item "reset"
.Vb 2
\&   reset $t;
\&   $t\->reset;
.Ve
.Sp
Resets the timer to the non-running, non-expired state and clears
the \fIend_time()\fR.
.IP "start" 4
.IX Item "start"
.Vb 4
\&   start $t;
\&   $t\->start;
\&   start $t, $interval;
\&   start $t, $interval, $now;
.Ve
.Sp
Starts or restarts a timer.  This always sets the start_time.  It sets the
end_time based on the interval if the timer is running or if no end time
has been set.
.Sp
You may pass an optional interval or current time value.
.Sp
Not passing a defined interval causes the previous interval setting to be
re-used unless the timer is reset and an end_time has been set
(an exception is thrown if no interval has been set).
.Sp
Not passing a defined current time value causes the current time to be used.
.Sp
Passing a current time value is useful if you happen to have a time value
lying around or if you want to make sure that several timers are started
with the same concept of start time.  You might even need to lie to an
IPC::Run::Timer, occasionally.
.IP "start_time" 4
.IX Item "start_time"
Sets/gets the start time, in seconds since the epoch.  Setting this manually
is a bad idea, it's better to call \*(L"start\*(R"() at the correct time.
.IP "state" 4
.IX Item "state"
.Vb 2
\&   $s = state $t;
\&   $t\->state( $s );
.Ve
.Sp
Get/Set the current state.  Only use this if you really need to transfer the
state to/from some variable.
Use \*(L"expire\*(R", \*(L"start\*(R", \*(L"reset\*(R", \*(L"is_expired\*(R", \*(L"is_running\*(R",
\&\*(L"is_reset\*(R".
.Sp
Note:  Setting the state to 'undef' to expire a timer will not throw an
exception.
.SH "TODO"
.IX Header "TODO"
use Time::HiRes; if it's present.
.PP
Add detection and parsing of [[[\s-1HH:\s0]MM:]SS formatted times and intervals.
.SH "AUTHOR"
.IX Header "AUTHOR"
Barrie Slaymaker <barries@slaysys.com>