.\" 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
.\" ========================================================================
.\"
.IX Title "Mail::SpamAssassin::Timeout 3"
.TH Mail::SpamAssassin::Timeout 3 "2015-04-29" "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"
Mail::SpamAssassin::Timeout \- safe, reliable timeouts in perl
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    # non\-timeout code...
\&
\&    my $t = Mail::SpamAssassin::Timeout\->new({ secs => 5, deadline => $when });
\&    
\&    $t\->run(sub {
\&        # code to run with a 5\-second timeout...
\&    });
\&
\&    if ($t\->timed_out()) {
\&        # do something...
\&    }
\&
\&    # more non\-timeout code...
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides a safe, reliable and clean \s-1API\s0 to provide
\&\f(CWalarm(2)\fR\-based timeouts for perl code.
.PP
Note that \f(CW$SIG{ALRM}\fR is used to provide the timeout, so this will not
interrupt out-of-control regular expression matches.
.PP
Nested timeouts are supported.
.SH "PUBLIC METHODS"
.IX Header "PUBLIC METHODS"
.ie n .IP "my $t = Mail::SpamAssassin::Timeout\->new({ ... options ... });" 4
.el .IP "my \f(CW$t\fR = Mail::SpamAssassin::Timeout\->new({ ... options ... });" 4
.IX Item "my $t = Mail::SpamAssassin::Timeout->new({ ... options ... });"
Constructor.  Options include:
.RS 4
.ie n .IP "secs => $seconds" 4
.el .IP "secs => \f(CW$seconds\fR" 4
.IX Item "secs => $seconds"
time interval, in seconds. Optional; if neither \f(CW\*(C`secs\*(C'\fR nor \f(CW\*(C`deadline\*(C'\fR is
specified, no timeouts will be applied.
.ie n .IP "deadline => $unix_timestamp" 4
.el .IP "deadline => \f(CW$unix_timestamp\fR" 4
.IX Item "deadline => $unix_timestamp"
Unix timestamp (seconds since epoch) when a timeout is reached in the latest.
Optional; if neither \fBsecs\fR nor \fBdeadline\fR is specified, no timeouts will
be applied. If both are specified, the shorter interval of the two prevails.
.RE
.RS 4
.RE
.ie n .IP "$t\->run($coderef)" 4
.el .IP "\f(CW$t\fR\->run($coderef)" 4
.IX Item "$t->run($coderef)"
Run a code reference within the currently-defined timeout.
.Sp
The timeout is as defined by the \fBsecs\fR and \fBdeadline\fR parameters
to the constructor.
.Sp
Returns whatever the subroutine returns, or \f(CW\*(C`undef\*(C'\fR on timeout.
If the timer times out, \f(CW\*(C`$t\-<gt\*(C'\fR\fItimed_out()\fR> will return \f(CW1\fR.
.Sp
Time elapsed is not cumulative; multiple runs of \f(CW\*(C`run\*(C'\fR will restart the
timeout from scratch. On the other hand, nested timers do observe outer
timeouts if they are shorter, resignalling a timeout to the level which
established them, i.e. code running under an inner timer can not exceed
the time limit established by an outer timer. When restarting an outer
timer on return, elapsed time of a running code is taken into account.
.ie n .IP "$t\->run_and_catch($coderef)" 4
.el .IP "\f(CW$t\fR\->run_and_catch($coderef)" 4
.IX Item "$t->run_and_catch($coderef)"
Run a code reference, as per \f(CW\*(C`$t\-<gt\*(C'\fR\fIrun()\fR>, but also catching any
\&\f(CW\*(C`die()\*(C'\fR calls within the code reference.
.Sp
Returns \f(CW\*(C`undef\*(C'\fR if no \f(CW\*(C`die()\*(C'\fR call was executed and \f(CW$@\fR was unset, or the
value of \f(CW$@\fR if it was set.  (The timeout event doesn't count as a \f(CW\*(C`die()\*(C'\fR.)
.ie n .IP "$t\->\fItimed_out()\fR" 4
.el .IP "\f(CW$t\fR\->\fItimed_out()\fR" 4
.IX Item "$t->timed_out()"
Returns \f(CW1\fR if the most recent code executed in \f(CW\*(C`run()\*(C'\fR timed out, or
\&\f(CW\*(C`undef\*(C'\fR if it did not.
.ie n .IP "$t\->\fIreset()\fR" 4
.el .IP "\f(CW$t\fR\->\fIreset()\fR" 4
.IX Item "$t->reset()"
If called within a \f(CW\*(C`run()\*(C'\fR code reference, causes the current alarm timer
to be restored to its original setting (useful after our alarm setting was
clobbered by some underlying module).