Mail::...yncLoop(3pm)

🎀 NAME 🎀

so the manual name is Mail::SpamAssassin::AsyncLoop(3pm) — it's living in your friendly neighborhood User Contributed Perl Documentation, and bestie, it's literally the scanner's asynchronous event loop 💅

---

🦋 DESCRIPTION 🦋

It's an async event loop, okay? An asynchronous event loop. The whole point is doing long-running stuff "in the background" while the Mail::SpamAssassin::check() scan operation is happening, so nobody's just standing there waiting. Think DNS blocklist lookups — the classic slow-boy behavior that needed a glow-up. ✨

---

✨ METHODS ✨

• $ent = $async->bgsend_and_start_lookup($name, $type, $class, $ent, $cb, %options)

Launch async DNS lookups. This is the only official method supported for plugins since version 4.0.0. Do not use bgsend and start_lookup separately, bestie, I'm so serious. 🙈

It merges duplicate queries automatically — only launches one, then calls all the related callbacks on answer. Efficiency queen 👑

$name (required)

Name to query.

$type (required)

Type to query, A, TXT, NS, etc.

$class (required/deprecated)

Deprecated, ignored, set as undef.

$ent is a required hash reference containing the following items:

$ent->{rulename} (required)

The rulename that started and/or depends on this query. Required for rule dependencies to work correctly. Can be a single rulename, or array of multiple rulenames.

$ent->{type} (optional)

A string, typically one word, used to describe the type of lookup in log messages, such as "DNSBL", "URIBL-A". If not defined, default is value of $type.

$ent->{zone} (optional)

A zone specification (typically a DNS zone name — e.g. host, domain, or RBL) which may be used as a key to look up per-zone settings. No semantics on this parameter is imposed by this module. Currently used to fetch by-zone timeouts (from rbl_timeout setting). Defaults to $name.

$ent->{timeout_initial} (optional)

An initial value of elapsed time for which we are willing to wait for a response (time in seconds, floating point value is allowed). When elapsed time since a query started exceeds the timeout value and there are no other queries to wait for, the query is aborted. The actual timeout value ranges from timeout_initial and gradually approaches timeout_min (see next parameter) as the number of already completed queries approaches the number of all queries started.

If a caller does not explicitly provide this parameter or its value is undefined, a default initial timeout value is settable by a configuration variable rbl_timeout.

If a value of the timeout_initial parameter is below timeout_min, the initial timeout is set to timeout_min.

$ent->{timeout_min} (optional)

A lower bound (in seconds) to which the actual timeout approaches as the number of queries completed approaches the number of all queries started. Defaults to 0.2 * timeout_initial.

$ent->{key}, $ent->{id} (deprecated)

Deprecated, ignored, automatically generated since 4.0.0. not me still listing them, but okay 💀

$ent->{YOUR_OWN_ITEM}

Any other custom values/objects that you want to pass on to the answer callback. Go off, customize away 🫶

$cb (required)

Callback function for answer, called as $cb->($ent, $pkt). $ent is the same object that bgsend_and_start_lookup was called with. $pkt is the packet object for the response, Net::DNS:RR objects can be found from $pkt->answer.

%options (required)

Hash of options. Only supported and required option is master_deadline:

master_deadline => $pms->{master_deadline}

• $ent = $async->start_lookup($ent, $master_deadline)

DIRECT USE DEPRECATED since 4.0.0, please use bgsend_and_start_lookup. like please. 🥺

• $ent = $async->get_lookup($key)

DEPRECATED since 4.0.0. Do not use. that's it, that's the whole vibe 🌸

• $async->log_lookups_timing()

Log sorted timing for all completed lookups.

• $alldone = $async->complete_lookups()

Perform a poll of the pending lookups, to see if any are completed. Callbacks on completed queries will be called from poll_responses().

If there are no lookups remaining, or if too much time has elapsed since any results were returned, 1 is returned, otherwise 0.

• $async->abort_remaining_lookups()

Abort any remaining lookups. bye bestie 👋

• $async->set_response_packet($id, $pkt, $key, $timestamp)

For internal use, do not call from plugins. (iykyk — if you're a plugin, back away slowly 🚫)

Register a "response packet" for a given query. $id is the ID for the query, and must match the "id" supplied in start_lookup(). $pkt is the packet object for the response. A parameter $key identifies an entry in a hash %{$self->{pending_lookups}} where the object which spawned this query can be found, and through which further information about the query is accessible.

$pkt may be undef, indicating that no response packet is available, but a query has completed (e.g. was aborted or dismissed) and is no longer "pending".

The DNS resolver's response packet $pkt will be made available to a callback subroutine through its argument as well as in "$ent->{response_packet}".

• $async->report_id_complete($id,$key,$key,$timestamp)

DEPRECATED since 4.0.0. Do not use.

Legacy. Equivalent to $self->set_response_packet($id,undef,$key,$timestamp), i.e. providing undef as a response packet. Register that a query has completed and is no longer "pending". $id is the ID for the query, and must match the "id" supplied in start_lookup().

One or the other of set_response_packet() or report_id_complete() should be called, but not both. pick a lane, babe 💅

• $time = $async->last_poll_responses_time()

Get the time of the last call to poll_responses() (which is called from complete_lookups(). If poll_responses() was never called or abort_remaining_lookups() has been called last_poll_responses_time() will return undef.

---

that's the whole page, no notes, every single option and every single deprecation accounted for 💖

and that's a wrap, bestie! this iconic little number came to you from perl v5.40.1, dated 2026-07-23 — slay, stay async, and don't call the deprecated stuff 🌈👑