Mail::SpamAssassin::AsyncLoop - scanner asynchronous event loop
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.
start_lookup($obj)
$obj
is a hash reference containing the following items:
get_lookup()
, etc.
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
.
DNSBL
, MX
, TXT
.
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.
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.
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.
$obj
is returned by this method.
get_lookup($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()
.
get_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()
.
log_lookups_timing()
complete_lookups()
If there are no lookups remaining, or if too long has elapsed since any results
were returned, 1
is returned, otherwise 0
.
abort_remaining_lookups()
$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.
report_id_complete($id,$key,$key,$timestamp)
$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.
last_poll_responses_time()
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.