Mail::SpamAssassin::AsyncLoop
Mail::SpamAssassin::AsyncLoop
NAMEDESCRIPTION
METHODS
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 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.
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.
$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()".
$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; 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 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.
$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_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.
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
