Mail::SpamAssassin::AsyncLoop(3)               User Contributed Perl Documentation              Mail::SpamAssassin::AsyncLoop(3)



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
       $obj = $async->start_lookup($obj)
           Register the start of a long-running asynchronous lookup operation. $obj 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".

           poll_callback (optional)
               A code reference, which will be called periodically during the background-processing period.  If you will be
               performing an async lookup on a non-DNS-based service, you will need to implement this so that it checks for new
               responses and calls "set_response_packet()" or "report_id_complete()" as appropriate.   DNS-based lookups can
               leave it undefined, since DnsResolver::poll_responses() will be called automatically anyway.

               The code reference will be called with one argument, the $ent object.

           completed_callback (optional)
               A code reference which will be called when an asynchronous task (e.g. a DNS lookup) is completed, either
               normally, or aborted, e.g. by a timeout.

               When a task has been reported as completed via "set_response_packet()" the response (as provided to
               "set_response_packet()") is stored in $ent->{response_packet} (possibly undef, its semantics is defined by the
               caller). When completion is reported via "report_id_complete()" or a task was aborted, the
               $ent->{response_packet} is guaranteed to be undef.  If it is necessary to distinguish between the last two cases,
               the $ent->{status} may be examined for a string 'ABORTING' or 'FINISHED'.

               The code reference will be called with one argument, the $ent object.

           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.

           $obj is returned by this method.

       $obj = $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()" or "report_id_complete()".

       @objs = $async->get_pending_lookups()
           Retrieve the lookup objects for all pending lookups.

           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()" or "report_id_complete()".

       $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; if they are, their <completed_callback> is called
           with the entry object for that lookup.

           If there are no lookups remaining, or if too long 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 futher
           information about the query is accessible.

           If this was called, $pkt will be available in the "completed_callback" function as "$ent-<gt"{response_packet}>.

           One or the other of "set_response_packet()" or "report_id_complete()" should be called, but not both.

       $async->report_id_complete($id,$key,$key,$timestamp)
           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.12.4                                               2011-06-06                           Mail::SpamAssassin::AsyncLoop(3)