Mail::SpamAssassin::AsyncLoop
Mail::SpamAssassin::AUserLContributed Perl DoMail::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 opera-
tion, such as DNS blocklist lookups.
METHODS
$obj = $async->start_lookup($obj)
Register the start of a long-running asynchronous lookup opera-
tion. $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 appropri-
ate. DNS-based lookups can leave it undefined, since DnsRe-
solver::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 ’ABORT-
ING’ 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.
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 time-
out_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 set-
table by a configuration variable rbl_timeout.
If a value of the timeout_initial parameter is below time-
out_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_ini-
tial.
$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 "com-
plete_lookups()" is called, even if it has been reported as com-
plete 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 "com-
plete_lookups()" is called, even if it has been reported as com-
plete 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 com-
pleted; 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 iden-
tifies 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_call-
back" function as "$ent-<gt"{response_packet}>.
One or the other of "set_response_packet()" or "report_id_com-
plete()" 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_com-
plete()" 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.8.8 2008-01-05 Mail::SpamAssassin::AsyncLoop(3)
