NAME

Mail::SpamAssassin::Timeout - safe, reliable timeouts in perl

SYNOPSIS

    # non-timeout code...

    my $t = Mail::SpamAssassin::Timeout->new({ secs => 5 });
    
    $t->run(sub {
        # code to run with a 5-second timeout...
    });

    if ($t->timed_out()) {
        # do something...
    }

    # more non-timeout code...

This module provides a safe, reliable and clean API to provide alarm(2)-based timeouts for perl code.

Note that $SIG{ALRM} is used to provide the timeout, so this will not interrupt out-of-control regular expression matches.

Nested timeouts are supported.

my $t = Mail::SpamAssassin::Timeout->new({ ... options ... });: Constructor. Options include:
$t->run($coderef): Run a code reference within the currently-defined timeout.; The timeout is as defined by the secs parameter to the constructor.; Returns whatever the subroutine returns, or undef on timeout. If the timer times out, $t-<gttimed_out()> will return 1.; Time elapsed is not cumulative; multiple runs of run will restart the timeout from scratch.
$t->run_and_catch($coderef): Run a code reference, as per $t-<gtrun()>, but also catching any die() calls within the code reference.; Returns undef if no die() call was executed and $@ was unset, or the value of $@ if it was set. (The timeout event doesn't count as a die().)
$t->timed_out(): Returns 1 if the most recent code executed in run() timed out, or undef if it did not.
$t->reset(): If called within a run() code reference, causes the current alarm timer to be reset to its starting value.