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