---
name: "Mail::SpamAssassin::AsyncLoop"
section: "3pm"
platform: "linux"
package: "spamassassin"
version: "4.0.2-3"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/Mail::SpamAssassin::AsyncLoop"
---

# Mail::SpamAssassin::AsyncLoop(3pm)

scanner asynchronous event loop

## NAME

Mail::SpamAssassin::AsyncLoop - scanner asynchronous event loop

## DESCRIPTION

An asynchronous event loop used for long-running operations, performed "in the background" during the **Mail::SpamAssassin::check()** scan operation, such as DNS blocklist lookups.

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

  Merges duplicate queries automatically, only launches one and calls all related callbacks on answer.

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

    - $ent-\>{YOUR\_OWN\_ITEM}

      Any other custom values/objects that you want to pass on to the answer callback.

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

- $ent = $async-\>get\_lookup($key)

  DEPRECATED since 4.0.0. Do not use.

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

- $async-\>set\_response\_packet($id, $pkt, $key, $timestamp)

  For internal use, do not call from plugins.

  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.

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