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 the lookup has been reported as complete via
"set_response_packet()" or "report_id_complete()".
The code reference will be called with one argument, the $ent object.
$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()".
$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)
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.
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)
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->get_last_start_lookup_time()
Get the time of the last call to "start_lookup()". If "start_lookup()" was never called or
"abort_remaining_lookups()" has been called "get_last_start_lookup_time()" will return undef.
perl v5.8.8 2007-05-21 Mail::SpamAssassin::AsyncLoop(3)
|