Mail::...Timeout(3pm)

💖 Mail::SpamAssassin::Timeout — the manual, but make it cute 💖

okay bestie, gather round, because this is Mail::...Timeout(3pm) from the User Contributed Perl Documentation shelf, and she is lowkey iconic. she's the module you call when you want your Perl code to have a bedtime and you want it to actually, fr fr, respect that bedtime. 🫶

---

✨ NAME ✨

Mail::SpamAssassin::Timeout — safe, reliable timeouts in perl. that's the whole vibe. safety, reliability, and perl. 💅

---

🌸 SYNOPSIS 🌸

bestie here's the whole flow, copy-paste ready, no cap:

# 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...

see how it's giving main character? you make a timer, you hand it a coderef, you find out if it ghosted you. 😭

---

🦋 DESCRIPTION 🦋

so this module hands you a safe, reliable, and clean API that gives perl code timeouts built on alarm(2). yes, the real alarm(2). she's not faking it. ✨

heads up bestie: this thing uses $SIG{ALRM} to do its timeout magic, which means it will not interrupt out-of-control regular expression matches. like, if your regex is in its villain era, this timeout simply cannot touch it. 💀

nested timeouts are supported. timers within timers, turducken style, slay. 👑

---

👑 PUBLIC METHODS 👑

💜 my $t = Mail::SpamAssassin::Timeout->new({ ... options ... });

the constructor. she builds you a timeout object. the options include:

• secs => $seconds — the time interval, in seconds. optional! if you specify neither secs nor deadline, no timeouts will be applied at all. no timer, no drama. 🙈
• deadline => $unix_timestamp — a Unix timestamp (seconds since epoch) marking when a timeout is reached in the latest. optional! if neither secs nor deadline is specified, no timeouts will be applied. and if you specify both? the shorter interval of the two wins. periodt. 💅

🌈 $t->run($coderef)

run a code reference inside the currently-defined timeout. she wraps it up, she keeps an eye on it, she's your bodyguard. 🫶

the timeout is exactly what you defined with the secs and deadline parameters to the constructor. no surprises.

returns whatever the subroutine returns, or undef on timeout. and if the timer times out, $t->timed_out() will return 1. caught in 4k. ✨

time elapsed is not cumulative — multiple runs of run will restart the timeout from scratch every single time. fresh start, new me, it's giving rebirth arc. 🦋

on the other hand, nested timers do observe outer timeouts if those 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. the hierarchy is real and it is respected. 👑

when restarting an outer timer on return, elapsed time of a running code is taken into account. she remembers. she's keeping receipts. 💅

🎀 $t->run_and_catch($coderef)

runs a code reference, as per $t->run(), but also catching any die() calls within the code reference. like run but with emotional support. 😭

returns undef if no die() call was executed and $@ was unset, or the value of $@ if it was set.

little note bestie: the timeout event doesn't count as a die(). it's a whole different thing, don't mix them up. 🙈

⭐ $t->timed_out()

returns 1 if the most recent code executed in run() timed out, or undef if it did not. simple. clean. iconic. 💖

🧚 $t->reset()

if called within a run() code reference, this causes the current alarm timer to be restored to its original setting. super useful after our alarm setting was clobbered by some underlying module. like, rude of them, but okay, we fix it. 💅

---

and that's the whole page bestie!! safe timeouts, nested timeouts, no regex interruption, and a reset() for when the vibes get clobbered. 🌸

this little beauty is perl v5.40.1, dated 2026-07-23, and she belongs to Mail::...Timeout(3pm). mwah, love that for her, go forth and timeout responsibly. 💜✨