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->start_lookup($ent, $master_deadline)
           Register  the  start  of  a  long-running  asynchronous  lookup  operation.  $ent is a hash reference
           containing the following items:

           key (required)
               A key string, unique to this lookup.  This is what is reported in debug messages, used as the key
               for "get_lookup()", etc.

           id (required)
               An ID string, also unique to this lookup.  Typically, this is the DNS packet ID  as  returned  by
               DnsResolver's  "bgsend" method.  Sadly, the Net::DNS architecture forces us to keep a separate ID
               string for this task instead of reusing "key" --  if  you  are  not  using  DNS  lookups  through
               DnsResolver, it should be OK to just reuse "key".

           type (required)
               A  string,  typically  one  word,  used  to  describe the type of lookup in log messages, such as
               "DNSBL", "MX", "TXT".

           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.

           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.

           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 is returned by this method, with its contents augmented by additional information.

       $ent = $async->bgsend_and_start_lookup($domain, $type, $class, $ent, $cb, %options)
           A  common  idiom:  calls  "bgsend", followed by a call to "start_lookup", returning the argument $ent
           object as modified by "start_lookup" and filled-in with a query ID.

       $ent = $async->get_lookup($key)
           Retrieve the pending-lookup object for the given key $key.

           If the lookup is complete, this will return "undef".

           Note that a lookup is still considered "pending" until "complete_lookups()" is called, even if it has
           been reported as complete via "set_response_packet()".

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

perl v5.34.0                                       2023-03-23                 Mail::SpamAssassin::AsyncLoop(3pm)