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-<gt"{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.