| Mail::SpamAssassin::AsyncLoop(3pm) - phpMan
Mail::SpamAssassin::AsyncLoop(3User Contributed Perl DocumentatMail::SpamAssassin::AsyncLoop(3pm)
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 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.
perl v5.20.1 2014-02-07 Mail::SpamAssassin::AsyncLoop(3pm)
|