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.
Register the start of a long-running asynchronous lookup operation.
$obj is a hash reference containing the following items:
A key string,
unique to this lookup.
This is what is reported in debug messages,
used as the key for get_lookup(),
etc.
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.
A string,
typically one word,
used to describe the type of lookup in log messages,
such as DNSBL,
MX,
TXT.
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.
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 'ABORTING' or 'FINISHED'.
The code reference will be called with one argument,
the $ent object.
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.
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.
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.
$obj is returned by this method.
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().
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().
Log sorted timing for all completed 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.
Abort any remaining lookups.
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.
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.
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.
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.
